Gebruiksdocumentatie opgeven voor uw poorten

Overzicht

Door gebruiksdocumentatie voor poorten te bieden, kunnen gebruikers ze eenvoudig in hun projecten gebruiken. We raden u ten zeerste aan een usage bestand op te geven in de map van de poort (ports/<port name>/usage) waarin de minimale stappen worden beschreven die nodig zijn om te integreren met een buildsysteem.

Een gebruiksbestand opgeven

Als u gebruiksdocumentatie wilt opgeven, maakt u een tekstbestand met de naam usage in de installatiemap van share de poort. De aanbevolen methode is om de file(INSTALL ...) functie aan te roepen in portfile.cmake.

Voorbeeld:

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

Na het installeren van poorten detecteert vcpkg bestanden die naar ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage zijn geïnstalleerd en drukt vervolgens de gebruiksinstructies af.

Inhoudsformaat

Geef duidelijke instructies over het gebruik van het pakket. De inhoud moet beknopt, goed gestructureerd zijn en de minimale integratie van het buildsysteem benadrukken die nodig is voor het gebruik van de bibliotheek.

Wees duidelijk en beknopt over hoe u het pakket effectief kunt gebruiken. Vermijd overweldigende gebruikers met codefragmenten, opdrachtregelinstructies of configuratiedetails. Gebruik in plaats daarvan de "documentation" eigenschap in het poortbestandvcpkg.json, zodat gebruikers meer informatie over uw bibliotheek kunnen krijgen.

Gebruik de volgende sjablonen als patroon voor uw usage bestanden:

Pakketten met CMake-doelen:

<port> provides CMake targets:

  <instructions>

Bibliotheken met alleen headers:

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

  <instructions>

Voorbeeld van usage bestand

proj provides CMake targets:

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