Projets CMake dans Visual Studio

CMake est un outil open source multiplateforme qui permet de définir des processus de génération qui s’exécutent sur plusieurs plateformes. Cet article suppose que vous êtes familiarisé avec CMake. Pour plus d’informations sur CMake, consultez la documentation CMake. Le tutoriel CMake est un bon point de départ pour en savoir plus.

Notes

CMake est de plus en plus intégré à Visual Studio au cours des dernières versions. Pour afficher la documentation relative à votre version préférée de Visual Studio, utilisez le contrôle de sélecteur version . Il se trouve en haut de la table des matières de cette page.

La prise en charge native de Visual Studio pour CMake vous permet de modifier, de générer et de déboguer des projets CMake sur Windows, le Sous-système Windows pour Linux (WSL) et des systèmes distants à partir des mêmes instance de Visual Studio. Les fichiers projet CMake (tels que CMakeLists.txt) sont consommés directement par Visual Studio à des fins d’IntelliSense et de navigation. cmake.exe est appelé directement par la configuration et la build de Visual Studio pour CMake.

Installation

Les outils C++ CMake pour Windows sont installés dans le cadre du développement de bureau avec C++ et du développement Linux avec les charges de travail C++. Les outils CMake C++ pour Windows et Linux avec C++ sont requis pour le développement CMake multiplateforme.

Pour plus d’informations, consultez Installer la charge de travail Linux C++ dans Visual Studio.

Intégration de l’IDE

Lorsque vous ouvrez un dossier contenant un CMakeLists.txt fichier, les choses suivantes se produisent.

• Visual Studio ajoute des éléments CMake au menu Projet , avec des commandes permettant d’afficher et de modifier des scripts CMake.

• Le Explorateur de solutions affiche la structure de dossiers et les fichiers.

• Visual Studio exécute CMake et génère le fichier de cache CMake (CMakeCache.txt) pour la configuration par défaut. La ligne de commande CMake s’affiche dans la fenêtre Sortie, ainsi que d’autres sorties de CMake.

• En arrière-plan, Visual Studio démarre pour indexer les fichiers sources afin d’activer IntelliSense, les informations de navigation, la refactorisation et ainsi de suite. Pendant que vous travaillez, Visual Studio surveille les changements dans l’éditeur et sur le disque pour synchroniser son index avec les sources.

Notes

À compter de Visual Studio 2022 version 17.1 Preview 2, si votre niveau CMakeLists.txt supérieur existe dans un sous-dossier et non à la racine de l’espace de travail, vous serez invité à indiquer si vous souhaitez activer l’intégration CMake ou non. Pour plus d’informations, consultez Activation partielle CMake.

Une fois que la génération du cache CMake a réussi, vous pouvez également afficher vos projets organisés logiquement par cibles. Choisissez le bouton Sélectionner une vue dans la barre d’outils Explorateur de solutions. Dans la liste de Explorateur de solutions - Affichages, sélectionnez Vue cibles CMake, puis appuyez sur Entrée pour ouvrir la vue cibles :

Choisissez le bouton Afficher tous les fichiers en haut de Explorateur de solutions pour afficher toutes les sorties générées par CMake dans les out/build/<config> dossiers.

Utilisez le fichier dans chaque dossier de projet comme vous le CMakeLists.txt feriez dans n’importe quel projet CMake. Vous pouvez spécifier des fichiers sources, rechercher des bibliothèques, définir des options de compilateur et d’éditeur de liens, et spécifier d’autres informations liées au système de génération. Pour plus d’informations sur les services de langage CMake fournis par Visual Studio, consultez Modification de fichiers CMakeLists.txt.

Visual Studio utilise un fichier de configuration CMake pour piloter la génération et la génération du cache CMake. Pour plus d’informations, consultez Configuration de projets CMake et Création de projets CMake.

Pour passer des arguments à un exécutable au moment du débogage, vous pouvez utiliser un autre fichier appelé launch.vs.json. Pour plus d’informations sur le débogage de projets CMake multiplateformes dans Visual Studio, consultez Débogage de projets CMake.

La plupart des fonctionnalités de langage Visual Studio et C++ sont prises en charge par les projets CMake dans Visual Studio. Voici quelques exemples :

• Modifier et continuer pour les projets CMake

• Intégration Incredibuild pour les projets CMake

• Prise en charge d’AddressSanitizer pour les projets CMake

