Ange användningsdokumentation för dina portar

Översikt

Genom att tillhandahålla användningsdokumentation för portar kan användarna enkelt använda dem i sina projekt. Vi rekommenderar starkt att du tillhandahåller en usage fil i portens katalog (ports/<port name>/usage) som beskriver de minimala steg som krävs för att integrera med ett byggsystem.

Ange en användningsfil

Om du vill tillhandahålla användningsdokumentation skapar du en textfil med namnet usage i portens share installationskatalog. Den rekommenderade metoden är att anropa file(INSTALL ...) funktionen i portfile.cmake.

Till exempel:

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

När du har installerat portar identifierar vcpkg filer som är installerade i ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage och skriver ut deras användningsinstruktioner.

Innehållsformat

Ge tydliga instruktioner om hur du använder paketet. Innehållet ska vara koncist, välstrukturerat och betona den minsta byggsystemintegrering som krävs för att använda biblioteket.

Var tydlig och koncis om hur du använder paketet effektivt. Undvik att överväldiga användare med kodfragment, kommandoradsinstruktioner eller konfigurationsinformation. Använd "documentation" i stället egenskapen i portens vcpkg.json fil så att användarna kan lära sig mer om ditt bibliotek.

Använd följande mallar som ett mönster för dina usage filer:

Paket med CMake-mål:

<port> provides CMake targets:

  <instructions>

Bibliotek med endast rubrik:

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

  <instructions>

Exempel på usage fil

proj provides CMake targets:

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