Konfigurieren und Erstellen mit CMake-Voreinstellungen in Visual Studio

CMake unterstützt zwei Dateien, die es Benutzern ermöglichen, gemeinsame Konfigurations-, Build- und Testoptionen anzugeben und mit anderen zu teilen: CMakePresets.json und CMakeUserPresets.json. Verwenden Sie diese Dateien zum Steuern von CMake in Visual Studio und Visual Studio Code, einer CI-Pipeline (Continuous Integration) oder über die Befehlszeile.

CMakePresets.json dient dem Speichern projektweiter Builds. CMakeUserPresets.json dient Entwicklern zum Speichern ihrer eigenen lokalen Builds. Beide Dateien werden in Visual Studio 2019, Version 16.10 oder höher, unterstützt.

Dieser Artikel enthält Informationen zur Integration von CMakePresets.json in Visual Studio. Hilfreiche Links:

• Weitere Informationen zum Format von CMakePresets.json finden Sie in der offiziellen CMake-Dokumentation.
• Weitere Informationen zu den Anbieterzuordnungen und der Makroerweiterung von Microsoft finden Sie unter Microsoft-Anbieterzuordnungen CMakePresets.json und CMakeUserPresets.json.
• Weitere Informationen zur Verwendung von CMakePresets.json in Visual Studio Code finden Sie unter Configure and build with CMake Presets in VS Code (Konfigurieren und Erstellen mit CMake-Voreinstellungen in VS Code).

Wir empfehlen CMakePresets.json als Alternative zu CMakeSettings.json. Visual Studio liest nie aus beiden CMakePresets.json und CMakeSettings.json gleichzeitigen Lesevorgängen. Informationen, wie Sie die Integration von CMakePresets.json in Visual Studio aktivieren oder deaktivieren, finden Sie unter Aktivieren von CMakePresets.json in Visual Studio 2019.

Unterstützte Versionen von CMake und CMakePresets.json

Die unterstützten CMakePresets.json und CMakeUserPresets.json Schemaversionen hängen von Ihrer Version von Visual Studio ab:

• Visual Studio 2019, Version 16.10 und höher, unterstützen Schemaversionen 2 und 3.
• Visual Studio 2022, Version 17.4 Preview 1, bietet Unterstützung für Schemaversion 4.
• Visual Studio 2022, Version 17.5 Preview 1, bietet Unterstützung für Schemaversion 5.

Sie können die Version aktualisieren, indem Sie das "version" Feld im Stammobjekt ändern. Ein Beispiel sowie weitere Informationen finden Sie im Abschnitt der CMake-Dokumentation zum Format von CMakePresets.json.

CMake Version 3.20 oder höher ist erforderlich, wenn Sie CMake über CMakePresets.json die Befehlszeile aufrufen. Visual Studio ruft CMake jedoch nicht direkt über die Option --preset auf, sondern liest die Dateien CMakePresets.json und CMakeUserPresets.json selbst und wertet sie auch selbst aus. Somit ist beim Erstellen in Visual Studio mit CMakePresets.json Version 3.20 oder höher von CMake nicht zwingend erforderlich.

Es wird empfohlen, mindestens CMake Version 3.14 oder höher zu verwenden.

Aktivieren der CMakePresets.json Integration in Visual Studio

CMakePresets.json Die Integration ist in Visual Studio nicht standardmäßig aktiviert. Sie können es in den Tools-Optionen>>"CMake>Allgemein" aktivieren:

Dieser Bildschirm wird über das Visual Studio 2022-Menü erreicht: Extras > Optionen > CMake > Allgemein. Die Option befindet sich im Abschnitt "Datei konfigurieren" von CMake.

Wichtig

Schließen Sie den Ordner in Visual Studio, und öffnen Sie ihn erneut, um die Integration zu aktivieren.

In einigen älteren Versionen von Visual Studio verfügt "Tools>Options>CMake>General" nur über eine einzige Option zum Aktivieren CMakePresets.json der Integration:

In der folgenden Tabelle wird angegeben, wann CMakePresets.json anstelle der CMakeSettings.json CMake-Konfiguration und des Builds in Visual Studio 2022 und Visual Studio 2019, Version 16.10 und höher, verwendet wird. Wenn keine Konfigurationsdatei vorhanden ist, werden die Standardkonfigurationsvoreinstellungen verwendet.

In der Tabelle bedeutet „Extras>Optionen aktiviert“, dass unter Extras>Optionen>CMake>Allgemein die Option Use CMakePresets.json to drive CMake configure, build, and test (CMakePresets.json zum Steuern von Konfiguration, Erstellung und Tests mit CMake verwenden) aktiviert ist.

