Projets CMake dans Visual Studio

CMake est un outil open source multiplateforme utilisé pour définir des processus de génération qui s’exécutent sur plusieurs plateformes. Cet article part du principe que vous connaissez déjà CMake. Pour plus d’informations sur CMake, consultez la documentation de CMake. Le didacticiel CMake est un bon point de départ pour en savoir plus.

Remarque

Au cours des dernières versions, CMake est devenu de plus en plus intégré à Visual Studio. Pour consulter la documentation sur votre version préférée de Visual Studio, utilisez le contrôle de sélection de 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, générer et déboguer des projets CMake sur Windows, le Sous-système Windows pour Linux (WSL) et les systèmes distants à partir de la même 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 Visual Studio pour la configuration et la génération CMake.

Installation

Outils C++ CMake pour Windows est installé dans le cadre du développement Desktop avec C++ et du développement Linux avec des charges de travail C++. Les outils CMake C++ pour Windows et Développement Linux avec C++ sont nécessaires pour le développement CMake multiplateforme.

Dans le programme d’installation, le développement Desktop avec la liste déroulante C++ est sélectionné et les outils C++ et C Make pour Windows sont sélectionnés.

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 fichier CMakeLists.txt, les choses suivantes se produisent.

La boîte de dialogue propose ces options : cloner un référentiel, ouvrir un projet ou une solution, ouvrir un dossier local ou créer un projet. Ouvrir un dossier local est appelé dans la capture d’écran.

• Visual Studio ajoute des éléments CMake au menu de Projet, avec des commandes pour voir et modifier les scripts CMake.

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

• Visual Studio exécute CMake et génère le fichier cache CMake (CMakeCache.txt) pour la configuration par défaut. La ligne de commande CMake s’affiche dans la Fenêtre Sortie, ainsi que l’autre sortie 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.

Remarque

À compter de Visual Studio 2022 version 17.1 Preview 2, si votre CMakeLists.txt de niveau 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 de CMake.

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

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

Utilisez le fichier CMakeLists.txt dans chaque dossier de projet comme vous le feriez dans n’importe quel projet CMake. Vous pouvez spécifier des fichiers sources, rechercher des bibliothèques, définir des options du compilateur et de l’éditeur de liens, puis 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 entraîner la génération et la création du cache CMake. Pour plus d’informations, consultez Configuration des projets CMake et Génération 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 du 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 d’Incredibuild pour les projets CMake
• Prise en charge d’AddressSanitizer pour les projets CMake
• Prise en charge de Clang/LLVM

Remarque

Pour d’autres types de projets Dossier ouvert, un fichier JSON supplémentaires CppProperties.json 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. Cette option correspond à invoquer 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 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. CMakeSettings.json est disponible pour les clients utilisant une version antérieure de Visual Studio. Pour plus d’informations sur CMakeSettings.json, consultez Personnaliser les paramètres de génération CMake.

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

Les paramètres de configuration CMake sont appelés. Afficher les notification de cache C Make est sélectionné. Sous « Lorsque le cache est obsolète : », l’option « Ne jamais exécuter l’étape de configuration automatiquement » est sélectionnée.

Si l’étape de configuration se termine sans erreur, les informations qui sont disponibles sont les lecteurs C++ IntelliSense et les services de langage. Elles sont également utilisées 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 s’il y a une erreur. Pour afficher tous les messages, sélectionnez Outils>Options>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 de cache CMake.

Résolution des erreurs de cache CMake

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

• Afficher CMakeCache.txt ouvre le fichier CMakeCache.txt à partir du répertoire de build dans l’éditeur. Toutes les modifications que vous apportez ici à CMakeCache.txt sont effacées si vous nettoyez le cache. Pour apporter des modifications qui persistent après avoir nettoyé le cache, consultez Personnaliser les paramètres CMake ou Configurer et générer avec les 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’exécution de l’étape de génération même si Visual Studio considère l’environnement comme étant à 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. Cette option correspond à invoquer cmake --build à partir de la ligne de commande. Pour plus d’informations sur l’étape de génération de 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, puis 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 Vue CMake Targets active dans l’Explorateur de solutions, puis sélectionnez Générer dans le menu contextuel.

