Podaj dokumentację użycia dla portów

Przegląd

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 funkcji file(INSTALL ...) w portfile.cmake.

Przykład:

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")

Po zainstalowaniu portów narzędzie vcpkg wykrywa pliki zainstalowane w ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage i wyświetla instrukcje ich 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łaczania użytkowników fragmentami kodu, poleceniami wiersza lub szczegółami konfiguracji. Zamiast tego, użyj właściwości "documentation" w pliku portuvcpkg.json, aby użytkownicy mogli dowiedzieć się więcej o twojej 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 nagłówkowe

<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)