Partager via

CMakePresets.json et cartes CMakeUserPresets.json des fournisseurs Microsoft

  • Article

CMake prend en charge deux fichiers et CMakePresets.json CMakeUserPresets.json, qui permettent aux utilisateurs de spécifier des options courantes de configuration, de génération et de test, et de les partager avec d’autres utilisateurs.

CMakePresets.json et CMakeUserPresets.json peut être utilisé pour piloter CMake dans Visual Studio, dans Visual Studio Code, dans un pipeline d’intégration continue (CI) et à partir de la ligne de commande.

CMakePresets.json est destiné à enregistrer des builds à l’échelle du projet et CMakeUserPresets.json est destiné aux développeurs d’enregistrer leurs propres builds locales. Le schéma des deux fichiers est identique.

CMakePresets.json et CMakeUserPresets.json de prendre en charge les mappages des fournisseurs pour stocker des informations spécifiques au fournisseur. Microsoft gère deux mappages de fournisseurs avec des options spécifiques à Visual Studio et Visual Studio Code. Ici, nous documentons deux cartes de fournisseurs Microsoft et macros de fournisseur. Pour plus d’informations sur le reste du schéma, consultez la documentation CMake officielle. Il inclut des informations sur la configuration des présélections, des présélections de build et des présélections de test.

Pour plus d’informations sur l’utilisation CMakePresets.json dans Visual Studio, consultez Configurer et générer avec des présélections CMake dans Visual Studio

Pour plus d’informations sur l’utilisation CMakePresets.json dans Visual Studio Code, consultez Configurer et générer avec des présélections CMake dans VS Code

Carte du fournisseur des paramètres Visual Studio

Un fournisseur mappé avec l’URI microsoft.com/VisualStudioSettings/CMake/<version> du fournisseur est autorisé par présélection de configuration et contient des options spécifiques à l’intégration CMake dans Visual Studio et Visual Studio Code. Toutes les options de la carte fournisseur s’appliquent à Visual Studio. Les options qui s’appliquent à Visual Studio et Visual Studio Code ont été marquées explicitement.

Tous les paramètres de la carte du fournisseur des paramètres Visual Studio sont facultatifs et hérités des présélections spécifiées par la inherits clé. Seules les options qui ont été modifiées sont écrites dans le fichier. La carte du fournisseur des paramètres Visual Studio est prise en charge par les deux CMakePresets.json et CMakeUserPresets.jsonles deux.

Les options de la carte du fournisseur des paramètres Visual Studio n’affectent pas la construction de la ligne de commande CMake ou CTest. Il est donc possible d’utiliser le même CMakePresets.json fichier pour piloter CMake avec Visual Studio, Visual Studio Code et à partir de la ligne de commande. Les exceptions sont les options et cmakeGenerateCommand les cacheRoot options. Ces options sont spécifiques au scénario Open Existing Cache dans Visual Studio et ne peuvent pas être reproduites à partir de la ligne de commande.

Setting Description
hostOS Tableau de systèmes d’exploitation pris en charge. Les valeurs acceptées sont Windows, Linux et macOS.

La valeur de celle-ci hostOS est utilisée par Visual Studio et Visual Studio Code pour masquer les présélections qui ne s’appliquent pas au système d’exploitation du système cible et offrent une meilleure expérience utilisateur.

S’il hostOS n’est pas spécifié, Visual Studio et Visual Studio Code affichent toujours toutes les présélections de configuration pour la sélection. Ce champ peut également être une chaîne, qui équivaut à un tableau contenant une chaîne

Cette option est prise en charge par Visual Studio et Visual Studio Code.
intelliSenseMode Spécifie le mode utilisé pour l’informatique des informations IntelliSense dans Visual Studio au format <target>-<toolset>-<arch>.

Valeurs acceptées :

android-clang-arm
android-clang-arm64
android-clang-x6
android-clang-x86
ios-clang-ar
ios-clang-arm64
ios-clang-x6
ios-clang-x86
linux-gcc-arm
linux-gcc-x64
linux-gcc-x86
windows-clang-arm
windows-clang-arm64
windows-clang-x64
windows-clang-x86
windows-msvc-arm
windows-msvc-arm64
windows-msvc-x64
windows-msvc-x86