3. Dans le menu principal, sélectionnez Générer> Générer tout. Vérifiez qu’une cible CMake est déjà sélectionnée dans la liste déroulante Élément de démarrage dans 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.

Les avertissements de génération CMake concernant les conversions qui peuvent entraîner une perte de données, comme la conversion d’un flottant en entier, sont visibles. :::image-end:::

Modifier les paramètres de génération

Visual Studio utilise un fichier de configuration CMake pour entraîner la génération 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 les présélections CMake. Si CMakeSettings.json est votre fichier de configuration actif, consultez Personnaliser les paramètres de génération CMake. CMakePresets.json est disponible dans Visual Studio 2019 version 16.10 ou ultérieure et il s’agit du fichier de configuration CMake recommandé.

Débogage de projets CMake

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

La liste déroulante comporte ces options : Afficher / Masquer les cibles de débogage, document actif, échantillons (mis en surbrillance), box2d_tests et samples-noGUI.

Les commandes Déboguer ou F5 génèrent d’abord le projet si des modifications ont été apportées depuis la dernière génération. Les modifications apportées au fichier de configuration CMake (CMakePresets.json ou CMakeSettings.json) ou à un CMakeLists.txt entraînent 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 d’une cible spécifique, sélectionnez la cible dans la liste déroulante Élément de démarrage, puis appuyez sur Débogage > Paramètres de débogage et de lancement pour <cible active>. Pour plus d’informations sur les sessions de débogage CMake, consultez Configurer les sessions de débogage CMake.

Uniquement 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 Uniquement mon code. Pour modifier le paramètre Uniquement mon code, accédez à Outils>Options>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 Modifier et Continuer. Ajoutez le code suivant à votre fichier CMakeLists.txt pour activer Modifier et Continuer.

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

Attacher à un projet CMake s’exécutant 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 de 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 le Gestionnaire de connexions

Les options suivantes sont disponibles dans la boîte de dialogue : Type de connexion (défini sur SSH), la cible de connexion (définie sur demo@ 172. 20. 60. 6), ainsi qu’une liste de processus disponibles auquel il est possible d’attacher. »

Activation partielle de CMake

Dans Visual Studio 2022 version 17.1 et ultérieure, la fonctionnalité CMake n’est pas activée automatiquement si votre dossier racine ne contient pas de fichier CMakeLists.txt. Au lieu de cela, une boîte de dialogue vous invite à savoir 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 de CMakePresets.json) n’apparaissent pas dans la liste déroulante de configuration. Si vous acceptez, vous êtes dirigé vers un fichier de configuration au niveau de l’espace de travail, CMakeWorkspaceSettings.json (stocké dans le répertoire .vs), pour spécifier les dossiers que vous souhaitez activer pour 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 répertoire 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 sont ignorés.

Vous pouvez accéder à CMakeWorkspaceSettings.json via la commande de menu Project>Paramètres de l’espace de travail 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 contrôlent complètement 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.

Remarque

L’expérience de cache existante par défaut s’appuie sur cmake-server, qui a été supprimée 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 inférieure. Ensuite, définissez la propriété cmakeExecutable dans votre configuration de cache existante pour utiliser cette version de CMake.
• Dans votre configuration de cache existante, définissez la propriété cacheGenerationCommand pour permettre à Visual Studio de demander les fichiers API 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 les fichiers 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 avancée des problèmes du cache CMake.

Résolution avancée des problèmes de cache CMake