Konfigurationsdateien	Extras > Optionen deaktiviert	Optionen für Extras > aktiviert
Es ist keine Konfigurationsdatei vorhanden.	CMakeSettings.json	CMakePresets.json
CMakeSettings.json ist vorhanden.	CMakeSettings.json	CMakePresets.json
CMakePresets.json ist vorhanden.	CMakePresets.json	CMakePresets.json
Beide Konfigurationsdateien sind vorhanden.	CMakePresets.json	CMakePresets.json

Ändern der automatischen Konfiguration und von Cachebenachrichtigungen

Standardmäßig ruft Visual Studio configure immer dann automatisch auf, wenn sich das aktive Zielsystem oder die Konfigurationsvoreinstellung ändert. Sie können dieses Verhalten ändern, indem Sie unter Extras>Optionen>CMake>Allgemein die Option Konfigurationsschritt nie automatisch ausführen auswählen. Sie können auch alle CMake-Cachebenachrichtigungen (gelbe Leiste) deaktivieren, indem Sie CMake-Cachebenachrichtigungen anzeigen deaktivieren.

Standardkonfigurationsvoreinstellungen

Wenn keine CMakePresets.json Datei vorhanden ist oder CMakeUserPresets.json CMakePresets.json CMakeUserPresets.json ungültig ist, greift Visual Studio auf die folgenden Standardeinstellungen "Voreinstellungen konfigurieren" zurück:

Windows-Beispiel

{
  "name": "windows-default",
  "displayName": "Windows x64 Debug",
  "description": "Sets Ninja generator, compilers, x64 architecture, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "architecture": {
    "value": "x64",
    "strategy": "external"
  },
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Windows" ]
    }
  }
},

Linux-Beispiel

{
  "name": "linux-default",
  "displayName": "Linux Debug",
  "description": "Sets Ninja generator, compilers, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Linux" ]
    },
    "microsoft.com/VisualStudioRemoteSettings/CMake/1.0": {
      "sourceDir": "$env{HOME}/.vs/$ms{projectDirName}"
   }
  }
}

Wenn Sie versuchen, eine Datei CMakePresets.json zu öffnen oder zu bearbeiten, die nicht vorhanden ist, erstellt Visual Studio automatisch die Datei CMakePresets.json mit den Standardkonfigurationsvoreinstellungen im Stamm Ihres Projekts.

Konfigurieren und Erstellen

Auf der Visual Studio-Symbolleiste gibt es Dropdowns für die Zielsysteme, "Voreinstellungen konfigurieren" und "Voreinstellungen erstellen", wenn CMakePresets.json die Integration aktiviert ist:

Auswählen eines Zielsystems

Die Dropdownliste auf der linken Seite zeigt das aktive Zielsystem an. Dies ist das System, auf dem CMake zum Konfigurieren und Erstellen des Projekts aufgerufen wird. Diese Dropdownliste umfasst Ihren lokalen Computer, alle SSH-Verbindungen im Verbindungs-Manager nach Hostname sowie alle WSL-Installationen (Windows-Subsystem für Linux), die Visual Studio findet:

Die Dropdownliste enthält mehrere Einträge, darunter local Machine, eine IP-Adresse 192.168.0.5, WSL: ubuntu2004, WSL: debian und Manage Connections.

Im vorherigen Beispiel:

• 192.168.0.5 ist ein Linux-Remotesystem, das dem Verbindungs-Manager hinzugefügt wurde.
• ubuntu2004 und debian sind WSL-Installationen.

Wählen Sie Verbindungen verwalten aus, um den Verbindungs-Manager zu öffnen.

Auswählen einer Konfigurationsvoreinstellung

Die Dropdownliste in der Mitte gibt die aktive Konfigurationsvoreinstellung an. Dies ist der configurePreset-Wert, mit dem beim Aufrufen von CMake das Projekterstellungssystem generiert wird. Diese Dropdownliste umfasst alle nicht ausgeblendeten Konfigurationsvoreinstellungen, die in CMakePresets.json und CMakeUserPresets.json definiert sind.

Visual Studio verwendet den Wert des hostOS Microsoft Visual Studio-Einstellungsanbieters, um Configure Presets auszublenden, die nicht für das aktive Zielsystem gelten. Weitere Informationen finden Sie im Eintrag zu hostOS in der Tabelle unter Anbieterzuordnung für Visual Studio-Einstellungen.

Wählen Sie Konfigurationen verwalten aus, um die Datei CMakePresets.json im Stammverzeichnis des Projekts zu öffnen. Wenn die Datei CMakePresets.json noch nicht vorhanden ist, wird sie erstellt.

Auswählen einer Buildvoreinstellung

Die Dropdownliste auf der rechten Seite gibt die aktive Buildvoreinstellung an. Dies ist der buildPreset-Wert, mit dem beim Aufrufen von CMake das Projekt erstellt wird. Diese Dropdownliste enthält alle nicht ausgeblendeten Buildvoreinstellungen, die in CMakePresets.json und CMakeUserPresets.json definiert sind.

