vcpkg nei progetti CMake

vcpkg offre un'integrazione perfetta con CMake per rendere i pacchetti installati disponibili automaticamente nei progetti. Il meccanismo in cui vcpkg si integra consiste nel fornire un file toolchain CMake.

La prima volta che CMake configura un progetto, esegue routine di ricerca interne per individuare una toolchain praticabile (compilatore, linker e così via). Questa ricerca viene eseguita all'interno della funzione nell'oggetto project() CMakeLists.txt.

Per personalizzare il processo di selezione della toolchain, CMake supporta l'uso di script personalizzati del linguaggio CMake, noti come file toolchain. Un file toolchain viene specificato impostando la CMAKE_TOOLCHAIN_FILE variabile. CMake valuta il contenuto dello script toolchain fornito e imposta le definizioni delle variabili, i percorsi degli strumenti di compilazione necessari e altri parametri di compilazione, ad esempio flag di compilazione incrociata, di conseguenza.

Quando si imposta CMAKE_TOOLCHAIN_FILE per usare la toolchain vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake), vcpkg sfrutta il meccanismo di file toolchain per inserire il codice da integrare con le funzioni CMake predefinite in modo trasparente.

È comunque possibile usare un file toolchain per configurare set di strumenti personalizzati usando la VCPKG_CHAINLOAD_TOOLCHAIN_FILE variabile triplet.

L'integrazione di vcpkg funziona in modo diverso a seconda della modalità operativa in uso:

In modalità classica vcpkg imposta i percorsi di ricerca di CMake in modo appropriato per rendere i pacchetti installati disponibili tramite le find_package()funzioni , find_library()e find_path() .

In modalità manifesto, oltre a quanto sopra, la toolchain rileva i file manifesto (vcpkg.json file) ed esegue vcpkg install per acquisire automaticamente le dipendenze del progetto.

Poiché il file toolchain viene valutato durante la project() chiamata, tutte le variabili a livello di CMake che modificano un'impostazione vcpkg devono essere impostate prima della prima chiamata a project(). Potrebbe anche essere necessario riconfigurare il progetto CMake se si modifica un'impostazione vcpkg che comporta modifiche all'hash ABI.

Vedere Esempio di installazione e uso di pacchetti: sqlite per un esempio completamente funzionante con CMake.

CMAKE_TOOLCHAIN_FILE

Nota

Se si imposta CMAKE_TOOLCHAIN_FILE nel CMakeList.txt file, assicurarsi che la variabile sia impostata prima di qualsiasi chiamata a project().

I progetti configurati per l'uso del file toolchain vcpkg (tramite l'impostazione CMAKE_TOOLCHAIN_FILECMake ) possono trovare librerie da vcpkg usando le funzioni CMake standard: find_package(), find_path()e find_library().

È consigliabile usare i set di impostazioni di CMake per specificare il file toolchain. Ad esempio, se è stata definita la variabile VCPKG_ROOTdi ambiente , è possibile usare quanto segue CMakePresets.json e passare --preset debug la riga di configurazione:

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

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

Se è necessario usare un percorso assoluto per vcpkg specifico del computer corrente, è possibile usarlo CMakeUserPresets.json e aggiungerlo al .gitignore file.

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

Le versioni di CMake precedenti alla 3.19 devono passare il file toolchain nella riga di comando di configurazione:

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

Uso delle librerie

vcpkg supporta i meccanismi nativi di CMake per la ricerca di librerie: find_package(), find_library()e find_path(). Quando si installano librerie con supporto CMake specifico, vcpkg visualizzerà informazioni sull'utilizzo su come usare la libreria:

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

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

vcpkg non aggiunge automaticamente percorsi di inclusione o collegamenti al progetto. Per usare una libreria di sola intestazione, è possibile usare find_path() che funzionerà correttamente in tutte le piattaforme:

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

Integrazione nell'IDE

Visual Studio/Visual Studio Code

È consigliabile usare i set di impostazioni di CMake sia in Visual Studio che in Visual Studio Code.

Per altre informazioni, vedere Configurare e compilare con i set di impostazioni di CMake in Visual Studio e configurare e compilare con i set di impostazioni di CMake in Visual Studio Code.

CLion

Aprire le impostazioni delle toolchain (File > Settings in Windows e Linux in CLion > Preferences macOS) e passare alle impostazioni di CMake (Build, Execution, Deployment > CMake). In CMake optionsaggiungere la riga seguente:

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

È necessario aggiungere questa riga a ogni profilo separatamente.

Uso di più file toolchain

Per combinare il file toolchain di vcpkg con un altro file toolchain, è possibile impostare la variabile VCPKG_CHAINLOAD_TOOLCHAIN_FILEcache CMake :

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

In alternativa, è possibile includere la toolchain vcpkg alla fine del file toolchain primario:

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

Nota