• Prise en charge de Clang/LLVM

Notes

Pour d’autres types de projets Open Folder, un fichier CppProperties.json JSON supplémentaire est utilisé. Ce fichier n’est pas pertinent pour les projets CMake.

Configuration de projets CMake

L’étape de configuration CMake génère le système de génération de projet. Cela équivaut à appeler cmake.exe à partir de la ligne de commande. Pour plus d’informations sur l’étape de configuration de CMake, consultez la documentation CMake.

Visual Studio utilise un fichier de configuration CMake pour piloter la génération et la génération CMake. CMakePresets.json est pris en charge par Visual Studio 2019 version 16.10 ou ultérieure et est le fichier de configuration CMake recommandé. CMakePresets.json est pris en charge directement par CMake et peut être utilisé pour piloter la génération et la génération 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 des présélections CMake. CMakeSettings.json est disponible pour les clients qui utilisent une version antérieure de Visual Studio. Pour plus d’informations sur CMakeSettings.json, consultez Personnaliser les paramètres de build CMake.

Lorsque vous apportez des modifications importantes à votre fichier de configuration CMake ou à un CMakeLists.txt fichier, Visual Studio exécute automatiquement l’étape de configuration CMake. Vous pouvez appeler l’étape de configuration manuellement : sélectionnez Projet > Configurer le cache dans la barre d’outils. Vous pouvez également modifier vos préférences de configuration dansOptions>d’outils>CMake>Général.

Si l’étape de configuration se termine sans erreur, les informations disponibles pilotent C++ IntelliSense et les services linguistiques. Il est également utilisé dans les opérations de génération et de débogage.

Vous pouvez également ouvrir un cache CMake existant dans Visual Studio. Pour plus d’informations, consultez Ouvrir un cache existant.

Personnaliser les commentaires et notifications de configuration

Par défaut, la plupart des messages de configuration sont supprimés, sauf en cas d’erreur. Pour afficher tous les messages, sélectionnezOptions>d’outils>CMake>Activer la sortie de diagnostic CMake détaillée.

Vous pouvez également désactiver toutes les notifications de cache CMake (barres d’or) en désélectionnant Afficher la notification du cache CMake.

Résolution des erreurs de cache CMake

Si vous avez besoin d’informations supplémentaires sur l’état du cache CMake pour diagnostiquer un problème, ouvrez le menu Project main ou le CMakeLists.txt menu contextuel dans Explorateur de solutions pour exécuter l’une des commandes suivantes :

• Afficher CMakeCache.txt ouvre le CMakeCache.txt fichier à partir du répertoire de build dans l’éditeur. Toutes les modifications que vous apportez ici CMakeCache.txt sont effacées si vous propre le cache. Pour apporter des modifications qui persistent après avoir propre le cache, consultez Personnaliser les paramètres CMake ou Configurer et générer avec des présélections CMake.

• Supprimer le cache et reconfigurer supprime le répertoire de build et reconfigure à partir d’un cache propre.

• Configurer le cache force l’étape de génération à s’exécuter même si Visual Studio considère l’environnement à jour.

Génération de projets CMake

L’étape de génération CMake génère une arborescence binaire de projet déjà générée. Cela équivaut à appeler cmake --build à partir de la ligne de commande. Pour plus d’informations sur l’étape de génération CMake, consultez la documentation CMake.

Pour générer un projet CMake, vous avez ces possibilités :

1. Dans la barre d’outils, recherchez la liste déroulante Élément de démarrage . Sélectionnez la cible préférée et appuyez sur F5, ou choisissez le bouton Exécuter dans la barre d’outils. Le projet est d’abord généré automatiquement, comme une solution Visual Studio.

2. Cliquez avec le bouton droit sur la cible CMake avec la vue Cibles CMake active dans le Explorateur de solutions, puis sélectionnez Générer dans le menu contextuel.

3. Dans le menu main, sélectionnez Générer > tout. Assurez-vous qu’une cible CMake est déjà sélectionnée dans la liste déroulante Élément de démarrage de la barre d’outils.

Comme attendu, les résultats de génération sont affichés dans la fenêtre sortie et la Liste des erreurs.

Modifier les paramètres de build