Zum Angeben eines zugeordneten configurePreset-Werts sind alle Buildvoreinstellungen erforderlich. Visual Studio blendet Buildvoreinstellungen aus, die für die aktive Konfigurationsvoreinstellung nicht gelten. Weitere Informationen finden Sie in der Liste der Buildvoreinstellungen.

Wenn keine Buildvoreinstellungen mit der aktiven "Voreinstellung konfigurieren" verknüpft sind, listet Visual Studio die Standardmäßige Buildvoreinstellung auf. Die Standardbuildvoreinstellung entspricht dem Übergeben von cmake --build ohne weitere Argumente über die Befehlszeile.

Konfigurieren

Visual Studio versucht automatisch, das Projekt zu konfigurieren, wenn Visual Studio erkennt, dass der CMake-Cache veraltet ist. Um die Konfiguration manuell aufzurufen, wählen Sie "Projekt>konfigurieren>" <im Hauptmenü aus. Dies entspricht der Ausführung von cmake --preset <configurePreset> über die Befehlszeile, wobei <configurePreset> der Name der aktiven Konfigurationsvoreinstellung ist.

Informationen zum Deaktivieren der automatischen Cachegenerierung finden Sie unter Automatische Konfiguration und Cachebenachrichtigungen.

Erstellen

Klicken Sie im Hauptmenü auf Erstellen>Alles erstellen, um das gesamte Projekt zu erstellen. Dies entspricht der Ausführung von cmake --build --preset <buildPreset> über die Befehlszeile, wobei <buildPreset> der Name der aktiven Buildvoreinstellung ist.

Wechseln Sie im Projektmappen-Explorer zur CMake-Zielansicht, um ein einzelnes Ziel zu erstellen. Klicken Sie dann mit der rechten Maustaste auf ein beliebiges Ziel, und klicken Sie im Kontextmenü auf Erstellen.

Hinweis

Visual Studio 2019 unterstützt die Option buildPresets.targets zum Erstellen einer Teilmenge der in CMakePresets.json angegebenen Ziele nicht.

Ausführen von CTest

CMakePresets.json unterstützt zwei Menüoptionen in Visual Studio 2019:

• Test>Run CTests for <project-name> invokes CTest and run all tests associated with the active Configure Preset and Build Preset, with no other arguments passed to CTest.
• Test>run Test Preset for <configurePreset> expands to show all Test Presets associated with the active Configure Preset. Das Auswählen einer einzelnen Testvoreinstellung entspricht der Ausführung von ctest --preset <testPreset> über die Befehlszeile, wobei <testPreset> der Name der ausgewählten Testvoreinstellung ist. Wenn für die aktive Konfigurationsvoreinstellung keine Testvoreinstellungen definiert sind, ist diese Option nicht verfügbar.

In Visual Studio 2019 ist der Test-Explorer nicht in CMakePresets.json integriert.

Hinzufügen neuer Voreinstellungen

In Visual Studio 2019 ändern alle Befehle und Vorlagen für Voreinstellungen CMakePresets.json. Sie können neue Voreinstellungen auf Benutzerebene hinzufügen, indem Sie CMakeUserPresets.json direkt bearbeiten.

Verwenden Sie für Pfade in CMakePresets.json und CMakeUserPresets.json einen Schrägstrich (/).

Hinzufügen neuer Konfigurationsvoreinstellungen

Klicken Sie im Projektmappen-Explorer in der Ordneransicht mit der rechten Maustaste auf CMakePresets.json, und wählen Sie dann im Kontextmenü Konfiguration hinzufügen aus, um CMakePresets.json eine neue Konfigurationsvoreinstellung hinzuzufügen. Das Dialogfeld zum Auswählen einer Vorlage für Konfigurationsvoreinstellungen wird angezeigt:

Wählen Sie für Konfigurationen für Windows-Systeme die Vorlage Windows x64 Debug aus. Wählen Sie die Vorlage Linux Debug aus, um Konfigurationen für das WSL und Linux-Remotesysteme vorzunehmen. Weitere Informationen zum Bearbeiten von CMakePresets.json finden Sie unter Bearbeiten von Voreinstellungen.

Wenn CMakePresets.json vorhanden ist, wird der Datei die ausgewählte Vorlage hinzugefügt. Andernfalls wird die Vorlage in eine neue Datei mit dem Namen CMakePresets.json kopiert.

Hinzufügen neuer Build- und Testvoreinstellungen

