vcpkg dans les projets CMake

vcpkg offre une intégration transparente avec CMake pour rendre les packages installés disponibles automatiquement dans vos projets. Le mécanisme dans lequel vcpkg s’intègre consiste à fournir un fichier de chaîne d’outils CMake.

La première fois que CMake configure un projet, il exécute des routines de recherche internes pour localiser une chaîne d’outils viable (compilateur, éditeur de liens, etc.). Cette recherche se produit dans la project() fonction dans votre CMakeLists.txt.

Pour personnaliser le processus de sélection de chaîne d’outils, CMake prend en charge l’utilisation de scripts de langage CMake personnalisés, appelés fichiers de chaîne d’outils. Un fichier de chaîne d’outils est spécifié en définissant la CMAKE_TOOLCHAIN_FILE variable. CMake évalue le contenu du script de chaîne d’outils fourni et définit les définitions de variables, les chemins d’accès aux outils de génération requis et d’autres paramètres de génération, tels que les indicateurs de compilation croisée, en conséquence.

Lorsque vous définissez CMAKE_TOOLCHAIN_FILE pour utiliser la chaîne d’outils vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake), vcpkg tire parti du mécanisme de fichier de chaîne d’outils pour injecter du code pour intégrer les fonctions CMake intégrées de manière transparente à vous.

Vous pouvez toujours utiliser un fichier de chaîne d’outils pour configurer vos propres ensembles d’outils à l’aide de la VCPKG_CHAINLOAD_TOOLCHAIN_FILE variable triplet.

L’intégration de vcpkg fonctionne différemment en fonction du mode d’opération que vous utilisez :

En mode classique, vcpkg définit les chemins de recherche CMake de manière appropriée pour rendre les packages installés disponibles via les fonctions et find_path() les find_package()find_library()fonctions.

En mode manifeste, en plus des éléments ci-dessus, la chaîne d’outils détecte les fichiers manifeste (vcpkg.json fichiers) et s’exécute vcpkg install pour acquérir automatiquement les dépendances du projet.

Étant donné que le fichier de chaîne d’outils est évalué pendant l’appel project() , toutes les variables de niveau CMake qui modifient un paramètre vcpkg doivent être définies avant le premier appel project(). Il peut également être nécessaire de reconfigurer votre projet CMake si vous modifiez un paramètre vcpkg qui entraîne des modifications de hachage ABI.

Consultez l’exemple d’installation et d’utilisation de packages : sqlite pour obtenir un exemple entièrement travaillé à l’aide de CMake.

CMAKE_TOOLCHAIN_FILE

Remarque

Si vous définissez CMAKE_TOOLCHAIN_FILE dans votre CMakeList.txt fichier, vérifiez que la variable est définie avant les appels à project().

Les projets configurés pour utiliser le fichier de chaîne d’outils vcpkg (via le paramètre CMAKE_TOOLCHAIN_FILECMake) peuvent rechercher des bibliothèques à partir de vcpkg à l’aide des fonctions CMake standard : find_package(), find_path()et find_library().

Nous vous recommandons d’utiliser les présélections CMake pour spécifier votre fichier de chaîne d’outils . Par exemple, si vous avez défini la variable VCPKG_ROOTd’environnement, vous pouvez utiliser les éléments suivants CMakePresets.json et transmettre --preset debug la ligne de configuration :