S’il intelliSenseMode n’est pas spécifié, Visual Studio utilise le mode IntelliSense qui correspond à vos compilateurs et architecture cible spécifiés. intelliSenseMode est souvent utilisé pour fournir intelliSense amélioré pour la compilation croisée.

Dans Visual Studio 2019, vous devez spécifier explicitement un mode IntelliSense clang lors de la génération avec clang ou clang-cl.
intelliSenseOptions Carte des options de configuration IntelliSense supplémentaires.

useCompilerDefaults: qui bool spécifie s’il faut utiliser le compilateur par défaut définit et inclut des chemins d’accès pour IntelliSense. Doit être false uniquement si les compilateurs en cours d’utilisation ne prennent pas en charge les arguments de style gcc. La valeur par défaut est true.

additionalCompilerArgs: tableau d’options supplémentaires pour contrôler IntelliSense dans Visual Studio. Cette option prend en charge l’expansion des macros.
enableMicrosoftCodeAnalysis Qui bool active l’analyse du code Microsoft dans Visual Studio lors de la génération avec cl ou clang-cl. La valeur par défaut est false.
codeAnalysisRuleset Spécifie l’ensemble de règles à utiliser lors de l’exécution de l’analyse du code Microsoft dans Visual Studio. Vous pouvez utiliser un chemin d’accès à un fichier d’ensemble de règles ou le nom d’un fichier d’ensemble de règles installé avec Visual Studio. Cette option prend en charge l’expansion des macros.
disableExternalAnalysis Qui bool spécifie si l’analyse du code doit s’exécuter sur des en-têtes externes dans Visual Studio.
codeAnalysisExternalRuleset Spécifie l’ensemble de règles à utiliser lors de l’exécution de l’analyse du code Microsoft sur un en-tête externe dans Visual Studio. Vous pouvez utiliser un chemin d’accès à un fichier d’ensemble de règles ou le nom d’un fichier d’ensemble de règles installé avec Visual Studio. Cette option prend en charge l’expansion des macros.
enableClangTidyCodeAnalysis Bool qui active l’analyse du code clang-tidy dans Visual Studio lors de la génération avec clang-cl. La valeur par défaut est false.
clangTidyChecks Liste séparée par des virgules des avertissements passés à clang-tidy lors de l’exécution de l’analyse du code clang-tidy dans Visual Studio. Les caractères génériques sont autorisés et le - préfixe supprime les vérifications.
cacheRoot Spécifie le chemin d’accès à un cache CMake. Ce répertoire doit contenir un fichier existant CMakeCache.txt . Cette clé est uniquement prise en charge par le scénario Open Existing Cache dans Visual Studio. Cette option prend en charge l’expansion des macros.
cmakeGenerateCommand Outil en ligne de commande (spécifié en tant que programme de ligne de commande et arguments, par exemple gencache.bat debug) pour générer le cache CMake. Cette commande s’exécute dans l’interpréteur de commandes à l’aide de l’environnement spécifié de la présélection lorsque la configuration CMake est appelée. Cette clé est uniquement prise en charge par le scénario Open Existing Cache dans Visual Studio. Cette option prend en charge l’expansion des macros.

Carte des paramètres distants visual Studio

Un fournisseur mappé avec l’URI microsoft.com/VisualStudioRemoteSettings/CMake/<version> du fournisseur est autorisé par présélection de configuration et contient des options spécifiques au développement à distance dans Visual Studio. Le développement à distance signifie que vous appelez CMake sur une connexion SSH distante ou WSL. Aucune des options de la carte des paramètres distants visual Studio ne s’applique à Visual Studio Code.

Tous les paramètres de la carte des paramètres distants de Visual Studio sont facultatifs et hérités des présélections spécifiées par la inherits clé. Seules les options qui ont été modifiées sont écrites dans le fichier. Le mappage des paramètres distants visual Studio est pris en charge par les deux CMakePresets.json et CMakeUserPresets.jsonles deux.