Visual Studio 2019 bietet keine Vorlagen für neue Build- und Testvoreinstellungen. Build- und Testvoreinstellungen können durch direktes Bearbeiten von CMakePresets.json hinzugefügt werden. Weitere Informationen finden Sie in der Liste der Buildvoreinstellungen, der Liste der Testvoreinstellungen oder in einer CMakePresets.json-Beispieldatei.

Bearbeiten von Voreinstellungen

Die offizielle CMake-Dokumentation ist die beste Ressource für das Bearbeiten von Konfigurations-, Build- und Testvoreinstellungen. Die folgenden Informationen sind ein Teil der CMake-Dokumentation, der für Visual Studio-Entwickler besonders relevant ist.

Auswählen von Compilern

Sie können C- und C++-Compiler mithilfe von cacheVariables.CMAKE_C_COMPILER und cacheVariables.CMAKE_CXX_COMPILER in einer Konfigurationsvoreinstellung festlegen. Dies entspricht dem Übergeben von -D CMAKE_C_COMPILER=<value> und -D CMAKE_CXX_COMPILER=<value> an CMake über die Befehlszeile. Weitere Informationen finden Sie unter CMAKE_<LANG>_COMPILER.

Verwenden Sie die folgenden Beispiele, um mit cl.exe und clang-cl.exe Builds über Visual Studio zu erstellen. Die C++-Clang-Tools für die Windows-Komponente müssen für Sie installiert sein, um mit clang-cl Builds zu erstellen.

Erstellung mit cl.exe:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "cl",
  "CMAKE_CXX_COMPILER": "cl"
},

Erstellung mit clang:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "clang-cl",
  "CMAKE_CXX_COMPILER": "clang-cl"
},

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

Wenn Sie entweder Visual Studio 16 2019 oder Visual Studio 17 2022 als Generator verwenden, können Sie die toolset Voreinstellung konfigurieren verwenden, um das ClangCL Toolset anzugeben:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
},

"toolset": "ClangCL",

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

Weitere Informationen zu Generatoren, die die toolset Spezifikation unterstützen, finden Sie CMAKE_GENERATOR_TOOLSET in der CMake-Dokumentation.

Wichtig

In Visual Studio 2019 müssen Sie für die Builderstellung mit clang oder clang-cl explizit einen Clang-IntelliSense-Modus angeben.

Informationen, wie Sie diese Builds außerhalb von Visual Studio reproduzieren können, finden Sie unter Ausführen von CMake über die Befehlszeile oder eine CI-Pipeline.

Wenn Sie Builds unter Linux oder ohne das Visual C++-Toolset erstellen möchten, geben Sie den Namen eines Compilers in Ihrer PATH-Instanz oder eine Umgebungsvariable an, die den vollständigen Pfad eines Compilers angibt. Von vollständigen Pfaden wird abgeraten, damit die Datei weiterhin geteilt werden kann. Eine Voreinstellung, die Builds mit Version 8 der GCC erstellt, könnte wie folgt aussehen:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "gcc-8",
  "CMAKE_CXX_COMPILER": "g++-8"
},

Sie können Compiler auch mit einer CMake-Toolkettendatei festlegen. Toolkettendateien können mit cacheVariables.CMAKE_TOOLCHAIN_FILE festgelegt werden, was der Übergabe von -D CMAKE_TOOLCHAIN_FILE=<value> an CMake über die Befehlszeile entspricht. CMake-Toolkettendateien werden am häufigsten für Crosskompilierung verwendet. Weitere Informationen zum Erstellen von CMake-Toolkettendateien finden Sie unter cmake-toolchains.

Auswählen des Generators

Sowohl in den Vorlagen für Konfigurationsvoreinstellungen für Windows als auch in denen für Linux ist Ninja als Standard-Generator angegeben. Andere gängige Generatoren sind die Visual Studio-Generatoren unter Windows und Unix-Makefiles unter Linux und macOS. In einer Konfigurationsvoreinstellung können Sie einen neuen Generator mit der Option generator angeben. Dies entspricht der Übergabe von -G an CMake über die Befehlszeile.

Legen Sie bei der Erstellung mit einem Visual Studio-Generator architecture.strategy und toolset.strategy auf set fest. Weitere Informationen finden Sie unter cmake-generators.

Auswählen des Konfigurationstyps

Sie können den Konfigurationstyp (Debug oder Release) für einzelne Konfigurations-Generatoren mithilfe von cacheVariables.CMAKE_BUILD_TYPE festlegen. Dies entspricht der Übergabe von -D CMAKE_BUILD_TYPE=<value> an CMake über die Befehlszeile. Weitere Informationen finden Sie unter CMAKE_BUILD_TYPE.

Auswählen Ihrer Ziel- und Hostarchitektur bei der Erstellung mit dem Visual C++-Toolset

Sie können die Zielarchitektur (x64, Win32, ARM64 oder ARM) über architecture.value festlegen. Dies entspricht der Übergabe von -A an CMake über die Befehlszeile. Weitere Informationen finden Sie im Abschnitt zur Plattformauswahl.