Visual Studio utilise l’API CMake basée sur des fichiers (dans les versions 3.14 et ultérieures) pour remplir l’éditeur avec des informations spécifiques à votre structure de projet. Pour plus d’informations, consultez le billet de blog de l’équipe C++ sur Espaces de travail multi-racines et 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 que Visual Studio utilise pour remplir l’éditeur avec des informations spécifiques à votre structure de projet.

Modification des fichiers CMakeLists.txt

Pour modifier un fichier CMakeLists.txt , cliquez avec le bouton droit sur le fichier dans l’Explorateur de solutions et choisissez Ouvrir. Si vous modifiez le fichier, une barre d’état jaune s’affiche pour vous informer qu’IntelliSense va effectuer la mise à 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.

Il contient le projet de lignes (hello-cmake), add_subdirectory (tests), add_executable (hello hello.cpp) et l’installation (TARGETS hello DESTINATION hello/bin). Un message en haut de la fenêtre indique que les informations IntelliSense C++ s’actualisent une fois que C Make termine la génération du cache.

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 des erreurs pour accéder à la ligne concernée dans CMakeLists.txt.

Un message d’erreur A C Make à la ligne 3 de CMakeLists.txt est mis en surbrillance. Les détails sont que C Make n’a pas trouvé de fichier de configuration de package fourni par sqlite3. C Make l’a cherché dans CMAKE_MODULE_PATH, mais n’a pas pu le trouver. La suggestion consiste à ajouter le préfixe d’installation « sqlite3 » à CMAKE_PREFIX_PATH ou à définir sqlite3_DIR à un répertoire contenant sqlite3Config.cmake et/ou sqlitet3-config.cmake.

Services de langage pour CMake

Les services de langage pour CMake sont disponibles dans Visual Studio 2019 version 16.5 ou ultérieure. Il prend en charge les fonctionnalités de navigation de code telles que Atteindre la définition, Faire un Peek de la Définition et Trouver toutes les références pour les variables, fonctions et cibles CMake dans les fichiers de script CMake. Pour plus d’informations, consultez Navigation de code pour les scripts CMake.

Les résultats de l’emplacement où SUPERTUX_SOURCES_CXX sont trouvés sont affichés. Par exemple, dans liste(SORT SSUPERTUX_SOURCES_CXX), fichier(GLOB SUPERTUX_SOURCES_CXX), etc.

Manipulation du 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. Quand vous ajoutez ou supprimez des fichiers de l’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 les projets CMake.

Une arborescence affiche CMakeLists.txt, sous laquelle il y a deux éléments : add_executable et défini. L’option Définie est cochée. La fenêtre d’aperçu indique où les modifications seront faites. L’ensemble de lignes (PROJECT_SRC « CmakeProject4.cpp » « CMakeProject4.h » affiche « Demo.cpp » mis en surbrillance avant la parenthèse fermante. Le bouton Appliquer accepte la modification, ou vous pouvez appuyer sur Annuler.

IntelliSense pour les projets CMake

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

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

Si CMakeSettings.json est votre fichier de configuration CMake actif, vous pouvez spécifier des 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 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 :

• Installer et utiliser des packages avec CMake dans Visual Studio
• vcpkg dans les projets CMake

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 désactivé automatiquement lorsque vous spécifiez une 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 à vcpkg.cmake dans CMakePresets.json. Nous vous recommandons d’utiliser la variable d’environnement VCPKG_ROOT au lieu d’un chemin absolu pour conserver le fichier partageable. Pour plus d’informations, consultez Activer l’intégration de vcpkg à CMake Presets. CMakePresets.json est disponible dans Visual Studio 2019 version 16.10 ou ultérieure et il s’agit du 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 générations 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 il s’agit du 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 fichier CMakeSettings.json à 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 vsdevcmd.bat approprié (x86/x64). Pour plus d’informations, consultez Génération à partir de 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 les paramètres de génération CMake
CMakeSettings.json Informations de référence sur le 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
vcpkg dans les projets CMake
Installer et utiliser des packages avec CMake dans Visual Studio