Dela via

vcpkg i CMake-projekt

vcpkg erbjuder sömlös integrering med CMake för att göra installerade paket tillgängliga i dina projekt automatiskt. Mekanismen där vcpkg integreras är genom att tillhandahålla en CMake-verktygskedjafil.

Första gången CMake konfigurerar ett projekt körs interna sökrutiner för att hitta en fungerande verktygskedja (kompilator, länkare osv.). Den här sökningen sker inom project()-funktionen i din CMakeLists.txt.

För att anpassa urvalsprocessen för verktygskedjan stöder CMake användning av anpassade CMake-skript, så kallade verktygskedjefiler. En verktygskedjafil anges genom att variabeln CMAKE_TOOLCHAIN_FILE anges. CMake utvärderar innehållet i det angivna verktygskedjans skript och anger variabeldefinitioner, sökvägar till nödvändiga byggverktyg och andra byggparametrar, till exempel korskompileringsflaggor.

När du anger CMAKE_TOOLCHAIN_FILE att använda vcpkg-verktygskedjan (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake) drar vcpkg nytta av verktygskedjans filmekanism för att mata in kod för att integrera med inbyggda CMake-funktioner transparent till dig.

Du kan fortfarande använda en verktygskedja för att konfigurera dina egna verktygsuppsättningar med hjälp VCPKG_CHAINLOAD_TOOLCHAIN_FILE av trippelvariabeln.

vcpkg-integreringen fungerar annorlunda beroende på vilket åtgärdsläge du använder:

I klassiskt läge anger vcpkg CMake-sökvägar på rätt sätt för att göra installerade paket tillgängliga via find_package()funktionerna , find_library()och find_path() .

I manifestläge identifierar verktygskedjan manifestfiler (vcpkg.json-filer) och kör vcpkg install för att automatiskt hämta projektets beroenden, förutom ovanstående.

Eftersom verktygskedjans fil utvärderas under anropet project() måste alla CMake-nivåvariabler som ändrar en vcpkg-inställning anges före det första anropet till project(). Det kan också vara nödvändigt att konfigurera om CMake-projektet om du ändrar någon vcpkg-inställning som resulterar i ABI-hashändringar .

Se Installera och använda paket Exempel: sqlite för ett fullständigt fungerat exempel med CMake.

CMAKE_TOOLCHAIN_FILE

Anmärkning

Om du anger CMAKE_TOOLCHAIN_FILE i CMakeList.txt filen kontrollerar du att variabeln är inställd före alla anrop till project().

Projekt som har konfigurerats för att använda vcpkg-verktygskedjan (via CMake-inställningen CMAKE_TOOLCHAIN_FILE) kan hitta bibliotek från vcpkg med hjälp av CMake-standardfunktionerna: find_package(), find_path()och find_library().

Vi rekommenderar att du använder CMake-förinställningar för att ange din verktygsringsfil. Om du till exempel har definierat miljövariabeln VCPKG_ROOTkan du använda följande CMakePresets.json och skicka --preset debug på konfigurationsraden:

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

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

Om du behöver använda en absolut sökväg för vcpkg som är specifik för den aktuella datorn kan du använda CMakeUserPresets.json och lägga till den i .gitignore filen.

{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "inherits": "debug",
      "environment": {
        "VCPKG_ROOT": "<path to vcpkg>"
      }
    }
  ]
}

CMake-versioner äldre än 3.19 måste ange verktygskedjans fil på kommandoraden för konfigurering.

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

Använda bibliotek

vcpkg stöder CMakes inbyggda mekanismer för att hitta bibliotek: find_package(), find_library()och find_path(). När du installerar bibliotek med specifikt CMake-stöd visar vcpkg användningsinformation om hur du använder biblioteket:

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

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

vcpkg lägger inte automatiskt till några inkluderings- eller länksökvägar i projektet. Om du vill använda ett huvudbibliotek kan du använda find_path() som fungerar korrekt på alla plattformar:

# 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-integrering

Visual Studio/Visual Studio Code

Vi rekommenderar att du använder CMake-förinställningar i både Visual Studio och Visual Studio Code.

Läs mer i Konfigurera och skapa med CMake-förinställningar i Visual Studio och Konfigurera och skapa med CMake-förinställningar i Visual Studio Code.

CLion

Öppna inställningarna för verktygskedjor (File > Settings i Windows och Linux, CLion > Preferences på macOS) och gå till CMake-inställningarna (Build, Execution, Deployment > CMake). I CMake optionslägger du till följande rad:

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

Du måste lägga till den här raden i varje profil separat.

Använda flera verktygskedjefiler

Om du vill kombinera vcpkg-filen med en annan verktygskedja kan du ange CMake-cachevariabeln VCPKG_CHAINLOAD_TOOLCHAIN_FILE:

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

Du kan också inkludera vcpkg-verktygskedjan i slutet av den primära verktygskedjan:

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

Anmärkning

vcpkg tillämpar inte automatiskt verktygskedjans inställningar, till exempel kompilatorn eller kompileringsflaggor, när du skapar bibliotek. Om du vill ändra biblioteksinställningarna för vcpkg måste du skapa en anpassad trillingfil (som kan dela din verktygskedja)**