Les options de la carte du fournisseur des paramètres Visual Studio n’affectent pas la construction de la ligne de commande CMake ou CTest. Il est donc possible d’utiliser le même CMakePresets.json fichier pour piloter CMake avec Visual Studio, Visual Studio Code et à partir de la ligne de commande.

La plupart des options de la carte des paramètres distants de Visual Studio sont ignorées lors du ciblage de WSL1. C’est parce que l’ensemble d’outils WSL1 exécute toutes les commandes localement et s’appuie sur les lecteurs Windows montés sous le /mnt dossier pour accéder aux fichiers sources locaux à partir de WSL1. Aucune copie de fichier source n’est requise. Les options qui sont ignorées lors du ciblage de WSL1 ont été marquées explicitement.

Setting Description
sourceDir Chemin d’accès au répertoire sur le système distant où le projet sera copié. La valeur par défaut est $env{HOME}/.vs/$ms{projectDirName}. Cette option prend en charge l’expansion des macros.

Dans les scénarios de copie à distance, la macro prend la valeur ${sourceDir} du répertoire source du projet sur le système distant et non le répertoire source du projet sur l’ordinateur Windows. Les scénarios de copie à distance incluent le ciblage d’une connexion SSH distante. Dans ces cas, le répertoire source du projet sur le système distant est déterminé par la valeur du mappage des paramètres distants de sourceDir Visual Studio. Cette option est ignorée lors du ciblage de WSL1.
copySources Si true, Visual Studio copie les sources de Windows vers le système distant. Définissez la valeur si false vous gérez vous-même la synchronisation de fichiers. La valeur par défaut est true. Cette option est ignorée lors du ciblage de WSL1.
copySourcesOptions Objet d’options liées à la copie source de Windows vers le système distant. Cet objet est ignoré lors du ciblage de WSL1.

copySourcesOptions.exclusionList: liste de chemins à exclure lors de la copie de fichiers sources vers le système distant. Un chemin d’accès peut être le nom d’un fichier ou d’un répertoire, ou un chemin relatif à partir de la racine de la copie. La valeur par défaut est [ ".vs", ".git", "out" ]. Cette option prend en charge l’expansion des macros.

copySourcesOptions.method: méthode utilisée pour copier des fichiers sources vers le système distant. Les valeurs acceptées sont rsync et sftp. La valeur par défaut est rsync.

copySourcesOptions.concurrentCopies: nombre de copies simultanées utilisées pendant la synchronisation des sources vers le système distant. La valeur par défaut est 5.

copySourcesOptions.outputVerbosity: niveau de détail des opérations de copie source vers le système distant. Les niveaux acceptés sont Normal, Verboseet Diagnostic. La valeur par défaut est Normal.
rsyncCommandArgs Liste des arguments de ligne de commande passés à rsync. La valeur par défaut est [ "-t", "--delete", "--delete-excluded" ]. Cette option prend en charge l’expansion des macros et est ignorée lors du ciblage de WSL1.
copyBuildOutput Spécifie s’il faut copier la sortie de build du système distant vers Windows. La valeur par défaut est false. Cette option est ignorée lors du ciblage de WSL1.
copyOptimizations Objet d’options liées aux optimisations de copie source. Ces options sont ignorées lors du ciblage de WSL1.

copyOptimizations.maxSmallChange: nombre maximal de fichiers à copier à l’aide de sftp au lieu de rsync. La valeur par défaut est 10.

copyOptimizations.useOptimizations: spécifie les optimisations de copie en cours d’utilisation. Les valeurs acceptées ne sont pas des optimisations de copie (None), des optimisations rsync uniquement (RsyncOnly) ou des optimisations rsync et sftp (RsyncAndSftp). La valeur par défaut est RsyncAndSftp.

copyOptimizations.rsyncSingleDirectoryCommandArgs: liste d’arguments de ligne de commande passés à rsync lors de la copie du contenu d’un répertoire unique vers le système distant. La valeur par défaut est [ "-t", "-d" ]. Cette option prend en charge l’expansion des macros.
copyAdditionalIncludeDirectoriesList Liste des chemins d’accès aux répertoires d’en-tête distants à copier localement pour IntelliSense. Cette option prend en charge l’expansion des macros.
copyExcludeDirectoriesList Liste des chemins d’accès aux répertoires d’en-tête distants à ne pas copier localement pour IntelliSense. Cette option prend en charge l’expansion des macros.
forceWSL1Toolset Si true, Visual Studio utilise toujours l’ensemble d’outils WSL1 lors du ciblage de WSL à partir de Visual Studio. L’ensemble d’outils WSL1 exécute toutes les commandes localement et s’appuie sur les lecteurs Windows montés sous le /mnt dossier pour accéder aux fichiers sources locaux à partir de WSL. Ces options peuvent être plus lentes avec WSL2. La valeur par défaut est false.

