vcpkg in CMake-Projekten

vcpkg bietet eine nahtlose Integration in CMake, um installierte Pakete automatisch in Ihren Projekten verfügbar zu machen. Der Mechanismus, in den vcpkg integriert wird, besteht darin, eine CMake-Toolkettedatei bereitzustellen.

Wenn CMake ein Projekt zum ersten Mal konfiguriert, führt es interne Suchroutinen aus, um eine lebensfähige Toolkette (Compiler, Linker usw.) zu finden. Diese Suche erfolgt innerhalb der project() Funktion in Ihrer CMakeLists.txt.

Um den Toolkette-Auswahlprozess anzupassen, unterstützt CMake die Verwendung von benutzerdefinierten CMake-Sprachskripts, die als Toolbunddateien bezeichnet werden. Eine Toolbunddatei wird durch Festlegen der CMAKE_TOOLCHAIN_FILE Variablen angegeben. CMake wertet den Inhalt des bereitgestellten Toolbundskripts aus und legt Variablendefinitionen, Pfade zu erforderlichen Buildtools und andere Buildparameter wie Kompilierungskennzeichnungen entsprechend fest.

Wenn Sie die vcpkg-Toolkette (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake) verwenden, CMAKE_TOOLCHAIN_FILE nutzt vcpkg den Toolchain-Dateimechanismus, um Code in integrierte CMake-Funktionen transparent in Sie zu integrieren.

Sie können weiterhin eine Toolkettedatei verwenden, um Ihre eigenen Toolsets mithilfe der VCPKG_CHAINLOAD_TOOLCHAIN_FILE Triplet-Variable zu konfigurieren.

Die vcpkg-Integration funktioniert je nach dem verwendeten Vorgangsmodus unterschiedlich:

Im klassischen Modus legt vcpkg CMake-Suchpfade entsprechend fest, um installierte Pakete über die find_package(), find_library()und find_path() Funktionen verfügbar zu machen.

Im Manifestmodus erkennt die Toolkette zusätzlich zu den oben genannten Manifestdateien (vcpkg.json Dateien) und wird ausgeführt vcpkg install , um die Abhängigkeiten des Projekts automatisch zu erwerben.

Da die Toolkettedatei während des project() Aufrufs ausgewertet wird, müssen alle Variablen auf CMake-Ebene, die eine vcpkg-Einstellung ändern, vor dem ersten Aufruf project()festgelegt werden. Es kann auch erforderlich sein, Ihr CMake-Projekt neu zu konfigurieren, wenn Sie eine vcpkg-Einstellung ändern, die zu ABI-Hashänderungen führt.

Siehe Beispiel zum Installieren und Verwenden von Paketen: sqlite für ein vollständig funktionsfähiges Beispiel mit CMake.

CMAKE_TOOLCHAIN_FILE

Projekte, die für die Verwendung der vcpkg-Toolchaindatei (über die CMake-Einstellung CMAKE_TOOLCHAIN_FILE) konfiguriert sind, können Bibliotheken von vcpkg mithilfe der standardmäßigen CMake-Funktionen finden: find_package(), , find_path()und find_library().

Wir empfehlen die Verwendung von CMake Presets zum Angeben Der Toolkette-Datei. Wenn Sie beispielsweise die Umgebungsvariable VCPKG_ROOTdefiniert haben, können Sie Folgendes CMakePresets.json verwenden und die Konfigurationszeile übergeben --preset debug :