Hinweis

Derzeit erwarten Visual Studio-Generatoren beim Erstellen für x86 die Win32-Syntax und Befehlszeilen-Generatoren (wie Ninja) die x86-Syntax.

Sie können die Hostarchitektur (x64 oder x86) und das Toolset mithilfe von toolset.value festlegen. Dies entspricht der Übergabe von -T an CMake über die Befehlszeile. Weitere Informationen finden Sie im Abschnitt zur Toolsetauswahl.

Die Werte von architecture.strategy und toolset.strategy teilen CMake mit, wie mit den Feldern für die Architektur und das Toolset umgegangen werden soll. set bedeutet, dass CMake den entsprechenden Wert festlegt und external bedeutet, dass CMake den entsprechenden Wert nicht festlegt.

Wir empfehlen die Verwendung set mit IDE-Generatoren wie dem Visual Studio-Generator. Verwenden Sie external mit Befehlszeilen-Generatoren wie Ninja. Mithilfe dieser Werte können Anbieter wie Visual Studio die erforderliche Umgebung bereitstellen, bevor CMake aufgerufen wird. Weitere Informationen zu den Feldern für Architektur und Toolset finden Sie in der Liste der Konfigurationsvoreinstellungen.

Wenn Sie keine Umgebung einbinden möchten, können Sie architecture.strategy auf external und architecture.value auf unspecified festlegen. Aus einem der folgenden Gründen kann es sich anbieten, keine Umgebung einzubinden:

• Sie verwenden ein anderes Toolset als MSVC.
• Sie verwenden eine benutzerdefinierte Toolkette, z. B. in eingebetteten Szenarios.
• Sie benötigen keine bestimmte Buildumgebung.

Eine vollständige Liste der IDE-Generatoren, die das Architekturfeld unterstützen, finden Sie unter CMAKE_GENERATOR_PLATFORM. Eine vollständige Liste der IDE-Generatoren, die das Toolsetfeld unterstützen, finden Sie unter CMAKE_GENERATOR_TOOLSET.

In den folgenden Beispielen wird gezeigt, wie Sie ARM64 als Ziel für den Ninja-Generator und Win32 (x86) als Ziel für den Visual Studio 16 2019-Generator verwenden:

"generator": "Ninja",
"architecture": {
    "strategy": "external",
    "value": "arm64"
},

"generator": "Visual Studio 16 2019",
"architecture": {
    "strategy": "set",
     "value": "Win32"
},

Festlegen von und Verweisen auf Umgebungsvariablen

Sie können Umgebungsvariablen mithilfe der Umgebungszuordnung festlegen. Umgebungsvariablen werden über das Feld inherits geerbt, Sie können sie jedoch bei Bedarf überschreiben.

Die Umgebung einer Voreinstellung besteht aus ihrer eigenen Umgebung und der Umgebung aller ihr übergeordneten Elemente. Wenn mehrere inherits-Voreinstellungen widersprüchliche Werte für dieselbe Variable angeben, wird die frühere Voreinstellung in der inherits-Liste verwendet. Sie können eine von einer anderen Voreinstellung geerbte Variable löschen, indem Sie sie auf null festlegen.

Umgebungsvariablen, die in einer Konfigurationsvoreinstellung festgelegt sind, werden auch automatisch an zugeordnete Buildvoreinstellungen und Testvoreinstellungen übergeben, es sei denn, inheritConfigureEnvironment ist auf false festgelegt. Weitere Informationen finden Sie in der Liste der Konfigurationsvoreinstellungen.

Mit der Syntax $env{<variable-name>} und $penv{<variable-name>} können Sie auf Umgebungsvariablen verweisen. Weitere Informationen finden Sie im Abschnitt zur Makroerweiterung.

Konfigurieren von IntelliSense für einen Crosscompiler

Standardmäßig verwendet Visual Studio den passenden IntelliSense-Modus für das Toolset und die Zielarchitektur, die Sie angeben. Wenn Sie Crosskompilierung verwenden, müssen Sie möglicherweise über die Option intelliSenseMode in der Anbieterzuordnung für Visual Studio-Einstellungen manuell den richtigen IntelliSense-Modus angeben. Weitere Informationen finden Sie im Eintrag zu intelliSenseMode in der Tabelle unter Anbieterzuordnung für Visual Studio-Einstellungen.

Konfigurieren und Erstellen auf einem Remotesystem oder dem Windows-Subsystem für Linux

Dank der Unterstützung von CMakePresets.json in Visual Studio können Sie Ihr Projekt auf Windows-Systemen, dem WSL und Remotesystemen leicht konfigurieren und erstellen. Die Schritte zum Konfigurieren und Erstellen Ihres Projekts sind bei all diesen Systemen identisch. Es gibt jedoch einige spezifische Verhalten bei der Remoteentwicklung.

