`CMakeSettings.json` Informations de référence sur le schéma

Article
04/03/2023

Les projets CMake sont pris en charge dans Visual Studio 2017 et versions ultérieures.

Le CMakeSettings.json fichier contient des informations que Visual Studio utilise pour IntelliSense et pour construire les arguments de ligne de commande qu’il transmet à CMake pour une configuration et un environnement de compilateur spécifiés. Une configuration spécifie les propriétés qui s’appliquent à une plateforme et un type de build spécifiques, par exemple, x86-Debug ou Linux-Release. Chaque configuration spécifie un environnement, qui encapsule des informations sur l’ensemble d’outils du compilateur, par exemple MSVC, GCC ou Clang. CMake utilise les arguments de ligne de commande pour régénérer le fichier racine CMakeCache.txt et d’autres fichiers projet pour le projet. Les valeurs peuvent être substituées dans les CMakeLists.txt fichiers.

Vous pouvez ajouter ou supprimer des configurations dans l’IDE, puis les modifier directement dans le fichier JSON ou utiliser l’éditeur de Paramètres CMake (Visual Studio 2019 et versions ultérieures). Vous pouvez basculer facilement entre les configurations de l’IDE pour générer les différents fichiers projet. Pour plus d’informations, consultez Personnaliser les paramètres de build CMake dans Visual Studio.

Configurations

Le configurations tableau contient toutes les configurations d’un projet CMake. Pour plus d’informations sur les configurations prédéfinies, consultez la référence de configuration prédéfinie CMake. Vous pouvez ajouter n’importe quel nombre de configurations prédéfinies ou personnalisées au fichier.

Une configuration a les propriétés suivantes :

addressSanitizerEnabled: Si true, compile le programme à l’aide de AddressSanitizer. Sur Linux, compilez avec -fno-omit-frame-pointer le niveau -Os d’optimisation du compilateur ou -Oo pour obtenir de meilleurs résultats.
addressSanitizerRuntimeFlags: indicateurs d’exécution passés à AddressSanitizer dans la variable d’environnement ASAN_OPTIONS . Format : flag1=value :flag2=value2.
buildCommandArgs: spécifie les commutateurs de build natifs passés à CMake après --build --. Par exemple, le passage -v lors de l’utilisation du générateur Ninja force Ninja à générer des lignes de commande. Pour plus d’informations sur les commandes Ninja, consultez les arguments de ligne de commande Ninja.
buildRoot: spécifie le répertoire dans lequel CMake génère des scripts de génération pour le générateur choisi. Cartes à -DCMAKE_BINARY_DIR basculer et spécifie l’emplacement où CMakeCache.txt est créé. Si le dossier n’existe pas, il est créé. Les macros prises en charge incluent ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.
cacheGenerationCommand: spécifie un outil en ligne de commande et des arguments, par exemple gencache.bat debug pour générer le cache. La commande est exécutée à partir de l’interpréteur de commandes dans l’environnement spécifié pour la configuration lorsque l’utilisateur demande explicitement la régénération, ou qu’un ou CMakeSettings.json un CMakeLists.txt fichier est modifié.
cacheRoot: spécifie le chemin d’accès à un cache CMake. Ce répertoire doit contenir un fichier existant CMakeCache.txt .
clangTidyChecks: liste séparée par des virgules des avertissements passés à clang-tidy ; les caractères génériques carte sont autorisés et un préfixe « - » supprime les case activée s.
cmakeCommandArgs: spécifie toutes les options de ligne de commande supplémentaires à passer à CMake lorsqu’elles sont appelées pour générer les fichiers projet.
cmakeToolchain: spécifie le fichier de chaîne d’outils. Il est passé à CMake à l’aide -DCMAKE_TOOLCHAIN_FILE.
codeAnalysisRuleset: spécifie l’ensemble de règles à utiliser lors de l’exécution de l’analyse du code. Vous pouvez utiliser un chemin d’accès complet ou le nom de fichier d’un jeu de règles installé par Visual Studio.
configurationType: spécifie la configuration du type de build pour le générateur sélectionné. Possibilités :
- Debug
- Release
- MinSizeRel
- RelWithDebInfo
ctestCommandArgs: spécifie toutes les options de ligne de commande supplémentaires à passer à CTest lors de l’exécution des tests.
description: description de cette configuration qui apparaît dans les menus.
enableClangTidyCodeAnalysis: Utilisez Clang-Tidy pour l’analyse du code.
enableMicrosoftCodeAnalysis: Utilisez les outils d’analyse de code Microsoft pour l’analyse du code.
generator: spécifie le générateur CMake à utiliser pour cette configuration. Possibilités :