{
  "version": 2,

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

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

Si vous devez utiliser un chemin absolu pour vcpkg spécifique à votre ordinateur actuel, vous pouvez l’utiliser CMakeUserPresets.json et l’ajouter à votre .gitignore fichier.

{
  "version": 2,

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

Les versions CMake antérieures à la version 3.19 doivent transmettre le fichier de chaîne d’outils sur la ligne de commande configurer :

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

Utilisation de bibliothèques

vcpkg prend en charge les mécanismes natifs de CMake pour rechercher des bibliothèques : find_package(), find_library()et find_path(). Lors de l’installation de bibliothèques avec une prise en charge spécifique de CMake, vcpkg affiche des informations d’utilisation sur la façon d’utiliser la bibliothèque :

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

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

vcpkg n’ajoute pas automatiquement de chemins d’accès include ou liens dans votre projet. Pour utiliser une bibliothèque en-tête uniquement, vous pouvez utiliser find_path() ce qui fonctionnera correctement sur toutes les plateformes :

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

Intégration à l’IDE

Visual Studio / Visual Studio Code

Nous vous recommandons d’utiliser des présélections CMake dans Visual Studio et Visual Studio Code.

En savoir plus sur Configurer et générer avec des présélections CMake dans Visual Studio et configurer et générer avec des présélections CMake dans Visual Studio Code.

CLion

Ouvrez les paramètres des chaînes d’outils (File > Settings sur Windows et Linux, CLion > Preferences sur macOS), puis accédez aux paramètres CMake (Build, Execution, Deployment > CMake). Dans CMake options, ajoutez la ligne suivante :

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

Vous devez ajouter cette ligne à chaque profil séparément.

Utilisation de plusieurs fichiers de chaîne d’outils

Pour combiner le fichier de chaîne d’outils de vcpkg avec un autre fichier de chaîne d’outils, vous pouvez définir la variable VCPKG_CHAINLOAD_TOOLCHAIN_FILEde cache CMake :

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

Vous pouvez également inclure la chaîne d’outils vcpkg à la fin du fichier de chaîne d’outils principal :

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

Remarque

vcpkg n’applique pas automatiquement les paramètres de votre chaîne d’outils, tels que votre compilateur ou vos indicateurs de compilation, lors de la création de bibliothèques. Pour modifier les paramètres de bibliothèque de vcpkg, vous devez créer un fichier triplet personnalisé (qui peut partager votre chaîne d’outils)**

Informations de référence sur les paramètres

Toutes les variables affectant vcpkg doivent être définies avant la première project() directive, par exemple dans la carte d’un CMakePresets.jsonfichier "cacheVariables" map, via la ligne de commande ou set() les instructions.

VCPKG_TARGET_TRIPLET

Ce paramètre contrôle le triplet vcpkg à partir duquel installer et consommera des bibliothèques.

Si ce paramètre n’est pas défini, vcpkg détecte automatiquement un triplet par défaut approprié en fonction des paramètres actuels du compilateur. Si vous modifiez cette variable CMake, vous devez supprimer votre cache et reconfigurer.

VCPKG_HOST_TRIPLET

Cette variable contrôle les dépendances de l’hôte triplet pour lesquelles les dépendances seront installées.

Si ce paramètre n’est pas défini, vcpkg détecte automatiquement un triplet natif approprié (x64-windows, x64-osx, x64-linux).

Consultez également les dépendances de l’hôte.

VCPKG_INSTALLED_DIR

Cette variable définit l’emplacement à partir duquel les bibliothèques seront installées et consommées.

En mode manifeste, la valeur par défaut est ${CMAKE_BINARY_DIR}/vcpkg_installed.

En mode classique, la valeur par défaut est ${VCPKG_ROOT}/installed.

VCPKG_MANIFEST_MODE

Cette variable force vcpkg à fonctionner en mode manifeste ou en mode classique.

ON La valeur par défaut est quand VCPKG_MANIFEST_DIR n’est pas vide ou ${CMAKE_SOURCE_DIR}/vcpkg.json existe.

Pour désactiver le mode manifeste lorsqu’un vcpkg.json message est détecté, définissez-le OFFsur .

VCPKG_MANIFEST_DIR

Cette variable spécifie un autre dossier contenant un vcpkg.json manifeste.

La valeur par défaut est ${CMAKE_SOURCE_DIR} ${CMAKE_SOURCE_DIR}/vcpkg.json si elle existe.

VCPKG_MANIFEST_INSTALL

Cette variable contrôle si vcpkg sera automatiquement exécuté pour installer vos dépendances lors de l’étape de configuration.

ON VCPKG_MANIFEST_MODE La valeur par défaut est ON.

VCPKG_BOOTSTRAP_OPTIONS

Cette variable peut être définie sur des paramètres de commande supplémentaires à passer à ./bootstrap-vcpkg.

En mode manifeste, vcpkg est automatiquement démarré si l’exécutable n’existe pas.

VCPKG_OVERLAY_TRIPLETS

Cette variable peut être définie sur une liste de chemins à transmettre sur la ligne de commande en tant que --overlay-triplets=...

VCPKG_OVERLAY_PORTS

Cette variable peut être définie sur une liste de chemins à transmettre sur la ligne de commande en tant que --overlay-ports=...

VCPKG_MANIFEST_FEATURES

Cette variable peut être définie sur une liste de fonctionnalités à activer lors de l’installation à partir de votre manifeste.

Par exemple, les fonctionnalités peuvent être utilisées par des projets pour contrôler la génération avec des dépendances supplémentaires pour activer des tests ou des exemples :

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

Ce paramètre peut être contrôlé directement par les présélections CMake avec "cacheVariables" ou indirectement en fonction d’autres paramètres :

# 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

Cette variable contrôle l’activation des fonctionnalités par défaut en plus de celles répertoriées dans VCPKG_MANIFEST_FEATURES. Si la valeur est définie ON, les fonctionnalités par défaut ne sont pas activées automatiquement.

La valeur par défaut est OFF.

VCPKG_INSTALL_OPTIONS

Cette variable peut être définie sur une liste de paramètres de ligne de commande supplémentaires à passer à l’outil vcpkg pendant l’installation automatique.

VCPKG_PREFER_SYSTEM_LIBS

Avertissement

Cette fonctionnalité est déconseillée. Utilisez plutôt des ports de superposition vides.

Cette variable contrôle si vcpkg ajoute au lieu de prépender ses chemins d’accès CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH et CMAKE_FIND_ROOT_PATH afin que les bibliothèques/packages vcpkg soient trouvées après la chaîne d’outils/bibliothèques système/packages.

La valeur par défaut est OFF.

VCPKG_FEATURE_FLAGS

Cette variable peut être définie sur une liste d’indicateurs de fonctionnalité à transmettre à l’outil vcpkg pendant l’installation automatique pour accepter le comportement expérimental.

Pour plus d’informations, consultez l’option --feature-flags= de ligne de commande.

VCPKG_TRACE_FIND_PACKAGE

Lorsque la valeur est ONdéfinie, imprimez chaque appel à find_package. Les appels imbriqués (par exemple via find_dependency) sont mis en retrait en fonction de la profondeur d’imbrication.