L’ensemble d’outils WSL1 sera toujours utilisé dans Visual Studio 2019 version 16.10. Cette option sera pertinente une fois la prise en charge native de WSL2 disponible.

Événements de pré-génération et de post-build distants

Les options d’un remotePrebuildEvent et remotePostbuildEvent ont été déconseillées avec l’adoption de CMakePresets.json.

Encoder des événements de pré-génération, de pré-liaison et de post-génération dans votre CMakeLists.txt utilisation add_custom_command. Il garantit le même comportement lors de la génération avec Visual Studio et à partir de la ligne de commande.

Si vous avez besoin d’un comportement spécifique à Visual Studio, vous pouvez ajouter une tâche distante personnalisée dans tasks.vs.json. Pour commencer, cliquez avec le bouton droit sur votre racine CMakeLists.txt dans le Explorateur de solutions à partir de l’affichage dossier, puis sélectionnez Configurer les tâches. Vous pouvez ensuite ajouter une nouvelle tâche distante à votre tasks.vs.json fichier.

La tâche distante suivante crée un répertoire appelé test sur le système Linux distant :

{
      "taskLabel": "mkdir",
      "appliesTo": "CMakeLists.txt",
      "type": "remote",
      "command": "mkdir test",
      "remoteMachineName": "localhost"
  }

Cliquez avec le bouton droit sur n’importe quelle CMakeLists.txt option et sélectionnez l’option mkdir pour exécuter cette tâche.

La valeur de remoteMachineName doit correspondre au nom d’hôte d’une connexion dans le Gestionnaire des connexions.

Macros du fournisseur Microsoft

Les deux fournisseurs Microsoft mappent et Visual Studio Settings Visual Studio Remote Settingsprennent en charge toutes les macros définies par CMake. Nos cartes fournisseur prennent en charge toutes les macros définies par CMake. Pour plus d’informations, consultez l’extension macro cmake-presets. Toutes les macros et variables d’environnement sont développées avant d’être passées à CMake.

Visual Studio prend en charge les macros de fournisseur avec le préfixe ms. Les macros de fournisseur Microsoft ne peuvent être utilisées que dans les cartes des fournisseurs Microsoft. CMake ne peut pas utiliser de présélections qui ont des macros de fournisseur en dehors d’une carte de fournisseur.

Macro Description
$ms{projectDirName} Évalue le nom du dossier ouvert dans Visual Studio. Cette macro est utilisée pour définir la valeur par défaut dans les scénarios de sourceDir copie à distance. Cette macro n’est pas prise en charge par Visual Studio Code. Utilisez ${sourceDirName} à la place.

Variables d'environnement

Macro Description
$env{<variable-name>}
$penv{<variable-name>}		 Variables d’environnement de référence à l’aide de cette syntaxe prise en charge par CMake. Pour plus d’informations, consultez l’extension macro cmake-presets.

Macros déconseillées

Quelques macros prises en charge par CMakeSettings.json ont été dépréciées avec l’adoption de CMakePresets.json.

Utilisez les macros prises en charge par CMake pour construire vos chemins de fichier. Lorsque vous utilisez les macros, cela garantit que le même CMakePresets.json fichier fonctionne à l’intérieur de Visual Studio et à partir de la ligne de commande.

Macro déconseillée Recommandation
${projectFile} ${sourceDir}/CMakeLists.txt
${thisFile} ${sourceDir}/CMakePresets.json

Syntaxe d’interpréteur de commandes acceptée

Utilisez la syntaxe pour référencer $HOME lors de la $env{HOME} construction de chemins Linux dans les mappages du fournisseur Microsoft.