Anpassen von CMake-Buildeinstellungen

Visual Studio verwendet eine CMake-Konfigurationsdatei, um CMake-Generierung und -Build zu steuern. CMakePresets.json wird von Visual Studio 2019, Version 16.10 oder höher unterstützt und ist die empfohlene CMake-Konfigurationsdatei. CMakePresets.json wird direkt von CMake unterstützt und kann dazu verwendet werden, CMake-Generierung und -Build aus Visual Studio, aus VS Code, in einer Continuous Integration-Pipeline und von der Befehlszeile unter Windows, Linux und Mac zu steuern. Weitere Informationen zu CMakePresets.json finden Sie unter Konfigurieren und Kompilieren mit CMake-Voreinstellungen.

Wenn Sie Projekte verwalten, die eine CMakeSettings.json Datei für die CMake-Buildkonfiguration verwenden, stellen Visual Studio 2019 und höhere Versionen einen CMake-Einstellungs-Editor bereit. Mit dem Editor können Sie CMake-Konfigurationen hinzufügen und ihre Einstellungen ganz einfach anpassen. Es soll eine einfachere Alternative zum manuellen Bearbeiten der CMakeSettings.json Datei sein. Wenn Sie die Datei jedoch lieber direkt bearbeiten möchten, können Sie den JSON-Link in der oberen rechten Ecke des Editors auswählen.

Um den CMake Einstellungs-Editor zu öffnen, wählen Sie die Dropdownliste Konfiguration in der Hauptsymbolleiste, und wählen Sie Konfigurationen verwalten aus.

Jetzt wird der Einstellungs-Editor mit den installierten Konfigurationen auf der linken Seite angezeigt.

Visual Studio stellt standardmäßig eine x64-Debug-Konfiguration bereit. Sie können weitere Konfigurationen hinzufügen, indem Sie das grüne Pluszeichen auswählen. Die im Editor angezeigten Einstellungen unterscheiden sich möglicherweise abhängig von der ausgewählten Konfiguration.

Die Optionen, die Sie im Editor auswählen, werden in eine Datei mit dem Namen CMakeSettings.json geschrieben. Diese Datei stellt Befehlszeilenargumente und Umgebungsvariablen zur Verfügung, die beim Erstellen der Projekte an CMake übergeben werden. Visual Studio ändert CMakeLists.txt nie automatisch; mithilfe von CMakeSettings.json können Sie den Build über Visual Studio anpassen, ohne die CMake-Projektdateien zu bearbeiten, sodass andere in Ihrem Team sie mit Tools ihrer Wahl nutzen können.

CMake – allgemeine Einstellungen

Die folgenden Einstellungen sind unter der Überschrift Allgemein verfügbar:

Konfigurationsname

Entspricht der Einstellung name. Dieser Name wird in der Dropdownliste für die C++-Konfiguration angezeigt. Sie können das ${name}-Makro verwenden, um weitere Eigenschaftswerte wie etwa Pfade zu verfassen.

Konfigurationstyp

Entspricht der Einstellung configurationType. Definiert den Typ der Buildkonfiguration für den ausgewählten Generator. Derzeit werden die Werte "Debug", "MinSizeRel", "Release" und "RelWithDebInfo" unterstützt. Es ist zugeordnet zu CMAKE_BUILD_TYPE.

Toolset

Entspricht der Einstellung inheritedEnvironments. Mit dieser Einstellung wird die Compilerumgebung definiert, die zum Erstellen der ausgewählten Konfiguration verwendet wird. Die unterstützten Werte hängen von der Art der Konfiguration ab. Klicken Sie auf den Link JSON bearbeiten in der rechten oberen Ecke des Einstellungs-Editors, und bearbeiten Sie die Datei CMakeSettings.json direkt, um eine benutzerdefinierte Umgebung zu erstellen.

CMake-Toolkettendatei