vcpkg non applica automaticamente le impostazioni della toolchain, ad esempio il compilatore o i flag di compilazione, durante la compilazione di librerie. Per modificare le impostazioni della libreria di vcpkg, è necessario creare un file tripletta personalizzato (che può condividere la toolchain)**

Informazioni di riferimento sulle impostazioni

Tutte le variabili che influiscono su vcpkg devono essere definite prima della prima project() direttiva, ad esempio nella mappa di un CMakePresets.jsonoggetto , tramite la riga di "cacheVariables" comando o set() le istruzioni .

VCPKG_TARGET_TRIPLET

Questa impostazione controlla che il vcpkg triplo installerà e utilizzerà le librerie da.

Se non è impostato, vcpkg rileverà automaticamente un triplo predefinito appropriato in base alle impostazioni correnti del compilatore. Se si modifica questa variabile CMake, è necessario eliminare la cache e riconfigurarsi.

VCPKG_HOST_TRIPLET

Questa variabile controlla le dipendenze dell'host triplo per cui verranno installate.

Se unset, vcpkg rileverà automaticamente un triplo nativo appropriato (x64-windows, x64-osx, x64-linux).

Vedere anche Dipendenze host.

VCPKG_INSTALLED_DIR

Questa variabile imposta il percorso da cui verranno installate e utilizzate le librerie.

In modalità manifesto, il valore predefinito è ${CMAKE_BINARY_DIR}/vcpkg_installed.

In modalità classica, il valore predefinito è ${VCPKG_ROOT}/installed.

VCPKG_MANIFEST_MODE

Questa variabile forza vcpkg a funzionare in modalità manifesto o in modalità classica.

Il valore predefinito è ON quando VCPKG_MANIFEST_DIR non è vuoto o ${CMAKE_SOURCE_DIR}/vcpkg.json esiste.

Per disabilitare la modalità manifesto quando viene rilevato un vcpkg.json oggetto , impostare su OFF.

VCPKG_MANIFEST_DIR

Questa variabile specifica una cartella alternativa contenente un vcpkg.json manifesto.

L'impostazione predefinita è ${CMAKE_SOURCE_DIR} se ${CMAKE_SOURCE_DIR}/vcpkg.json esistente.

VCPKG_MANIFEST_INSTALL

Questa variabile controlla se vcpkg verrà eseguito automaticamente per installare le dipendenze durante il passaggio di configurazione.

L'impostazione ON predefinita è se VCPKG_MANIFEST_MODE è ON.

VCPKG_BOOTSTRAP_OPTIONS

Questa variabile può essere impostata su parametri di comando aggiuntivi da passare a ./bootstrap-vcpkg.

In modalità manifesto, vcpkg verrà automaticamente avviato se l'eseguibile non esiste.

VCPKG_OVERLAY_TRIPLETS

Questa variabile può essere impostata su un elenco di percorsi da passare nella riga di comando come --overlay-triplets=...

VCPKG_OVERLAY_PORTS

Questa variabile può essere impostata su un elenco di percorsi da passare nella riga di comando come --overlay-ports=...

VCPKG_MANIFEST_FEATURES

Questa variabile può essere impostata su un elenco di funzionalità da attivare durante l'installazione dal manifesto.

Ad esempio, le funzionalità possono essere usate dai progetti per controllare la compilazione con dipendenze aggiuntive per abilitare test o esempi:

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

Questa impostazione può essere controllata direttamente dai set di impostazioni di CMake con "cacheVariables" o indirettamente in base ad altre impostazioni:

# 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

Questa variabile controlla l'attivazione delle funzionalità predefinite oltre a quelle elencate in VCPKG_MANIFEST_FEATURES. Se impostato su ON, le funzionalità predefinite non verranno attivate automaticamente.

Il valore predefinito è OFF.

VCPKG_INSTALL_OPTIONS

Questa variabile può essere impostata su un elenco di parametri della riga di comando aggiuntivi da passare allo strumento vcpkg durante l'installazione automatica.

VCPKG_PREFER_SYSTEM_LIBS

Avviso

Questa funzionalità è stata deprecata. Usare invece porte sovrapposte vuote.

Questa variabile controlla se vcpkg aggiungerà invece di anteporre i relativi percorsi a CMAKE_PREFIX_PATHCMAKE_LIBRARY_PATH e CMAKE_FIND_ROOT_PATH in modo che le librerie/i pacchetti vcpkg vengano trovate dopo toolchain/librerie di sistema/pacchetti.

Il valore predefinito è OFF.

VCPKG_FEATURE_FLAGS

Questa variabile può essere impostata su un elenco di flag di funzionalità da passare allo strumento vcpkg durante l'installazione automatica per acconsentire esplicitamente al comportamento sperimentale.

Per altre informazioni, vedere l'opzione della --feature-flags= riga di comando.

VCPKG_TRACE_FIND_PACKAGE

Se impostato su ON, stampare ogni chiamata a find_package. Le chiamate annidate (ad esempio tramite find_dependency) vengono rientrate in base alla profondità di annidamento.