Verhalten von ${sourceDir} in Remotekopierszenarios

In lokalen Szenarios (einschließlich WSL1) gibt der Wert von ${sourceDir} den Pfad des in Visual Studio geöffneten Projektquellenverzeichnisses an. In Remotekopierszenarios gibt der Wert von ${sourceDir} den Pfad zum Projektquellenverzeichnis auf dem Zielsystem an und nicht den zum Projektquellenverzeichnis auf dem lokalen Computer.

In der Anbieterzuordnung für Visual Studio-Remoteeinstellungen bestimmt der Wert von sourceDir das Projektquellenverzeichnis auf dem Zielsystem (der Standardwert ist $env{HOME}/.vs/$ms{projectDirName}). Weitere Informationen finden Sie im Eintrag zu sourceDir in der Tabelle unter Anbieterzuordnung für Visual Studio-Einstellungen.

Lokaler Ordner für Remoteausgabe

Bei Remotekopierszenarios ist ein lokales Verzeichnis erforderlich, damit einige Remotedateien wie Antwort- und Builddateien für die CMake-Datei-API kopiert werden können, wenn copyBuildOutput in der Anbieterzuordnung für Visual Studio-Remoteeinstellungen auf true festgelegt ist. Diese Dateien werden automatisch in <local-source-directory>/out/<remote-connection-ID>/build/${presetName} kopiert.

Aufrufen derselben Konfigurationsvoreinstellung unter Windows und auf dem WSL1

Wenn Sie versuchen, dieselbe Konfigurationsvoreinstellung für Windows und das WSL1 zu verwenden, wird eine Fehlermeldung angezeigt. Windows und das WSL1 verwenden beide das Windows-Dateisystem, sodass CMake versucht, für die Windows- und WSL1-Buildstruktur dasselbe Ausgabeverzeichnis (binaryDir) zu verwenden.

Wenn Sie für Windows und das WSL1-Toolset dieselbe Konfigurationsvoreinstellung verwenden möchten, erstellen Sie eine zweite Konfigurationsvoreinstellung, die von der ursprünglichen Voreinstellung erbt und einen neuen binaryDir-Wert angibt. Im folgenden Beispiel kann windows-preset für Windows und base-preset für das WSL1 verwendet werden:

{
  "name": "windows-preset",
  "inherits": "base-preset",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": "Windows"
    }
  }
}

Hinweis

In Visual Studio 2019 wird nur das WSL1-Toolset unterstützt. Dieses Verhalten ist immer dann zu beobachten, wenn Sie configure sowohl unter Windows als auch auf dem WSL aufrufen.

Aktivieren der vcpkg-Integration

vcpkg unterstützt Sie bei der Verwaltung von C- und C++-Bibliotheken unter Windows, Linux und macOS. Zum Aktivieren der vcpkg-Integration muss eine vcpkg-Toolkettendatei (vcpkg.cmake) an CMake übergeben werden. Weitere Informationen finden Sie in der vcpkg-Dokumentation.

Wenn die CMakePresets.json-Integration aktiviert ist, übergibt Visual Studio Ihre vcpkg-Toolkettendatei nicht mehr automatisch an CMake. Durch diese Änderung wird das Visual Studio-spezifische Verhalten entfernt und sichergestellt, dass Ihr Build über die Befehlszeile reproduziert werden kann.

Legen Sie stattdessen den Pfad mithilfe der Umgebungsvariablen VCPKG_ROOT in CMakePresets.json auf vcpkg.cmake fest:

"cacheVariables": {
   "CMAKE_TOOLCHAIN_FILE": {
      "value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
       "type": "FILEPATH"
    }
 },

Für VCPKG_ROOT sollte der Stamm Ihrer vcpkg-Installation festgelegt werden. Weitere Informationen finden Sie im Abschnitt zu den vcpkg-Umgebungsvariablen.

Wenn Sie bereits eine CMake-Toolkettendatei verwenden und die vcpkg-Integration aktivieren möchten, sehen Sie sich den Abschnitt zur Verwendung mehrerer Toolkettendateien an. Befolgen Sie die beschriebenen Anweisungen, um eine externe Toolkettendatei mit einem Projekt unter Verwendung von vcpkg zu nutzen.

Variablenersetzung in launch.vs.json und tasks.vs.json

CMakePresets.json unterstützt Variablenersetzung in launch.vs.json und tasks.vs.json. Hier einige Überlegungen dazu:

