Personnaliser les paramètres de génération CMake

Visual Studio utilise un fichier de configuration CMake pour entraîner la génération et la création CMake. CMakePresets.json est pris en charge par Visual Studio 2019 version 16.10 ou ultérieure et il s’agit du fichier de configuration CMake recommandé. CMakePresets.json est pris en charge directement par CMake et peut être utilisé pour générer et créer CMake à partir de Visual Studio, à partir de VS Code, dans un pipeline d’intégration continue et à partir de la ligne de commande sur Windows, Linux et Mac. Pour plus d’informations sur CMakePresets.json, consultez Configurer et générer avec les présélections CMake.

Si vous gérez des projets qui utilisent un fichier CMakeSettings.json pour la configuration de build CMake, Visual Studio 2019 et les versions ultérieures fournissent un éditeur de paramètres CMake. L’éditeur vous permet d’ajouter des configurations CMake et de personnaliser leurs paramètres facilement. Il a été conçu pour être une alternative plus simple pour modifier manuellement le fichier CMakeSettings.json. Toutefois, si vous préférez modifier le fichier directement, vous pouvez sélectionner le lien Modifier le fichier JSON en haut à droite de l’éditeur.

Pour ouvrir l’éditeur de paramètres CMake, sélectionnez la liste déroulante Configuration dans la barre d’outils principale et choisissez Gérer les configurations.

Maintenant, vous voyez l’éditeur de paramètres, avec les configurations installées sur la gauche.

Visual Studio fournit une configuration x64-Debug par défaut. Vous pouvez ajouter d’autres configurations en choisissant le signe plus vert. Les paramètres que vous voyez dans l’éditeur peuvent varier en fonction de la configuration sélectionnée.

Les options que vous choisissez dans l’éditeur sont écrites dans un fichier appelé CMakeSettings.json. Ce fichier fournit des arguments de ligne de commande et des variables d’environnement qui sont passés à CMake quand vous générez les projets. Visual Studio ne modifie jamais CMakeLists.txt automatiquement ; à l’aide de CMakeSettings.json, vous pouvez personnaliser la génération par le biais de Visual Studio tout en conservant les fichiers projet CMake intacts afin que les autres membres de votre équipe puissent les utiliser avec les outils de leur choix.

Paramètres généraux CMake

Les paramètres suivants sont disponibles sous le titre Général :

Nom de la configuration

Correspond au paramètre name. Ce nom apparaît dans la liste déroulante des configurations C++. Vous pouvez utiliser la macro ${name} pour composer d’autres valeurs de propriété telles que des chemins.

Type de configuration

Correspond au paramètre configurationType. Définit le type de configuration de build du générateur sélectionné. Les valeurs actuellement prises en charge sont Debug, MinSizeRel, Release et RelWithDebInfo. Il correspond à CMAKE_BUILD_TYPE.

Ensemble d'outils

Correspond au paramètre inheritedEnvironments. Définit l’environnement du compilateur utilisé pour générer la configuration sélectionnée. Les valeurs prises en charge varient selon le type de configuration. Pour créer un environnement personnalisé, choisissez le lien Modifier le fichier JSON en haut à droite de l’éditeur de paramètres et modifiez directement le fichier CMakeSettings.json.

Fichier de chaîne d’outils CMake

Chemin du fichier de chaîne d’outils CMake. Ce chemin est passé à CMake en tant que "-DCMAKE_TOOLCHAIN_FILE = <filepath>. Les fichiers de chaîne d’outils spécifient les emplacements des compilateurs et des utilitaires de chaîne d’outils, ainsi que d’autres informations relatives à la plateforme cible et au compilateur. Par défaut, Visual Studio utilise le fichier de chaîne d’outils vcpkg si ce paramètre n’est pas spécifié.

Racine de build

Correspond à buildRoot. Correspond à CMAKE_BINARY_DIR et spécifie où créer le cache CMake. Le dossier spécifié est créé s’il n’existe pas.

Les arguments de la commande

Les paramètres suivants sont disponibles sous le titre Arguments de la commande  :

Arguments de commande CMake

Correspond à cmakeCommandArgs. Spécifie toute autre option de ligne de commande passée à CMake.

Arguments de commande de build

Correspond à buildCommandArgs. Spécifie d’autres commutateurs à passer au système de build sous-jacent. Par exemple, si vous passez -v quand vous utilisez le générateur Ninja, cela oblige Ninja à sortir des lignes de commande.

Arguments de commande CTest

Correspond à ctestCommandArgs. Spécifie d’autres options de ligne de commande à passer à CTest pendant l’exécution des tests.

Paramètres généraux pour les builds distantes

Pour les configurations telles que Linux qui utilisent des builds distantes, les paramètres suivants sont également disponibles :

Arguments de la commande rsync

Options de ligne de commande supplémentaires passées à rsync, un outil de copie de fichiers polyvalent rapide.

Variables et cache CMake