Visual Studio 2019 uniquement :
- Visual Studio 16 2019
- Visual Studio 16 2019 Win64
- Visual Studio 16 2019 ARM
Visual Studio 2017 et ultérieur :
- 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
- Unix Makefiles
- Ninja

Étant donné que Ninja est conçu pour des vitesses de génération rapides au lieu de flexibilité et de fonction, il est défini comme valeur par défaut. Toutefois, certains projets CMake peuvent ne pas pouvoir être générés correctement avec Ninja. Si une défaillance de build se produit, vous pouvez demander à CMake de générer des projets Visual Studio à la place.

Pour spécifier un générateur Visual Studio dans Visual Studio 2017, ouvrez l’éditeur de paramètres dans le menu principal en choisissant CMake | Modifiez le Paramètres CMake. Supprimez « Ninja » et entrez « V ». Cette modification active IntelliSense, ce qui vous permet de choisir le générateur souhaité.

Pour spécifier un générateur Visual Studio dans Visual Studio 2019, cliquez avec le bouton droit sur le CMakeLists.txt fichier dans Explorateur de solutions et choisissez CMake Paramètres pour le projet>Show Advanced Paramètres> CMake Generator.

Par défaut, lorsque la configuration active spécifie un générateur Visual Studio, elle appelle MSBuild avec -m -v:minimal des arguments. Pour personnaliser la build, utilisez la buildCommandArgs propriété à l’intérieur du CMakeSettings.json fichier. Ici, vous pouvez spécifier des arguments de ligne de commande MSBuild à passer au système de génération :

"buildCommandArgs": "-m:8 -v:minimal -p:PreferredToolArchitecture=x64"

installRoot: spécifie le répertoire dans lequel CMake génère des cibles d’installation pour le générateur choisi. Les macros prises en charge incluent ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.
inheritEnvironments: spécifie un ou plusieurs environnements de compilateur dont dépend cette configuration. Il peut s’agir de tout environnement personnalisé ou de l’un des environnements prédéfinis. Pour plus d’informations, consultez Environnements.
intelliSenseMode: spécifie le mode utilisé pour l’informatique des informations IntelliSense ». La valeur peut être l’une des suivantes :
- windows-msvc-x86
- windows-msvc-x64
- windows-msvc-arm
- windows-msvc-arm64
- android-clang-x86
- android-clang-x64
- android-clang-arm
- android-clang-arm64
- ios-clang-x86
- ios-clang-x64
- ios-clang-arm
- ios-clang-arm64
- windows-clang-x86
- windows-clang-x64
- windows-clang-arm
- windows-clang-arm64
- linux-gcc-x86
- linux-gcc-x64
- linux-gcc-arm
name : nomme la configuration. Pour plus d’informations sur les configurations prédéfinies, consultez la référence de configuration prédéfinie CMake.
wslPath: chemin d’accès au lanceur d’une instance de Sous-système Windows pour Linux.

Paramètres pour les projets Linux CMake

