Lernprogramm: Verpacken einer Bibliothek mit vcpkg

  • Artikel

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
  • Git

Hinweis

Unter Windows verwendet dieses Lernprogramm MSVC von Visual Studio als Compiler für die C++-Entwicklung.

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 von kuratierten Open-Source-Bibliotheken Standard von der vcpkg-Community enthalten. 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 von den kontinuierlichen Integrationspipelines von vcpkg überprüft, um zusammenzuarbeiten. 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

Hinweis

Das Festlegen von Umgebungsvariablen mit dem export Befehl wirkt sich nur auf die aktuelle Shellsitzung aus. Um diese Änderung dauerhaft in Sitzungen vorzunehmen, fügen Sie den export Befehl zum Profilskript Ihrer Shell hinzu (z. B ~/.bashrc . oder ~/.zshrc).

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

Hinweis

Das Festlegen von Umgebungsvariablen auf diese Weise wirkt sich nur auf die aktuelle Terminalsitzung aus. Um diese Änderungen in allen Sitzungen dauerhaft vorzunehmen, legen Sie sie über den Bereich "Windows System Environment Variables" fest.

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

Hinweis

Das Festlegen von Umgebungsvariablen auf diese Weise wirkt sich nur auf die aktuelle Terminalsitzung aus. Um diese Änderungen in allen Sitzungen dauerhaft vorzunehmen, legen Sie sie über den Bereich "Windows System Environment Variables" fest.

Die Einstellung VCPKG_ROOT teilt vcpkg mit, wo sich Ihre vcpkg-Instanz befindet. PATH Durch das Hinzufügen wird sichergestellt, 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-cmakeGibt 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-configGibt eine Abhängigkeit an vcpkg-cmake-config, die bei der Verwendung von CMake-Konfigurationsskripts unterstützt wird.
  • 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 Verwendungsanweisungen zu ermitteln, empfiehlt es sich, die Anweisungen des Upstreams zu befolgen. Falls upstream keine Nutzungsinformationen bereitstellt, kann es erforderlich sein, das Buildsystem 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 "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)

Dadurch portfile wird definiert, wie sie eine bestimmte C++-Bibliothek mithilfe von vcpkg von GitHub herunterladen, erstellen, installieren und verpacken.

  • 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 JavierMatosD/vcpkg-sample-library: 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"): Behebt die Konfigurationsdateien des CMake-Pakets, die mit vcpkg kompatibel sind.
  • file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): Löscht das Includeverzeichnis aus der Debuginstallation, um Überlappungen zu verhindern.
  • file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...): Installiert die LICENSE-Datei im Freigabeverzeichnis des Pakets und benennt sie in das Urheberrecht um.
  • configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...): Kopiert eine Verwendungsanweisungsdatei in das Freigabeverzeichnis des Pakets.

Weitere Informationen finden Sie im Leitfaden für Standard tainer.

5 – Sha512 aktualisieren für portfile.cmake

Führen Sie Folgendes 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 gefunden haben:

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

Kopieren Sie den Tatsächlichen Hash 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417, und ersetzen Sie den SHA512 Wert im portfile.cmake Wert durch den Wert.

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/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 – Überprüfen des Portbuilds

Um die Bibliotheksbuilds und Verknüpfungen ordnungsgemäß zu überprüfen, fügen Sie dem Projekt, das im Lernprogramm für Installationspakete erstellt wurde, eine neue Abhängigkeit hinzu.To verify the library builds and links properly, add a new dependency to the helloworld project created in the install packages tutorial. Nehmen Sie die folgenden Änderungen an den Manifest- und Konfigurationsdateien des Projekts vor.

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

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

Ändern, helloworld/vcpkg-configuration.json um den Ordner einzuschließen, der overlay-ports 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 helloworld/CMakeLists.txt und helloworld/main.cpp verwenden Sie die neue Abhängigkeit.

Ändern Sie den helloworld/CMakeLists.txt Inhalt 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 den main.cpp Inhalt 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
  1. Erstellen Sie das Projekt:
cmake --build build
  1. 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: