Bereitstellen der Verwendungsdokumentation für Ihre Ports

Überblick

Die Bereitstellung von Verwendungsdokumentationen für Ports ermöglicht benutzern die einfache Einführung in ihre Projekte. Wir empfehlen dringend, eine usage Datei im Portverzeichnis (ports/<port name>/usage) bereitzustellen, die die minimalen Schritte beschreibt, die für die Integration in ein Buildsystem erforderlich sind.

Bereitstellen einer Verwendungsdatei

Um Verwendungsdokumentation bereitzustellen, erstellen Sie eine Textdatei mit dem Namen usage im Installationsverzeichnis des Ports share. 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 von Ports erkennt vcpkg Dateien, die nach ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage installiert sind, und zeigt ihre Verwendungsanweisungen.

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)