remoteMachineName: spécifie le nom de la machine Linux distante qui héberge CMake, les builds et le débogueur. Utilisez le gestionnaire de connexions pour l’ajout de nouvelles machines Linux. Les macros prises en charge incluent ${defaultRemoteMachineName}.
remoteCopySourcesOutputVerbosity: spécifie le niveau de détail de l’opération de copie source sur l’ordinateur distant. Peut être l’un des Normal, Verboseou Diagnostic.
remoteCopySourcesConcurrentCopies: spécifie les copies simultanées à utiliser pendant la synchronisation des sources sur l’ordinateur distant (sftp uniquement).
remoteCopySourcesMethod: spécifie la méthode permettant de copier des fichiers sur l’ordinateur distant. Peut être rsync ou sftp.
remoteCMakeListsRoot: spécifie le répertoire sur l’ordinateur distant qui contient le projet CMake. Les macros prises en charge incluent ${workspaceRoot}, , ${workspaceHash}${projectFile}, ${name}${projectDir}${thisFileDir}${thisFile}${generator}et .${env.VARIABLE}
remoteBuildRoot: spécifie le répertoire sur l’ordinateur distant dans lequel CMake génère des scripts de génération pour le générateur choisi. Les macros prises en charge incluent ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.
remoteInstallRoot: spécifie le répertoire sur l’ordinateur distant dans lequel CMake génère des cibles d’installation pour le générateur choisi. Les macros prises en charge incluent ${workspaceRoot}, ${thisFile}${thisFileDir}${name}${generator}${projectFile}${projectDir}${workspaceHash}et , où ${env.VARIABLE}VARIABLE est une variable d’environnement qui a été définie au niveau du système, de l’utilisateur ou de la session.
remoteCopySources: qui boolean spécifie si Visual Studio doit copier des fichiers sources sur l’ordinateur distant. La valeur par défaut est true. Affectez la valeur false si vous gérez vous-même la synchronisation des fichiers.
remoteCopyBuildOutput: qui boolean spécifie s’il faut copier les sorties de build à partir du système distant.
remoteCopyAdditionalIncludeDirectories: ajout de répertoires include à copier à partir de l’ordinateur distant pour prendre en charge IntelliSense. Mettez en forme « /path1 ;/path2... ».
remoteCopyExcludeDirectories: incluez les répertoires NON à copier à partir de l’ordinateur distant. Mettez en forme « /path1 ;/path2... ».
remoteCopyUseCompilerDefaults: spécifie s’il faut utiliser les définitions par défaut du compilateur et inclure des chemins d’accès pour IntelliSense. Ne doit être false que si les compilateurs en cours d’utilisation ne prennent pas en charge les arguments de style gcc.
rsyncCommandArgs: spécifie un ensemble d’options de ligne de commande passées à rsync.
remoteCopySourcesExclusionList: qui array spécifie une liste de chemins à exclure lors de la copie de fichiers sources : un chemin d’accès peut être le nom d’un fichier/répertoire ou un chemin relatif à partir de la racine de la copie. Wild carte s * et ? peut être utilisé pour la mise en correspondance des modèles glob.
cmakeExecutable: spécifie le chemin complet de l’exécutable du programme CMake, y compris le nom de fichier et l’extension.
remotePreGenerateCommand: spécifie la commande à exécuter avant d’exécuter CMake pour analyser le CMakeLists.txt fichier.
remotePrebuildCommand: spécifie la commande à exécuter sur l’ordinateur distant avant la génération.
remotePostbuildCommand: spécifie la commande à exécuter sur l’ordinateur distant après la génération.
variables: contient une paire nom-valeur de variables CMake qui sont transmises en tant que -D name=value CMake. Si vos instructions de génération de projet CMake spécifient l’ajout de toutes les variables directement au fichier, nous vous recommandons de les ajouter ici à la CMakeCache.txt place. Cet exemple montre comment spécifier les paires nom-valeur pour utiliser l’ensemble d’outils MSVC 14.14.26428 :

