Lernprogramm: Verpacken einer Bibliothek mit vcpkg

In diesem Lernprogramm erfahren Sie, wie Sie eine Bibliothek für vcpkg mithilfe einer benutzerdefinierten Überlagerung verpacken. Es wird empfohlen, das Lernprogramm zum Installieren und Verwenden von Paketen mit CMake zu lesen, bevor Sie fortfahren.

Voraussetzungen

• Ein Terminal
• einen C++-Compiler
• CMake
• Einguss

1 – Einrichten von vcpkg

1. Klonen des Repositorys

   Der erste Schritt besteht darin, das vcpkg-Repository von GitHub zu klonen. Das Repository enthält Skripts zum Abrufen der ausführbaren Datei vcpkg und eine Registrierung kuratierter Open-Source-Bibliotheken, die von der vcpkg-Community verwaltet werden. Führen Sie dazu Folgendes aus:

   git clone https://github.com/microsoft/vcpkg.git
   

   Die kuratierte vcpkg-Registrierung ist eine Reihe von mehr als 2.000 Open-Source-Bibliotheken. Diese Bibliotheken wurden durch die kontinuierlichen Integrationspipelines von vcpkg validiert, um gemeinsam zu funktionieren. Während das vcpkg-Repository nicht den Quellcode für diese Bibliotheken enthält, enthält es Rezepte und Metadaten zum Erstellen und Installieren in Ihrem System.

2. Ausführen des Bootstrap-Skripts

   Nachdem Sie das vcpkg-Repository geklont haben, navigieren Sie zum vcpkg Verzeichnis, und führen Sie das Bootstrap-Skript aus:

   cd vcpkg && bootstrap-vcpkg.bat
   

   cd vcpkg; .\bootstrap-vcpkg.bat
   

   cd vcpkg && ./bootstrap-vcpkg.sh
   

   Das Bootstrap-Skript führt erforderliche Prüfungen durch und lädt die ausführbare Datei vcpkg herunter.

   Das ist alles! vcpkg ist eingerichtet und einsatzbereit.

2 – Konfigurieren der VCPKG_ROOT Umgebungsvariable

Führen Sie die folgenden Befehle aus, um die VCPKG_ROOT Umgebungsvariablen festzulegen:

export VCPKG_ROOT=/path/to/vcpkg
export PATH=$VCPKG_ROOT:$PATH

set "VCPKG_ROOT=C:\path\to\vcpkg"
set PATH=%VCPKG_ROOT%;%PATH%

$env:VCPKG_ROOT="C:\path\to\vcpkg"
$env:PATH="$env:VCPKG_ROOT;$env:PATH"

Die Einstellung VCPKG_ROOT teilt vcpkg mit, wo sich Ihre vcpkg-Instanz befindet. Das Hinzufügen zu PATH stellt sicher, dass Sie vcpkg-Befehle direkt über die Shell ausführen können.

3 – Einrichten der benutzerdefinierten Überlagerung

1. Erstellen Sie ein neues Verzeichnis custom-overlay neben dem Projekt, das Hello WorldSie im Lernprogramm zum Installieren und Verwenden von Paketen mit CMake erstellt haben.
2. custom-overlay Erstellen Sie im Verzeichnis einen Ordner mit dem Namen vcpkg-sample-library.

4 – Einrichten der Portdateien

Erstellen Sie zunächst die vcpkg.json Datei im custom-overlay\vcpkg-sample-library Ordner mit dem folgenden Inhalt:

{
  "name": "vcpkg-sample-library",
  "version": "1.0.2",
  "homepage": "https://github.com/microsoft/vcpkg-docs/tree/cmake-sample-lib",
  "description": "A sample C++ library designed to serve as a foundational example for a tutorial on packaging libraries with vcpkg.",
  "license": "MIT",
  "dependencies": [
    {
      "name" : "vcpkg-cmake",
      "host" : true
    },
    {
      "name" : "vcpkg-cmake-config",
      "host" : true
    },
    "fmt"
  ]
}

Die vcpkg.json Datei dient als Manifest, das Metadaten und Abhängigkeiten für eine C++-Bibliothek definiert und vcpkg mit den erforderlichen Informationen zum Erstellen, Installieren und Verwalten des Pakets bereitstellt.