• Umgebungsvariablen, die in der aktiven Konfigurationsvoreinstellung festgelegt sind, werden automatisch an die Konfigurationen launch.vs.json und tasks.vs.json übergeben. Sie können einzelne Umgebungsvariablen in launch.vs.json und tasks.vs.json löschen, indem Sie sie auf null festlegen. Im folgenden Beispiel wird die Variable DEBUG_LOGGING_LEVEL in launch.vs.json auf null festgelegt: "env": { "DEBUG_LOGGING_LEVEL": null }.

• Schlüsselwerte, die in der aktiven Konfigurationsvoreinstellung festgelegt sind, stehen in launch.vs.json und tasks.vs.json zur Verfügung und können mit der Syntax ${cmake.<KEY-NAME>} genutzt werden. Mit ${cmake.binaryDir} kann beispielsweise auf das Ausgabeverzeichnis der aktiven Konfigurationsvoreinstellung verwiesen werden.

• Einzelne Umgebungsvariablen, die in der Umgebungszuordnung der aktiven Konfigurationsvoreinstellung festgelegt sind, stehen in launch.vs.json und tasks.vs.json zur Verfügung und können mit der Syntax ${env.<VARIABLE-NAME>} genutzt werden.

Aktualisieren Sie die Dateien launch.vs.json und task.vs.json, sodass diese auf die CMakePresets.json-Syntax statt auf die CMakeSettings.json-Syntax verweisen. Makros, die auf die alte CMakeSettings.json-Syntax verweisen, wenn die aktive Konfigurationsdatei CMakePresets.json ist, sind zur Einstufung als veraltet in einem zukünftigen Release vorgemerkt. Verweisen Sie z. B. mit ${cmake.binaryDir} statt ${cmake.buildRoot} auf das Ausgabeverzeichnis der aktiven Konfigurationsvoreinstellung, da CMakePresets.json die binaryDir-Syntax verwendet.

Problembehandlung

Wenn etwas nicht wie erwartet funktioniert, können Sie einige Schritte zur Problembehandlung ausprobieren.

Wenn CMakePresets.json oder CMakeUserPresets.json ungültig ist, greift Visual Studio auf das Standardverhalten zurück und zeigt nur die Standardkonfigurationsvoreinstellungen an. Visual Studio IntelliSense kann Ihnen dabei helfen, viele dieser JSON-Fehler zu erkennen. Allerdings weiß IntelliSense nicht, ob Sie mit inherits oder configurePreset mit dem falschen Namen auf eine Voreinstellung verweisen.

Führen Sie über die Befehlszeile am Stamm Ihres Projektverzeichnisses cmake --list-presets aus, um zu überprüfen, ob Ihre Voreinstellungsdateien gültig sind. (CMake 3.20 oder höher ist erforderlich.) Wenn eine der Dateien ungültig ist, wird der folgende Fehler angezeigt:

CMake Error: Could not read presets from
C:/Users/<user>/source/repos/<project-name>: JSON parse error

Weitere Schritte zur Problembehandlung sind z. B.:

• Löschen Sie den Cache, und konfigurieren Sie das Projekt neu (CMake: Cache löschen und Projektnamen>konfigurieren).<>
• Schließen Sie den Ordner in Visual Studio (Datei>Ordner schließen), und öffnen Sie ihn erneut.
• Löschen Sie den Ordner .vs im Stamm Ihres Projekts.

Wenn Sie ein Problem identifiziert haben, ist die beste Möglichkeit zur Meldung dieses Problems das Auswählen der Schaltfläche Feedback senden in der oberen rechten Ecke in Visual Studio.

Aktivieren der Protokollierung für Remoteverbindungen

Sie können die Protokollierung für Remoteverbindungen aktivieren, wenn Sie Probleme beim Herstellen einer Verbindung mit einem Remotesystem oder beim Kopieren von Dateien auf ein solches System haben. Weitere Informationen finden Sie unter Protokollierung für Remoteverbindungen.

Aktivieren von AddressSanitizer für Windows und Linux

Visual Studio unterstützt AddressSanitizer (ASAN), einen C- und C++-Laufzeitspeicherfehlerdetektor für die Windows- und Linux-Entwicklung. Die addressSanitizerEnabled Option in CMakeSettings.json aktiviert AddressSanitizer. CMakePresets.json unterstützt dieses Verhalten nicht.

Aktivieren und deaktivieren Sie AddressSanitizer stattdessen, indem Sie die erforderlichen Compiler- und Linkerflags selbst festlegen. Durch die Festlegung wird das Visual Studio-spezifische Verhalten entfernt und sichergestellt, dass dieselbe Datei CMakePresets.json Ihren Build über die Befehlszeile reproduzieren kann.

Sie können der Datei CMakeLists.txt das folgende Beispiel hinzufügen, um AddressSanitizer für ein Ziel zu aktivieren oder zu deaktivieren:

option(ASAN_ENABLED "Build this target with AddressSanitizer" ON)