"variables": [
    {
      "name": "CMAKE_CXX_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    },
    {
      "name": "CMAKE_C_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    }
  ]

Si vous ne définissez pas le "type"type, le "STRING" type est supposé par défaut.

remoteCopyOptimizations: Propriétés Visual Studio 2019 version 16.5 ou ultérieures pour contrôler la copie source vers la cible distante. Les optimisations sont activées par défaut. Inclut remoteCopyUseOptimizations, rsyncSingleDirectoryCommandArgset remoteCopySourcesMaxSmallChange.

Environnements

Un environnement encapsule les variables d’environnement définies dans le processus que Visual Studio utilise pour appeler CMake. Pour les projets MSVC, il capture les variables définies dans une invite de commandes développeur pour une plateforme spécifique. Par exemple, l’environnement msvc_x64_x64 est identique à l’exécution de l’invite de commandes développeur pour VS {version} avec les arguments -arch=amd64 -host_arch=amd64 . Vous pouvez utiliser la env.{<variable_name>} syntaxe pour CMakeSettings.json référencer les variables d’environnement individuelles, par exemple pour construire des chemins d’accès aux dossiers. Les environnements prédéfinis suivants sont fournis :

linux_arm: Ciblez LINUX ARM à distance.
linux_x64: Cible x64 Linux à distance.
linux_x86: Ciblez linux x86 à distance.
msvc_arm: Ciblez Windows ARM avec le compilateur MSVC.
msvc_arm_x64: Ciblez Windows ARM avec le compilateur MSVC 64 bits.
msvc_arm64: Ciblez ARM64 Windows avec le compilateur MSVC.
msvc_arm64_x64: Ciblez ARM64 Windows avec le compilateur MSVC 64 bits.
msvc_arm64ec: ciblez ARM64EC Windows avec le compilateur MSVC.
msvc_arm64ec_x64: Ciblez ARM64EC Windows avec le compilateur MSVC 64 bits.
msvc_x64: Ciblez x64 Windows avec le compilateur MSVC.
msvc_x64_x64: Ciblez x64 Windows avec le compilateur MSVC 64 bits.
msvc_x86: Ciblez x86 Windows avec le compilateur MSVC.
msvc_x86_x64: Ciblez x86 Windows avec le compilateur MSVC 64 bits.

Accès aux variables d’environnement à partir de `CMakeLists.txt`

À partir d’un fichier, toutes les variables d’environnement CMakeLists.txt sont référencées par la syntaxe $ENV{variable_name}. Pour afficher les variables disponibles pour un environnement, ouvrez l’invite de commandes correspondante et tapez SET. Certaines des informations contenues dans les variables d’environnement sont également disponibles via les variables d’introduction au système CMake, mais vous pouvez trouver plus pratique d’utiliser la variable d’environnement. Par exemple, vous pouvez facilement récupérer la version du compilateur MSVC ou la version du Kit de développement logiciel (SDK) Windows via les variables d’environnement.

Variables d’environnement personnalisées

Dans CMakeSettings.json, vous pouvez définir des variables d’environnement personnalisées globalement ou par configuration dans le environments tableau. Un environnement personnalisé est un moyen pratique de regrouper un ensemble de propriétés. Vous pouvez l’utiliser à la place d’un environnement prédéfini, ou pour étendre ou modifier un environnement prédéfini. Chaque élément dans le tableau environments comprend ce qui suit :

namespace: nomme l’environnement afin que ses variables puissent être référencées à partir d’une configuration au format namespace.variable. L’objet environnement par défaut est appelé env et il est rempli avec certaines variables d’environnement système, notamment %USERPROFILE%.
environment: identifie de façon unique ce groupe de variables. Permet au groupe d’être hérité plus tard dans une entrée inheritEnvironments.
groupPriority: entier qui spécifie la priorité de ces variables lors de leur évaluation. Les éléments dont la valeur est élevée sont évalués en premier.
inheritEnvironments: tableau de valeurs qui spécifient l’ensemble d’environnements hérités par ce groupe. Cette fonctionnalité vous permet d’hériter des environnements par défaut et de créer des variables d’environnement personnalisées à passer à CMake lors de son exécution.

Visual Studio 2019 version 16.4 et ultérieure : les cibles de débogage sont automatiquement lancées avec l’environnement dans CMakeSettings.jsonlequel vous spécifiez . Vous pouvez remplacer ou ajouter des variables d’environnement par cible ou par tâche dans launch.vs.json et tasks.vs.json.

L’exemple suivant définit une variable globale, BuildDirhéritée à la fois dans les configurations x86-Debug et x64-Debug. Chaque configuration utilise la variable pour spécifier la valeur de la buildRoot propriété pour cette configuration. Notez également comment chaque configuration utilise la inheritEnvironments propriété pour spécifier une variable qui s’applique uniquement à cette configuration.

{
  // The "environments" property is an array of key-value pairs of the form
  // { "EnvVar1": "Value1", "EnvVar2": "Value2" }
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x86 compiler.
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.BuildDir}\\${name}"    },
    {
      "name": "x64-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x64 compiler.
      "inheritEnvironments": [ "msvc_x64" ],
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

Dans l’exemple suivant, la configuration x86-Debug définit sa propre valeur pour la propriété BuildDir. Cette valeur remplace celle définie par la propriété BuildDir globales pour que BuildRoot prenne la valeur D:\custom-builddir\x86-Debug.

{
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",

      // The syntax for this property is the same as the global one above.
      "environments": [
        {
          // Replace the global property entirely.
          "BuildDir": "D:\\custom-builddir"
          // This environment does not specify a namespace, hence by default "env" is assumed.
          // "namespace" : "name" would require that this variable be referenced with "${name.BuildDir}".
        }
      ],

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      // Evaluates to "D:\custom-builddir\x86-Debug"
      "buildRoot": "${env.BuildDir}\\${name}"
    },
    {
      "name": "x64-Debug",

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x64" ],
      // Since this configuration doesn't modify BuildDir, it inherits
      // from the one defined globally.
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

Macros

Les macros suivantes peuvent être utilisées dans CMakeSettings.json:

${workspaceRoot} : chemin d’accès complet du dossier de l’espace de travail
${workspaceHash} : Hachage de l’emplacement de l’espace de travail. Utile pour créer un identificateur unique pour l’espace de travail actuel (par exemple, à utiliser dans les chemins de dossier)
${projectFile}: chemin d’accès complet du fichier racine CMakeLists.txt
${projectDir}: chemin d’accès complet du dossier contenant le fichier racine CMakeLists.txt
${projectDirName}: nom du dossier contenant le fichier racine CMakeLists.txt
${thisFile} : chemin d’accès complet du CMakeSettings.json fichier
${name} : Nom de la configuration
${generator} : Nom du générateur CMake utilisé dans cette configuration

Toutes les références aux macros et variables d’environnement sont CMakeSettings.json développées avant d’être passées à la ligne de commande CMake.

Arguments de ligne de commande Ninja

Si les cibles ne sont pas spécifiées, Ninja génère la cible « par défaut ».

C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise>ninja -?
ninja: invalid option -- `-?'
usage: ninja [options] [targets...]

Option	Description
`--version`	Imprimer la version ninja (« 1.7.1 »)
`-C DIR`	Passer à DIR avant d’effectuer autre chose
`-f FILE`	Spécifier le fichier de build d’entrée (default=`build.ninja`)
`-j N`	Exécuter des `N` travaux en parallèle (par défaut=14, dérivé de processeurs disponibles)
`-k N`	Continuez jusqu’à ce que `N` les travaux échouent (par défaut=1)
`-l N`	Ne démarrez pas de nouveaux travaux si la moyenne de charge est supérieure à `N`
`-n`	Exécution sèche (n’exécutez pas de commandes, mais agissez comme elles ont réussi)
`-v`	Afficher toutes les lignes de commande lors de la génération
`-d MODE`	Activer le débogage (utiliser `-d list` pour répertorier les modes)
`-t TOOL`	Exécutez un sous-outil (utilisez `-t list` pour répertorier les sous-outils). Termine toutes les options de niveau supérieur ; d’autres indicateurs sont passés à l’outil
`-w FLAG`	Ajuster les avertissements (utiliser `-w list` pour répertorier les avertissements)

Partager via

`CMakeSettings.json` Informations de référence sur le schéma

Configurations

Paramètres pour les projets Linux CMake

Environnements

Accès aux variables d’environnement à partir de `CMakeLists.txt`

Variables d’environnement personnalisées

Macros

Arguments de ligne de commande Ninja

Commentaires

Commentaires

Ressources supplémentaires

Partager via

CMakeSettings.json Informations de référence sur le schéma

Configurations

Paramètres pour les projets Linux CMake

Environnements

Accès aux variables d’environnement à partir de CMakeLists.txt

Variables d’environnement personnalisées

Macros

Arguments de ligne de commande Ninja

Commentaires

Commentaires

Ressources supplémentaires

`CMakeSettings.json` Informations de référence sur le schéma

Accès aux variables d’environnement à partir de `CMakeLists.txt`