• name: Gibt den Namen der Bibliothek an. Dies wird als Paketbezeichner verwendet.
• version: Gibt die Versionsnummer der Bibliothek an.
• homepage: DIE URL zur Homepage des Projekts, häufig das Repository. Nützlich für diejenigen, die mehr wissen oder mitwirken möchten.
• description: Kurzer Text, der beschreibt, was die Bibliothek tut. Dies richtet sich an Dokumentation und Benutzer.
• license: Gibt die Lizenz an, unter der die Bibliothek verteilt wird.
• dependencies: Ein Array mit der Liste der Abhängigkeiten, die die Bibliothek benötigt.
• name: vcpkg-cmake: Spezifiziert eine Abhängigkeit von vcpkg-cmake, die CMake-Funktionen und Makros bereitstellt, die häufig in vcpkg-Ports verwendet werden.
• host: true: Gibt an, dass es vcpkg-cmake sich um eine Hostabhängigkeit handelt, was bedeutet, dass es zum Erstellen des Pakets erforderlich ist, aber nicht für die Verwendung.
• name: vcpkg-cmake-config: Spezifiziert eine Abhängigkeit von vcpkg-cmake-config, die bei der Nutzung von CMake-Konfigurationsskripten hilft.
• fmt: Gibt eine Laufzeitabhängigkeit von der fmt Bibliothek an. Dies bedeutet, dass fmt sowohl für das Erstellen als auch für die Verwendung des Pakets erforderlich ist.

Weitere Informationen vcpkg.jsonfinden Sie in der folgenden Dokumentation zu Manifesten.

Erstellen Sie nun die usage Datei im custom-overlay\vcpkg-sample-library Verzeichnis mit dem folgenden Inhalt:

vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

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. Um die richtigen Gebrauchsanweisungen zu bestimmen, wird empfohlen, die Anweisungen des Upstream zu befolgen. Für den Fall, dass der Upstream keine Nutzungsinformationen bereitstellt, kann es notwendig sein, sein Build-System zu durchsuchen, um die exportierten Ziele zu finden.

Weitere Anleitungen finden Sie unter Behandeln von Verwendungsdateien

Erstellen Sie schließlich die portfile.cmake Datei im custom-overlay\vcpkg-sample-library Verzeichnis mit dem folgenden Inhalt:

vcpkg_check_linkage(ONLY_STATIC_LIBRARY)

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO Microsoft/vcpkg-docs
    REF "${VERSION}"
    SHA512 0  # This is a temporary value. We will modify this value in the next section.
    HEAD_REF cmake-sample-lib
)

vcpkg_cmake_configure(
    SOURCE_PATH "${SOURCE_PATH}"
)

vcpkg_cmake_install()

vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib")

file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

Durch diese Anweisung wird definiert, wie eine bestimmte C++-Bibliothek mit vcpkg von GitHub heruntergeladen, erstellt, installiert und verpackt wird.

• vcpkg_check_linkage(ONLY_STATIC_LIBRARY): Gibt an, dass nur statische Verknüpfungen für dieses Paket unterstützt werden.
• vcpkg_from_github: Startet die Funktion, um den Quellcode aus einem GitHub-Repository herunterzuladen.
  • OUT_SOURCE_PATH SOURCE_PATH: Legt das Verzeichnis fest, in dem der Quellcode extrahiert wird.
  • REPO Microsoft/vcpkg-docs: Das GitHub-Repository, das den Quellcode enthält.
  • REF "${VERSION}": Die Version des Quellcodes, der heruntergeladen werden soll.
  • SHA512 0: Platzhalter für den SHA-512-Hash des Quellcodes für die Integritätsüberprüfung.
  • HEAD_REF main: Gibt die Standardbranch für das Repository an.
• vcpkg_cmake_configure: Konfiguriert das Projekt mit CMake und richtet den Build ein.
  • SOURCE_PATH "${SOURCE_PATH}": Der Pfad zum zuvor heruntergeladenen Quellcode.
• vcpkg_cmake_install(): Erstellt und installiert das Paket mit CMake.
• vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): Korrigiert die CMake-Paketkonfigurationsdateien, um mit vcpkg kompatibel zu sein.
• file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): Löscht das Includeverzeichnis aus der Debuginstallation, um Überlappungen zu verhindern.
• file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" ...): Kopiert eine Verwendungsanweisungsdatei in das Freigabeverzeichnis des Pakets.
• vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE"): Installiert die LICENSE-Datei im Freigabeverzeichnis des Pakets und benennt sie in 'copyright' um.

Weitere Informationen finden Sie im Betreuerhandbuch.

5 – Sha512 aktualisieren für portfile.cmake

Führen Sie folgenden Befehl aus:

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