Hierbei handelt es sich um den Pfad zur CMake-Toolkettendatei. Dieser Pfad wird an CMake als "-DCMAKE_TOOLCHAIN_FILE = <filepath> weitergegeben. In Toolkettendateien werden die Speicherorte von Compilern und Toolketten-Hilfsprogrammen sowie andere Informationen in Bezug auf die Zielplattform und Compiler angegeben. Wenn für diese Einstellung nichts angegeben ist, verwendet Visual Studio standardmäßig die VCPKG-Toolkettendatei.

Buildstamm

Entspricht buildRoot. Ordnet nach CMAKE_BINARY_DIR zu, und gibt an, wo der CMake-Cache erstellt werden soll. Wenn der angegebene Ordner nicht vorhanden ist, wird er erstellt.

Befehlsargumente

Die folgenden Einstellungen sind unter der Überschrift Befehlsargumente verfügbar:

CMake-Befehlsargumente

Entspricht cmakeCommandArgs. Gibt weitere Befehlszeilenoptionen an, die an CMake übergeben werden.

Build-Befehlsargumente

Diese Einstellung entspricht buildCommandArgs. Sie gibt weitere Parameter an, die an das zugrunde liegende Buildsystem übergeben werden sollen. Beispielsweise wird beim Übergeben von -v bei Verwendung des Ninja-Generators erzwungen, dass Ninja Befehlszeilen ausgibt.

CTest-Befehlsargumente

Diese Einstellung entspricht ctestCommandArgs. Sie gibt weitere Befehlszeilenoptionen an, die beim Ausführen von Tests an CTest übergeben werden sollen.

Allgemeine Einstellungen für Remotebuilds

Für Konfigurationen wie Linux, die Remotebuilds verwenden, sind ferner die folgenden Einstellungen verfügbar:

Argumente des rsync-Befehls

Zusätzliche Befehlszeilenoptionen, die an rsync weitergegeben werden, ein schnelles, vielseitiges Tool zum Kopieren von Dateien.

CMake-Variablen und -Cache

Mithilfe dieser Einstellungen können Sie CMake-Variablen festlegen und in CMakeSettings.json speichern. Sie werden zur Erstellungszeit an CMake übergeben und setzen die in der Datei CMakeLists.txt vorhandenen Werte außer Kraft. Sie können diesen Abschnitt in der gleichen Weise verwenden, in der Sie das CMakeGUI verwenden, um eine Liste aller für die Bearbeitung verfügbaren CMake-Variablen anzuzeigen. Wählen Sie die Schaltfläche Speichern und Cache generieren, um eine Liste aller für die Bearbeitung verfügbaren CMake-Variablen anzuzeigen, einschließlich erweiterter Variablen (mithilfe des CMakeGUI). Sie können die Liste nach dem Variablennamen filtern.

Diese Einstellung entspricht variables. Enthält ein Name-Wert-Paar von CMake-Variablen, die als -D name=value an CMake übergeben werden. Wenn die Buildanweisungen Ihres CMake-Projekts das direkte Hinzufügen aller Variablen zur CMake-Cachedatei festlegen, wird empfohlen, diese stattdessen hier hinzuzufügen.

Erweiterte Einstellungen

CMake-Generator

Diese Einstellung entspricht generator. Sie ist der CMake-Option -G zugeordnet und gibt den CMake-Generator an, der verwendet werden soll. Diese Eigenschaft kann ebenfalls als Makro (${generator}) beim Erstellen anderer Eigenschaftswerte verwendet werden. Visual Studio unterstützt derzeit folgende CMake-Generatoren:

• "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"

Da Ninja für schnelle Buildgeschwindigkeiten statt für Flexibilität und Funktionalität entwickelt wurde, ist dieser Generator als Standardwert festgelegt. Einige CMake-Projekte können jedoch mit Ninja keinen ordnungsgemäßen Build durchführen. In diesem Fall können Sie CMake anweisen, stattdessen ein Visual Studio-Projekt zu erstellen.

IntelliSense-Modus

Hierbei handelt es sich um den IntelliSense-Modus, der von der IntelliSense-Engine verwendet wird. Wenn kein Modus ausgewählt ist, erbt Visual Studio den Modus vom angegebenen Toolset.