Ces paramètres vous permettent de définir des variables CMake et de les enregistrer dans CMakeSettings.json. Ils sont passés à CMake au moment de la génération et remplacent les valeurs figurant dans le fichier CMakeLists.txt. Vous pouvez utiliser cette section de la même façon que l’interface CMakeGUI pour afficher la liste de toutes les variables CMake modifiables. Choisissez le bouton Enregistrer et générer le cache pour voir la liste de toutes les variables CMake modifiables, y compris les variables avancées (par le biais de l’interface CMakeGUI). Vous pouvez filtrer la liste par nom de variable.

Correspond aux variables. Contient une paire nom-valeur de variables CMake passées comme -D name=value à CMake. Si vos instructions de génération de projet CMake spécifient l’ajout des variables directement dans le fichier de cache CMake, nous vous recommandons de les ajouter plutôt ici.

Paramètres avancés

Générateur CMake

Correspond au générateur. Correspond au commutateur -G CMake et spécifie le générateur CMake à utiliser. Cette propriété peut également être utilisée en tant que macro, ${generator}, quand vous rédigez d’autres valeurs de propriétés. Visual Studio prend actuellement en charge les générateurs CMake suivants :

• « Ninja »
• « Unix Makefiles »
• « Visual Studio 16 2019 »
• « Visual Studio 16 2019 Win64 »
• « Visual Studio 16 2019 ARM »
• « Visual Studio 15 2017 »
• « Visual Studio 15 2017 Win64 »
• « Visual Studio 15 2017 ARM »
• « Visual Studio 14 2015 »
• « Visual Studio 14 2015 Win64 »
• « Visual Studio 14 2015 ARM »

Comme Ninja est conçu pour des grandes vitesses de génération plutôt que pour la flexibilité et la fonctionnalité, il est défini par défaut. Toutefois, certains projets CMake risquent de ne pas pouvoir être générés correctement avec Ninja. Si cela se produit, vous pouvez demander à CMake de générer un projet Visual Studio à la place.

Mode IntelliSense

Mode IntelliSense utilisé par le moteur IntelliSense. Si aucun mode n’est sélectionné, Visual Studio hérite du mode de l’ensemble d’outils spécifié.

Répertoire d’installation

Répertoire dans lequel CMake installe les cibles. Mappe à CMAKE_INSTALL_PREFIX.

Exécutable CMake

Chemin complet du programme exécutable CMake, avec le nom de fichier et l’extension. Il vous permet d’utiliser une version personnalisée de CMake avec Visual Studio. Pour les builds distantes, spécifiez l’emplacement CMake sur l’ordinateur distant.

Pour les configurations telles que Linux qui utilisent des builds distantes, les paramètres suivants sont également disponibles :

Racine CMakeLists.txt distante

Répertoire de l’ordinateur distant qui contient le fichier CMakeLists.txt racine.

Racine d’installation distante

Répertoire de l’ordinateur distant dans lequel CMake installe les cibles. Mappe à CMAKE_INSTALL_PREFIX.

Copier les sources sur la machine distante

Indique s’il faut copier les fichiers sources sur l’ordinateur distant et vous laisse spécifier s’il faut utiliser rsync ou sftp.

Modifier CMakeSettings.json directement

Vous pouvez également modifier directement CMakeSettings.json pour créer des configurations personnalisées. L’éditeur de paramètres a un bouton Modifier JSON en haut à droite qui ouvre le fichier en vue de sa modification.

L’exemple suivant illustre une configuration, que vous pouvez utiliser comme point de départ :

    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    },

JSON IntelliSense vous permet de modifier le fichier CMakeSettings.json :

L’éditeur JSON vous informe aussi quand vous choisissez des paramètres incompatibles.

Pour plus d’informations sur chacune des propriétés dans le fichier, consultez Informations de référence sur le schéma CMakeSettings.json.

Visual Studio 2017 fournit plusieurs configurations CMake qui définissent la manière d’appeler CMake pour créer le cache CMake d’un projet donné. Pour ajouter une nouvelle configuration, sélectionnez la liste déroulante de configuration dans la barre d’outils et choisissez Gérer les configurations :

Vous pouvez choisir dans la liste des configurations prédéfinies :

La première fois que vous sélectionnez une configuration, Visual Studio crée un fichier CMakeSettings.json dans le dossier racine de votre projet. Ce fichier est utilisé pour recréer le fichier de cache CMake, par exemple, après une opération Clean.

Pour ajouter une autre configuration, cliquez avec le bouton droit sur CMakeSettings.json et choisissez Ajouter une configuration.

Vous pouvez également modifier le fichier en utilisant l’éditeur de paramètres CMake. Cliquez avec le bouton droit sur CMakeSettings.json dans l’Explorateur de solutions et choisissez Modifier les paramètres CMake. Ou sélectionnez Gérer les configurations dans la liste déroulante de configuration en haut de la fenêtre de l’éditeur.

Vous pouvez également modifier directement CMakeSettings.json pour créer des configurations personnalisées. L’exemple suivant illustre une configuration, que vous pouvez utiliser comme point de départ :

    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    },

JSON IntelliSense vous permet de modifier le fichier CMakeSettings.json :

Pour plus d’informations sur chacune des propriétés dans le fichier, consultez Informations de référence sur le schéma CMakeSettings.json.