if(ASAN_ENABLED)
  if(MSVC)
    target_compile_options(<target> PUBLIC /fsanitize=address)
  else()
    target_compile_options(<target> PUBLIC -fsanitize=address <additional-options>)
    target_link_options(<target> PUBLIC -fsanitize=address)
  endif()
endif()

Im <additional-options>-Teil werden andere Kompilierungsflags aufgeführt wie "-fno-omit-frame-pointer". Weitere Informationen zu AddressSanitizer für Linux finden Sie im Abschnitt zur Verwendung von AddressSanitizer. Weitere Informationen zur Verwendung von AddressSanitizer mit MSVC finden Sie unter Verwenden von AddressSanitizer über eine Entwickler-Eingabeaufforderung.

Übergeben Sie mithilfe des Felds ASAN_OPTIONS in launch.vs.json Runtimeflags an AddressSanitizer. Wenn keine anderen Laufzeitoptionen angegeben sind, ist ASAN_OPTIONS standardmäßig auf detect_leaks=0 festgelegt, da LeakSanitizer in Visual Studio nicht unterstützt wird.

Ausführen von CMake über die Befehlszeile oder eine CI-Pipeline

Sie können zum Aufrufen von CMake in Visual Studio und über die Befehlszeile dieselben Dateien CMakePresets.json und CMakeUserPresets.json verwenden. Die Dokumentation zu CMake und die zu CTest sind die besten Quellen für Informationen zum Aufrufen von CMake und CTest mit --preset. Version 3.20 oder höher von CMake ist erforderlich.

Einbinden der Umgebung beim Erstellen mit Befehlszeilen-Generatoren unter Windows

Der Benutzer ist dafür verantwortlich, die Umgebung zu konfigurieren, bevor CMake bei der Erstellung mit einem Befehlszeilen-Generator aufgerufen wird. Wenn die Erstellung mit Ninja und dem Visual C++-Toolset unter Windows erfolgt, binden Sie die Umgebung vor dem Aufruf von CMake ein, um das Buildsystem zu generieren. Rufen Sie hierzu vcvarsall.bat mit dem Argument architecture auf. Das Argument architecture gibt die zu verwendende Host- und Zielarchitektur an. Weitere Informationen finden Sie unter vcvarsall-Syntax. Wenn die Erstellung mit einem Visual Studio-Generator unter Linux oder Windows erfolgt, müssen Sie diesen Schritt nicht ausführen.

Dies ist der gleiche Schritt, den Visual Studio für Sie ausführt, wenn die IDE CMake aufruft. Visual Studio analysiert die aktive Konfigurationsvoreinstellung für die über toolset und architecture angegebene Host- und Zielarchitektur. Visual Studio bindet dann die angegebene Umgebung aus vcvarsall.bat ein. Wenn die Erstellung über die Windows-Befehlszeile mit Ninja erfolgt, müssen Sie diesen Schritt selbst ausführen.

vcvarsall.bat wird mit Visual Studio Build Tools installiert. Standardmäßig wird vcvarsall.bat unter C:\Program Files (x86)\Microsoft Visual Studio\2019\<edition>\VC\Auxiliary\Build installiert. Sie können vcvarsall.bat zu PATH hinzufügen, wenn Sie den Befehlszeilen-Workflow häufig verwenden.

Beispiel für Befehlszeilen-Workflow

Sie können die folgenden Befehle verwenden, um ein CMake-Projekt zu konfigurieren und zu erstellen, das Ninja mit ARM64 mit x64-Buildtools als Ziel verwendet. Version 3.20 oder höher von CMake ist erforderlich. Führen Sie die folgenden Befehle in dem Verzeichnis aus, in dem sich Ihre Datei CMakePresets.json befindet:

/path/to/vcvarsall.bat x64_arm64 
cmake --list-presets=all .
cmake --preset <configurePreset-name>
cmake --build --preset <buildPreset-name> 

Beispieldatei für CMakePresets.json

Die Datei CMakePresets.json in box2d-lite enthält Beispiele für Konfigurations-, Build- und Testvoreinstellungen. Weitere Informationen zu diesem Beispiel finden Sie in der Präsentation "Einführung in CMakePresets.json". Sie können ein weiteres Beispiel im DirectXTK-Projekt sehen, das viele Buildziele in seinem configurePresets Abschnitt anzeigt.

Nächste Schritte

In den folgenden Artikeln erhalten Sie weitere Informationen zum Konfigurieren und Debuggen von CMake-Projekten in Visual Studio:

CMake Projects in Visual Studio (CMake-Projekte in Visual Studio)
Anpassen von CMake-Buildeinstellungen
Konfigurieren von CMake-Debugsitzungen
CMake predefined configuration reference (Referenz für vordefinierte CMake-Konfigurationen)