Installationsverzeichnis

Hierbei handelt es sich um das Verzeichnis, in dem CMake Ziele installiert. Wird CMAKE_INSTALL_PREFIX zugeordnet.

Ausführbare CMake-Datei

Hier wird der vollständige Pfad zur ausführbaren CMake-Programmdatei angegeben, einschließlich des Dateinamens und der Erweiterung. Die Verwendung einer benutzerdefinierten Version von CMake mit Visual Studio ist möglich. Geben Sie für Remotebuilds den CMake-Speicherort auf dem Remotecomputer an.

Für Konfigurationen wie Linux, die Remotebuilds verwenden, sind ferner die folgenden Einstellungen verfügbar:

Remoteverzeichnis der Stammdatei „CMakeLists.txt“

Hierbei handelt es sich um das Verzeichnis auf dem Remotecomputer, das die Stammdatei CMakeLists.txt enthält.

Installationsstammverzeichnis auf dem Remotesystem

Das Verzeichnis auf dem Remotecomputer, in dem CMake Zieldateien installiert. Wird CMAKE_INSTALL_PREFIX zugeordnet.

Quellen auf Remotesystem kopieren

Diese Einstellung gibt an, ob Quelldateien auf den Remotecomputer kopiert werden sollen, und ermöglicht Ihnen, anzugeben, ob rsync oder sftp verwendet werden soll.

„CMakeSettings.json“ direkt bearbeiten

Sie können CMakeSettings.json auch direkt bearbeiten, um benutzerdefinierte Konfigurationen zu erstellen. Der Einstellungs-Editor weist eine Schaltfläche JSON bearbeiten oben rechts auf, mit der die Datei zur Bearbeitung geöffnet wird.

Das folgende Beispiel zeigt eine Beispielkonfiguration, die Sie als Ausgangspunkt verwenden können:

    {
      "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 unterstützt Sie beim Bearbeiten der Datei CMakeSettings.json:

Der JSON-Editor informiert Sie auch, wenn Sie inkompatible Einstellungen auswählen.

Weitere Informationen zu den einzelnen Eigenschaften in der Datei finden Sie in der CMakeSettings.json-Schemareferenz.

Visual Studio 2017 bietet verschiedene CMake-Konfigurationen, die definieren, wie CMake aufgerufen wird, um den CMake-Cache für ein bestimmtes Projekt zu erstellen. Klicken Sie zum Hinzufügen einer neuen Konfiguration in der Symbolleiste auf die Konfigurations-Dropdownliste, und wählen Sie Konfigurationen verwalten... aus:

Sie können aus der Liste vordefinierter Konfigurationen wählen:

Wenn Sie zum ersten Mal eine Konfiguration auswählen, erstellt Visual Studio im Stammordner des Projekts eine CMakeSettings.json-Datei. Diese Datei wird verwendet, um die CMake-Cachedatei erneut zu erstellen, z.B. nach einem Bereinigungsvorgang.

Klicken Sie zum Hinzufügen einer weiteren Konfiguration mit der rechten Maustaste auf CMakeSettings.json, und wählen Sie Konfiguration hinzufügen aus.

Sie können die Datei auch mithilfe des Editors für CMake-Einstellungen bearbeiten. Klicken Sie mit der rechten Maustaste im Projektmappen-Explorer auf CMakeSettings.json, und wählen Sie CMake-Einstellungen bearbeiten aus. Alternativ können Sie oben im Editor-Fenster aus der Konfigurations-Dropdownliste Konfigurationen verwalten... auswählen.

Sie können CMakeSettings.json auch direkt bearbeiten, um benutzerdefinierte Konfigurationen zu erstellen. Das folgende Beispiel zeigt eine Beispielkonfiguration, die Sie als Ausgangspunkt verwenden können:

    {
      "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 unterstützt Sie beim Bearbeiten der Datei CMakeSettings.json:

Weitere Informationen zu den einzelnen Eigenschaften in der Datei finden Sie in der CMakeSettings.json Schemareferenz.