Visual Studio utilise un fichier de configuration CMake pour piloter les builds CMake. Les fichiers de configuration CMake encapsulent des options de génération telles que les commutateurs d’outils de génération natifs et les variables d’environnement. Si CMakePresets.json est votre fichier de configuration actif, consultez Configurer et générer avec des présélections CMake. Si CMakeSettings.json est votre fichier de configuration actif, consultez Personnaliser les paramètres de build CMake. CMakePresets.json est disponible dans Visual Studio 2019 version 16.10 ou ultérieure et est le fichier de configuration CMake recommandé.

Débogage de projets CMake

Toutes les cibles CMake exécutables sont affichées dans la liste déroulante Élément de démarrage de la barre d’outils. Pour démarrer le débogage, sélectionnez-en un et appuyez sur le bouton Démarrer > le débogage dans la barre d’outils. Dans un projet CMake, l’option « Document actuel » est valide uniquement pour les fichiers .cpp.

Les commandes Déboguer ou F5 créent d’abord le projet si des modifications ont été apportées depuis la build précédente. Les modifications apportées au fichier de configuration CMake (CMakePresets.json ou CMakeSettings.json) ou entraînent CMakeLists.txt la régénération du cache CMake.

Vous pouvez personnaliser une session de débogage CMake en définissant des propriétés dans le fichier launch.vs.json. Pour personnaliser les paramètres de débogage pour une cible spécifique, sélectionnez la cible dans la liste déroulante Élément de démarrage , puis appuyez sur Déboguer > et Lancer les paramètres pour <active-target>. Pour plus d’informations sur les sessions de débogage CMake, consultez Configurer les sessions de débogage CMake.

Juste mon code pour les projets CMake

Lorsque vous générez pour Windows à l’aide du compilateur MSVC, les projets CMake prennent en charge le débogage Juste mon code. Pour modifier le paramètre Juste mon code, accédez à Options d’outils>>Débogage>général.

Modifier et continuer pour les projets CMake

Lorsque vous générez pour Windows avec le compilateur MSVC, les projets CMake prennent en charge l’option Modifier et Continuer. Ajoutez le code suivant à votre CMakeLists.txt fichier pour activer modifier et continuer.

if(MSVC)
  target_compile_options(<target> PUBLIC "/ZI")
  target_link_options(<target> PUBLIC "/INCREMENTAL")
endif()

Attacher à un projet CMake en cours d’exécution sur Linux

Visual Studio vous permet de déboguer un processus s’exécutant sur un système Linux distant ou WSL et de le déboguer avec le débogueur GDB. Pour commencer, sélectionnez Déboguer>attacher au processus..., définissez le type de connexion sur SSH, puis sélectionnez votre cible de connexion dans la liste des connexions dans le Gestionnaire des connexions. Sélectionnez un processus dans la liste des processus disponibles, puis appuyez sur Attacher. GDB doit être installé sur votre ordinateur Linux. Pour plus d’informations sur les connexions SSH, consultez la Gestionnaire des connexions

Activation partielle de CMake

Dans Visual Studio 2022 version 17.1 et ultérieures, la fonctionnalité CMake ne sera pas activée automatiquement si votre dossier racine ne contient pas de CMakeLists.txt fichier. Au lieu de cela, une boîte de dialogue vous indique si vous souhaitez activer la fonctionnalité CMake pour votre projet. Si vous refusez, la génération du cache CMake ne démarre pas et les configurations CMake (à partir de CMakeSettings.json ou CMakePresets.json) n’apparaissent pas dans la liste déroulante de configuration. Si vous acceptez, vous serez redirigé vers un fichier de configuration au niveau de l’espace de travail ( CMakeWorkspaceSettings.json stocké dans le .vs répertoire) pour spécifier les dossiers pour lesquels vous souhaitez activer CMake. (Ces dossiers contiennent vos fichiers racine CMakeLists.txt ).

Les propriétés acceptées sont les suivantes :

Propriété	Description
enableCMake	Activez l’intégration de Visual Studio pour cet espace de travail.
sourceDirectory	Chaîne ou tableau de chaînes spécifiant le ou les répertoires avec CMakeLists.txt. Les macros (telles que ${workspaceRoot}) sont autorisées. Les chemins relatifs sont basés sur la racine de l’espace de travail. Les répertoires en dehors de l’espace de travail actuel seront ignorés.

Vous pouvez accéder CMakeWorkspaceSettings.json via la commandede menu Paramètres de l’espace de travailProject> CMake à tout moment, même si la fonctionnalité CMake est actuellement désactivée.