{
  "version": 2,

  "configurePresets": [
    {
      "name": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

cmake -B build -S /my/project --preset debug

Wenn Sie einen absoluten Pfad für vcpkg verwenden müssen, der für Ihren aktuellen Computer spezifisch ist, können Sie ihn verwenden CMakeUserPresets.json und ihrer .gitignore Datei hinzufügen.

{
  "version": 2,

  "configurePresets": [
    {
      "name": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

CMake-Versionen, die älter als 3.19 sind, müssen die Toolbunddatei in der Befehlszeile übergeben:

cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

Verwenden von Bibliotheken

vcpkg unterstützt die systemeigenen Mechanismen von CMake zum Suchen von Bibliotheken: find_package(), , find_library()und find_path(). Beim Installieren von Bibliotheken mit spezifischer CMake-Unterstützung zeigt vcpkg Nutzungsinformationen zur Nutzung der Bibliothek an:

The package zlib is compatible with built-in CMake targets:

    find_package(ZLIB REQUIRED)
    target_link_libraries(main PRIVATE ZLIB::ZLIB)

vcpkg fügt ihrem Projekt keine Include- oder Verknüpfungspfade automatisch hinzu. Zum Verwenden einer schreibgeschützten Bibliothek können Sie verwenden find_path() , die auf allen Plattformen ordnungsgemäß funktioniert:

# To find and use catch2
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
target_include_directories(main PRIVATE ${CATCH_INCLUDE_DIR})

IDE-Integration

Visual Studio/ Visual Studio Code

Es wird empfohlen, CMake-Voreinstellungen sowohl in Visual Studio als auch in Visual Studio Code zu verwenden.

Weitere Informationen finden Sie unter Konfigurieren und Erstellen mit CMake Presets in Visual Studio und Konfigurieren und Erstellen mit CMake Presets in Visual Studio Code.

CLion

Öffnen Sie die Einstellungen für die Toolkette (File > Settings unter Windows und Linux, CLion > Preferences unter macOS), und wechseln Sie zu den CMake-Einstellungen (Build, Execution, Deployment > CMake). Fügen Sie in CMake options, fügen Sie die folgende Zeile hinzu:

-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

Sie müssen diese Zeile jedem Profil separat hinzufügen.

Verwenden mehrerer Toolkettedateien

Um die Toolbunddatei von vcpkg mit einer anderen Toolkette zu kombinieren, können Sie die CMake-Cachevariable VCPKG_CHAINLOAD_TOOLCHAIN_FILEfestlegen:

cmake ../my/project \
   -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
   -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/toolchain.cmake

Alternativ können Sie die vcpkg-Toolkette am Ende der primären Toolkette einfügen:

# MyToolchain.cmake
set(CMAKE_CXX_COMPILER ...)
set(VCPKG_TARGET_TRIPLET x64-my-custom-windows-triplet)
include(/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake)

Einstellungsreferenz

Alle vcpkg-beeinflussenden Variablen müssen vor der ersten project() Direktive definiert werden, z. B. in einer CMakePresets.jsonKarte "cacheVariables" , über die Befehlszeile oder set() Anweisungen.

VCPKG_TARGET_TRIPLET

Diese Einstellung steuert die Triplet-vcpkg-Datei , aus der Bibliotheken installiert und verwendet werden.

Wenn dies nicht festgelegt ist, erkennt vcpkg automatisch ein entsprechendes Standard-Triplet, wenn die aktuellen Compilereinstellungen vorhanden sind. Wenn Sie diese CMake-Variable ändern, müssen Sie den Cache löschen und neu konfigurieren.

VCPKG_HOST_TRIPLET

Diese Variable steuert, für welche Triplethostabhängigkeiten installiert werden.

Wenn nicht festgelegt, erkennt vcpkg automatisch ein entsprechendes systemeigenes Triplet (x64-windows, x64-osx, x64-linux).

Siehe auch Hostabhängigkeiten.

VCPKG_INSTALLED_DIR

Diese Variable legt den Speicherort fest, an dem Bibliotheken installiert und genutzt werden.

Im Manifestmodus ist ${CMAKE_BINARY_DIR}/vcpkg_installedder Standardwert .

Im klassischen Modus ist ${VCPKG_ROOT}/installedder Standardwert .

VCPKG_MANIFEST_MODE

Diese Variable erzwingt vcpkg, entweder im Manifestmodus oder im klassischen Modus zu arbeiten.

ON Der Standardwert ist, wann VCPKG_MANIFEST_DIR nicht leer oder ${CMAKE_SOURCE_DIR}/vcpkg.json vorhanden ist.

Um den Manifestmodus zu deaktivieren, während ein vcpkg.json Manifest erkannt wird, legen Sie dies auf OFF.

VCPKG_MANIFEST_DIR

Diese Variable gibt einen alternativen Ordner an, der ein vcpkg.json Manifest enthält.

Wenn vorhanden, wird ${CMAKE_SOURCE_DIR} ${CMAKE_SOURCE_DIR}/vcpkg.json standardmäßig festgelegt.

VCPKG_MANIFEST_INSTALL

Diese Variable steuert, ob vcpkg während des Konfigurationsschritts automatisch ausgeführt wird, um Ihre Abhängigkeiten zu installieren.

Standardwert ist ON , wenn VCPKG_MANIFEST_MODE der Standardwert ist ON.

VCPKG_BOOTSTRAP_OPTIONS

Diese Variable kann auf zusätzliche Befehlsparameter festgelegt werden, an die ./bootstrap-vcpkgübergeben werden soll.

Im Manifestmodus wird vcpkg automatisch bootstrapped, wenn die ausführbare Datei nicht vorhanden ist.

VCPKG_OVERLAY_TRIPLETS

Diese Variable kann auf eine Liste der Pfade festgelegt werden, die an die Befehlszeile übergeben werden sollen. --overlay-triplets=...

VCPKG_OVERLAY_PORTS

Diese Variable kann auf eine Liste der Pfade festgelegt werden, die an die Befehlszeile übergeben werden sollen. --overlay-ports=...

VCPKG_MANIFEST_FEATURES

Diese Variable kann auf eine Liste der Features festgelegt werden, die beim Installieren aus Ihrem Manifest aktiviert werden sollen.

Beispielsweise können Features von Projekten verwendet werden, um das Erstellen mit zusätzlichen Abhängigkeiten zu steuern, um Tests oder Beispiele zu aktivieren:

{
  "name": "mylibrary",
  "version": "1.0",
  "dependencies": [ "curl" ],
  "features": {
    "samples": {
      "description": "Build Samples",
      "dependencies": [ "fltk" ]
    },
    "tests": {
      "description": "Build Tests",
      "dependencies": [ "gtest" ]
    }
  }
}

Diese Einstellung kann direkt von CMake Presets mit "cacheVariables" oder indirekt basierend auf anderen Einstellungen gesteuert werden:

# CMakeLists.txt

option(BUILD_TESTING "Build tests" OFF)
if(BUILD_TESTING)
  list(APPEND VCPKG_MANIFEST_FEATURES "tests")
endif()

option(BUILD_SAMPLES "Build samples" OFF)
if(BUILD_SAMPLES)
  list(APPEND VCPKG_MANIFEST_FEATURES "samples")
endif()

project(myapp)

# ...

VCPKG_MANIFEST_NO_DEFAULT_FEATURES

Diese Variable steuert die Aktivierung von Standardfeatures zusätzlich zu den in VCPKG_MANIFEST_FEATURES. Bei Festlegung auf ON, werden Die Standardfeatures nicht automatisch aktiviert.

Wird standardmäßig auf OFF festgelegt.

VCPKG_INSTALL_OPTIONS

Diese Variable kann auf eine Liste zusätzlicher Befehlszeilenparameter festgelegt werden, die während der automatischen Installation an das vcpkg-Tool übergeben werden.

VCPKG_PREFER_SYSTEM_LIBS

Diese Variable steuert, ob vcpkg angefügt wird, anstatt seine Pfade CMAKE_PREFIX_PATHCMAKE_LIBRARY_PATH vorzuerkennen und CMAKE_FIND_ROOT_PATH so, dass vcpkg-Bibliotheken/-pakete nach der Toolkette/Systembibliotheken/-pakete gefunden werden.

Wird standardmäßig auf OFF festgelegt.

VCPKG_FEATURE_FLAGS

Diese Variable kann auf eine Liste von Featurekennzeichnungen festgelegt werden, die während der automatischen Installation an das vcpkg-Tool übergeben werden, um sich für experimentelles Verhalten zu entscheiden.

Weitere Informationen finden Sie in der --feature-flags= Befehlszeilenoption.

VCPKG_TRACE_FIND_PACKAGE

Wenn diese Einstellung auf ON" festgelegt ist , drucken Sie jeden Anruf an find_package. Geschachtelte Anrufe (z. B. via find_dependency) werden entsprechend der Schachtelungstiefe eingezogen.