Bereitstellen der Verwendungsdokumentation für Ihre Ports

Überblick

Durch die Bereitstellung einer genauen Verwendungsdokumentation für Ports können Benutzer sie einfach in ihren Projekten übernehmen. vcpkg generiert automatisch Nutzungsinformationen, indem die von einem Port installierten Dateien überprüft werden. Stellen Sie nur eine benutzerdefinierte usage Datei bereit, wenn die generierten Nutzungsinformationen falsch oder unvollständig sind.

Führen Sie nach der Installation eines Ports aus vcpkg print-usage , um die Nutzungsinformationen zu überprüfen:

vcpkg print-usage <port>:<triplet>

Wenn der Port bereits eine benutzerdefinierte usage Datei installiert, können --generated Sie prüfen, was vcpkg ohne diese Datei generiert:

vcpkg print-usage --generated <port>:<triplet>

Bestätigen der generierten Nutzung

Wenn die generierten Verwendungsinformationen korrekt sind, installieren Sie eine leere usage-accurate Markierungsdatei:

file(TOUCH "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage-accurate")

Dieser Marker bestätigt, dass die generierten Anweisungen korrekt sind, sodass vcpkg die Warnung ausgelassen, dass die Anweisungen heuristisch generiert und möglicherweise falsch sind.

Vor dem Hinzufügen der Markierung können --affirm Sie eine Vorschau der generierten Ausgabe ohne Warnung anzeigen:

vcpkg print-usage --generated --affirm <port>:<triplet>

Bereitstellen einer Verwendungsdatei

Wenn generierte Nutzungsinformationen nicht ordnungsgemäß beschreiben, wie das Paket verwendet wird, erstellen Sie eine Textdatei usage namens im Portverzeichnis, und installieren Sie sie im Verzeichnis des share Ports. Die empfohlene Methode besteht darin, die file(INSTALL ...) Funktion in portfile.cmakeaufzurufen.

Beispiel:

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

Nach der Installation eines Ports erkennt vcpkg die installierte Datei und ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage druckt ihre Anweisungen, anstatt Nutzungsinformationen zu generieren.

Inhaltsformat

Stellen Sie klare Anweisungen zur Verwendung des Pakets bereit. Der Inhalt sollte präzise und gut strukturiert sein und die minimale für die Verwendung der Bibliothek erforderliche Build-System-Integration hervorheben.

Seien Sie klar und präzise darüber, wie Sie das Paket effektiv nutzen können. Vermeiden Sie, Benutzer mit Codeausschnitten, Befehlszeilenanweisungen oder Konfigurationsdetails zu überwältigen. Verwenden Sie stattdessen die "documentation" Eigenschaft in der Portdateivcpkg.json, damit Benutzer mehr über Ihre Bibliothek erfahren können.

Verwenden Sie die folgenden Vorlagen als Muster für Ihre usage Dateien:

Pakete mit CMake-Zielen:

<port> provides CMake targets:

  <instructions>

Nur-Header-Bibliotheken:

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

  <instructions>

Beispiel einer usage Datei

proj provides CMake targets:

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