Ouvrir un cache existant

Lorsque vous ouvrez un fichier de cache CMake existant (CMakeCache.txt), Visual Studio n’essaie pas de gérer votre cache et votre arborescence de génération pour vous. Vos outils personnalisés ou préférés ont un contrôle total sur la façon dont CMake configure votre projet.

Vous pouvez ajouter un cache CMake existant à un projet ouvert. Cela se fait de la même façon que vous ajouteriez une nouvelle configuration. Pour plus d’informations, consultez notre billet de blog sur l’ouverture d’un cache existant dans Visual Studio.

Notes

L’expérience de cache existante par défaut s’appuie sur cmake-server, qui a été supprimé de CMake dans la version 3.20. Pour continuer à utiliser les fonctionnalités de cache existantes dans Visual Studio 2019 version 16.10 et ultérieures, effectuez l’une des étapes suivantes :

• Installez manuellement CMake version 3.19 ou ultérieure. Ensuite, définissez la cmakeExecutable propriété dans votre configuration de cache existante pour utiliser cette version de CMake.
• Dans votre configuration de cache existante, définissez la cacheGenerationCommand propriété pour permettre à Visual Studio de demander les fichiers API basés sur des fichiers CMake nécessaires. Pour plus d’informations sur cette propriété, consultez référence CMakeSettings.json.
• Utilisez un fichier de requête pour demander les fichiers API basés sur un fichier CMake lors de la génération de votre cache avant son ouverture dans Visual Studio. Pour obtenir des instructions sur le fichier de requête, consultez la section suivante, Résolution des problèmes du cache CMake avancé.

Résolution des problèmes avancés du cache CMake

Visual Studio utilise l’API basée sur un fichier CMake (dans les versions 3.14 et ultérieures) pour renseigner l’éditeur avec des informations spécifiques à la structure de votre projet. Pour plus d’informations, consultez le billet de blog de l’équipe C++ sur les espaces de travail multi-racines et l’API basée sur des fichiers.

Avant de générer le cache CMake, vos outils personnalisés ou préférés peuvent avoir besoin de créer un fichier de requête nommé .cmake/api/v1/query/client-MicrosoftVS/query.json dans votre dossier de sortie de build (le dossier qui contient CMakeCache.txt). Le fichier de requête doit contenir ce contenu :

{"requests":[{"kind":"cache","version":2},{"kind":"cmakeFiles","version":1},{"kind":"codemodel","version":2}]}

Lorsque vos outils personnalisés ou préférés génèrent votre cache, CMake place les fichiers sous .cmake/api/v1/response utilisant Visual Studio pour remplir l’éditeur avec des informations spécifiques à la structure de votre projet.

Modification de CMakeLists.txt fichiers

Pour modifier un CMakeLists.txt fichier, cliquez avec le bouton droit sur le fichier dans Explorateur de solutions et choisissez Ouvrir. Si vous apportez des modifications au fichier, une barre de status jaune s’affiche et vous informe qu’IntelliSense sera mis à jour. Cela vous donne la possibilité d’annuler l’opération de mise à jour. Pour plus d’informations sur CMakeLists.txt, consultez la documentation CMake.

Dès que vous enregistrez le fichier, l’étape de configuration s’exécute à nouveau automatiquement et affiche les informations dans la fenêtre Sortie. Les erreurs et les avertissements sont affichés dans la Liste des erreurs ou la fenêtre Sortie. Double-cliquez sur une erreur dans la liste d’erreurs pour accéder à la ligne incriminée dans CMakeLists.txt.

Services linguistiques pour CMake

Les services linguistiques pour CMake sont disponibles dans Visual Studio 2019 version 16.5 ou ultérieure. Il prend en charge les fonctionnalités de navigation du code telles que Accéder à la définition, Rechercher la définition et Rechercher toutes les références pour les variables, fonctions et cibles CMake dans les fichiers de script CMake. Pour plus d’informations, consultez Navigation dans le code pour les scripts CMake.

Manipulation de projet CMake

