Udostępnij za pośrednictwem

Podaj dokumentację użycia dla portów

  • Artykuł

Omówienie

Udostępnianie dokumentacji użycia portów umożliwia użytkownikom łatwe wdrażanie ich w swoich projektach. Zdecydowanie zachęcamy do udostępnienia usage pliku w katalogu portu (ports/<port name>/usage), który opisuje minimalne kroki niezbędne do integracji z systemem kompilacji.

Dostarczanie pliku użycia

Aby udostępnić dokumentację użycia, utwórz plik tekstowy o nazwie usage w katalogu instalacyjnym share portu. Zalecaną metodą jest wywołanie configure_file() funkcji w pliku portfile.cmake.

Na przykład:

configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)

Po zainstalowaniu portów narzędzie vcpkg wykrywa zainstalowane ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage pliki i wyświetla instrukcje użycia.

Format zawartości

Podaj jasne instrukcje dotyczące korzystania z pakietu. Zawartość powinna być zwięzła, dobrze ustrukturyzowana i podkreślać minimalną integrację systemu kompilacji wymaganą do korzystania z biblioteki.

Jasne i zwięzłe informacje na temat efektywnego korzystania z pakietu. Unikaj przytłaczających użytkowników z fragmentami kodu, instrukcjami wiersza polecenia lub szczegółami konfiguracji. Zamiast tego użyj "documentation" właściwości w pliku portuvcpkg.json, aby użytkownicy mogli dowiedzieć się więcej o bibliotece.

Użyj następujących szablonów jako wzorca dla plików usage :

Pakiety z miejscami docelowymi narzędzia CMake:

<port> provides CMake targets:

    <instructions>

Biblioteki tylko do nagłówka:

<port> is header-only and can be used from CMake via:

    <instructions>

usage Przykład pliku

proj provides CMake targets:

    find_package(PROJ CONFIG REQUIRED)
    target_link_libraries(main PRIVATE PROJ::proj)