Sie erhalten eine lange Fehlermeldung. Scannen Sie die Ausgabe, bis Sie Folgendes finden:

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

Kopieren Sie den tatsächlichen Hash 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417 und ersetzen Sie den Wert in SHA512 durch dessen Wert in portfile.cmake.

Führen Sie den Installationsbefehl erneut aus:

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

Computing installation plan...
The following packages will be built and installed:
    vcpkg-sample-library:x64-windows -> 1.0.2 -- C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
Detecting compiler hash for triplet x64-windows...
Restored 0 package(s) from C:\Users\dev\AppData\Local\vcpkg\archives in 174 us. Use --debug to see more details.
Installing 1/1 vcpkg-sample-library:x64-windows...
Building vcpkg-sample-library:x64-windows...
-- Installing port from location: C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
-- Note: vcpkg-sample-library only supports static library linkage. Building static library.
-- Using cached Microsoft-vcpkg-docs-1.0.2.tar.gz.
-- Cleaning sources at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean. Use --editable to skip cleaning for the packages you specify.
-- Extracting source C:/Users/dev/demo/vcpkg/downloads/Microsoft-vcpkg-docs-1.0.2.tar.gz
-- Using source at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean
-- Configuring x64-windows
-- Building x64-windows-dbg
-- Building x64-windows-rel
-- Installing: C:/Users/dev/demo/vcpkg/packages/vcpkg-sample-library_x64-windows/share/vcpkg-sample-library/usage
-- Installing: C:/Users/dev/demo/vcpkg/packages/vcpkg-sample-library_x64-windows/share/vcpkg-sample-library/copyright
-- Performing post-build validation
Stored binaries in 1 destinations in 94 ms.
Elapsed time to handle vcpkg-sample-library:x64-windows: 6.1 s
Total install time: 6.1 s
vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

6 - Port-Build überprüfen

Um zu überprüfen, ob die Bibliothek korrekt gebaut und gelinkt wird, fügen Sie eine neue Abhängigkeit zu dem helloworld Projekt hinzu, das im TutorialPakete installieren erstellt wurde. Nehmen Sie die folgenden Änderungen an den Manifest- und Konfigurationsdateien des Projekts vor.

Ändern Sie helloworld/vcpkg.json, um eine Abhängigkeit von vcpkg-sample-library hinzuzufügen.

{
    "dependencies": [
        "fmt",
        "vcpkg-sample-library"
    ]
}

Ändern Sie helloworld/vcpkg-configuration.json , um den Ordner overlay-ports einzuschließen, der den neuen Port enthält:

{
  "default-registry": {
    "kind": "git",
    "baseline": "45f6e57d3e10ad96b7db206cf7888f736ba5aa61",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/microsoft/vcpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ],
  "overlay-ports": [
    "../custom-overlay"
  ]
}

Als Nächstes ändern Sie helloworld/CMakeLists.txt und helloworld/main.cpp, um die neue Abhängigkeit zu verwenden.

Ändern Sie helloworld/CMakeLists.txt mit folgendem Inhalt:

cmake_minimum_required(VERSION 3.10)

project(HelloWorld)

find_package(fmt CONFIG REQUIRED)
find_package(my_sample_lib CONFIG REQUIRED)  # Add this line

add_executable(HelloWorld helloworld.cpp)

target_link_libraries(HelloWorld PRIVATE fmt::fmt)
target_link_libraries(HelloWorld PRIVATE my_sample_lib::my_sample_lib)  # Add this line

Ändern Sie main.cpp mit folgendem Inhalt:

#include "my_sample_lib.h"  // Replace #include <fmt/core.h> with "my_sample_lib.h"

int main()
{
    greet("vcpkg!");  // Replace fmt::print("Hello World!\n) with this line
    return 0;
}

Konfigurieren, Erstellen und Ausführen der Anwendung.

1. Konfigurieren Sie den Build mit CMake:

cmake --preset=default

2. Erstellen Sie das Projekt:

cmake --build build

3. Führen Sie die Anwendung aus:

./build/HelloWorld

Der Pfad zur ausführbaren Datei Ihres Projekts kann unterschiedlich sein, z. B.: ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Nächste Schritte

Nachdem das vcpkg-sample-library Paket nun als Port gepackt wurde, besteht der nächste Schritt darin, es der kuratierten vcpkg-Registrierung hinzuzufügen. Weitere Informationen finden Sie unter Hinzufügen von Ports zur vcpkg-Registrierung.

Weitere Informationen finden Sie unter:

• Anschlüsse
• Leitfaden für Betreuer