La manipulation de projet CMake est disponible dans Visual Studio 2019 version 16.5 ou ultérieure. La manipulation de projet vous permet d’ajouter, de supprimer et de renommer des fichiers sources et des cibles dans votre projet CMake sans modifier manuellement vos scripts CMake. Lorsque vous ajoutez ou supprimez des fichiers du Explorateur de solutions, Visual Studio modifie automatiquement votre projet CMake. Il peut y avoir plusieurs endroits où il est judicieux d’ajouter ou de supprimer une référence à un script CMake. Si c’est le cas, Visual Studio vous demande où vous souhaitez apporter la modification et affiche un aperçu des modifications proposées. Pour obtenir des instructions pas à pas, consultez Ajouter, supprimer et renommer des fichiers et des cibles dans des projets CMake.

Projets IntelliSense pour CMake

Par défaut, Visual Studio utilise le mode IntelliSense qui correspond au compilateur et à l’architecture cible spécifiés par la configuration CMake active.

Si CMakePresets.json est votre fichier de configuration CMake actif, vous pouvez spécifier les options IntelliSense à l’aide intelliSenseMode de et intelliSenseOptions dans la carte du fournisseur des paramètres Visual Studio. Pour plus d’informations, consultez les informations de référence sur la carte des paramètres Visual Studio.

Si CMakeSettings.json est votre fichier de configuration CMake actif, vous pouvez spécifier les options IntelliSense à l’aide de intelliSenseMode dans CMakeSettings.json. Pour plus d’informations, consultez la référence CMakeSettings.json.

Configurer IntelliSense avec des fichiers de chaîne d’outils CMake

Dans Visual Studio 2019 version 16.9 et ultérieure, Visual Studio configure automatiquement IntelliSense dans les projets CMake en fonction des variables CMake lorsque vous utilisez un fichier de chaîne d’outils CMake. Pour plus d’informations, consultez Configurer IntelliSense avec les fichiers de chaîne d’outils CMake.

Intégration de Vcpkg

Les projets CMake ouverts dans Visual Studio s’intègrent à vcpkg, un gestionnaire de dépendances C/C++ multiplateforme. Avant d’utiliser vcpkg avec Visual Studio, vous devez exécuter vcpkg integrate install. Pour obtenir des instructions et plus d’informations sur vcpkg, consultez la documentation vcpkg.

Si CMakeSettings.json est votre fichier de configuration actif, Visual Studio transmet automatiquement le fichier de chaîne d’outils vcpkg (vcpkg.cmake) à CMake. Ce comportement est automatiquement désactivé lorsque vous spécifiez toute autre chaîne d’outils dans votre configuration des paramètres CMake.

Si CMakePresets.json est votre fichier de configuration actif, vous devez définir le chemin d’accès sur vcpkg.cmake dans CMakePresets.json. Nous vous recommandons d’utiliser la VCPKG_ROOT variable d’environnement au lieu d’un chemin absolu pour que le fichier reste partageable. Pour plus d’informations, consultez Activer l’intégration de vcpkg avec les présélections CMake. CMakePresets.json est disponible dans Visual Studio 2019 version 16.10 ou ultérieure et est le fichier de configuration CMake recommandé.

Exécuter CMake à partir de la ligne de commande

Si CMakePresets.json est votre fichier de configuration CMake actif, vous pouvez facilement reproduire vos builds locales en dehors de Visual Studio. Pour plus d’informations, consultez Exécuter CMake à partir de la ligne de commande ou d’un pipeline CI. CMakePresets.json est pris en charge dans Visual Studio 2019 version 16.10 ou ultérieure et est le fichier de configuration CMake recommandé.

Si CMakeSettings.json est votre fichier de configuration CMake actif, vous devez passer manuellement les arguments encodés dans votre CMakeSettings.json fichier à CMake. Si vous avez installé CMake à partir de Visual Studio Installer, vous pouvez l’exécuter à partir de la ligne de commande en suivant les étapes suivantes :

1. Exécutez le fichier approprié vsdevcmd.bat (x86/x64). Pour plus d’informations, consultez Génération sur la ligne de commande .

2. Revenez à votre dossier de sortie.

3. Exécutez CMake pour générer ou configurer votre application.

Voir aussi

Tutoriel : Créer des projets multiplateformes C++ dans Visual Studio
Configurer un projet CMake Linux
Se connecter à un ordinateur Linux distant
Personnaliser des paramètres de génération CMake
CMakeSettings.json Référence de schéma
Configurer des sessions de débogage CMake
Déployer, exécuter et déboguer un projet Linux
Informations de référence sur la configuration prédéfinie de CMake