Referens för inställningar

Alla variabler som påverkar vcpkg måste definieras före det första project() direktivet, till exempel i en CMakePresets.json's-karta "cacheVariables" , via kommandoraden eller set() -instruktioner.

VCPKG_TARGET_TRIPLET

Den här inställningen styr vilken triplet vcpkg installerar och använder bibliotek från.

Om vcpkg tas bort identifieras automatiskt en lämplig standardtrilling med tanke på de aktuella kompilatorinställningarna. Om du ändrar den här CMake-variabeln måste du ta bort cacheminnet och konfigurera om.

VCPKG_HOST_TRIPLET

Den här variabeln styr vilka triplet hostberoenden som ska installeras.

Om den inte är inställd kommer vcpkg automatiskt att identifiera en lämplig native triplet (x64-windows, x64-osx, x64-linux).

Se även Värdberoenden.

VCPKG_INSTALLED_DIR

Den här variabeln anger den plats där bibliotek ska installeras och förbrukas från.

I manifestläge är ${CMAKE_BINARY_DIR}/vcpkg_installedstandardvärdet .

I klassiskt läge är ${VCPKG_ROOT}/installedstandardvärdet .

VCPKG_MANIFEST_MODE

Den här variabeln tvingar vcpkg att fungera i antingen manifestläge eller klassiskt läge.

Standardvärdet är ON när VCPKG_MANIFEST_DIR inte är tom eller om ${CMAKE_SOURCE_DIR}/vcpkg.json finns.

Om du vill inaktivera manifestläget när en vcpkg.json identifieras anger du detta till OFF.

VCPKG_MANIFEST_DIR

Den här variabeln anger en alternativ mapp som innehåller ett vcpkg.json manifest.

Standardvärdet blir ${CMAKE_SOURCE_DIR} om ${CMAKE_SOURCE_DIR}/vcpkg.json finns.

VCPKG_MANIFEST_INSTALL

Den här variabeln styr om vcpkg ska köras automatiskt för att installera dina beroenden under konfigurationssteget.

Standardvärdet är ON om VCPKG_MANIFEST_MODE är ON.

VCPKG_BOOTSTRAP_OPTIONS

Den här variabeln kan ställas in på ytterligare kommandoparametrar som ska skickas till ./bootstrap-vcpkg.

I manifestläge startas vcpkg automatiskt om den körbara filen inte finns.

VCPKG_OVERLAY_TRIPLETS

Den här variabeln kan ställas in på en lista över sökvägar som ska skickas på kommandoraden som --overlay-triplets=...

VCPKG_OVERLAY_PORTS

Den här variabeln kan ställas in på en lista över sökvägar som ska skickas på kommandoraden som --overlay-ports=...

VCPKG_MANIFEST_FEATURES

Den här variabeln kan ställas in på en lista över funktioner som ska aktiveras när du installerar från manifestet.

Funktioner kan till exempel användas av projekt för att styra byggnad med ytterligare beroenden för att aktivera tester eller exempel:

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

Den här inställningen kan styras direkt av CMake-förinställningar med "cacheVariables" eller indirekt baserat på andra inställningar:

# 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

Den här variabeln styr aktiveringen av standardfunktioner utöver de som anges i VCPKG_MANIFEST_FEATURES. Om värdet ONär inställt på aktiveras inte standardfunktionerna automatiskt.

Standardinställningen är OFF.

VCPKG_INSTALL_OPTIONS

Den här variabeln kan ställas in på en lista över ytterligare kommandoradsparametrar som ska skickas till vcpkg-verktyget under automatisk installation.

VCPKG_PREFER_SYSTEM_LIBS

Varning

Den här funktionen är inaktuell. Använd tomma överläggsportar i stället.

Den här variabeln styr om vcpkg ska lägga till sina sökvägar i slutet av i stället för i början av CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH och CMAKE_FIND_ROOT_PATH så att vcpkg-bibliotek/paket hittas efter verktygskedjans/systemets bibliotek/paket.

Standardinställningen är OFF.

VCPKG_FEATURE_FLAGS

Den här variabeln kan ställas in på en lista över funktionsflaggor som ska skickas till vcpkg-verktyget under automatisk installation för att välja experimentellt beteende.

Mer information finns i --feature-flags= kommandoradsalternativet.

VCPKG_TRACE_FIND_PACKAGE

Skriv ut varje anrop till ONnär det är inställt på find_package. Kapslade anrop (t.ex. via find_dependency) indenteras enligt kapslingsdjup.

VCPKG_LOCK_FIND_PACKAGE_<Pkg>

När det här alternativet har angetts, är icke-kapslade anrop till find_package antingen obligatoriska (VCPKG_LOCK_FIND_PACKAGE_<Pkg>=ON) eller inaktiverade (VCPKG_LOCK_FIND_PACKAGE_<Pkg>=OFF).

Den här variabeln är ett verktyg för att styra direkta beroenden och relaterade funktioner i vcpkg-portar som använder CMake-byggsystemet. Det kan användas med vcpkg_check_features och undviker oavsiktliga effekter på transitiva beroenden.