CMakeSettings.json-Schemareferenz

CMake-Projekte werden von Visual Studio 2017 und höher unterstützt.

Die Datei CMakeSettings.json enthält Informationen, die Visual Studio für IntelliSense und das Erstellen der Befehlszeilenargumente verwendet, die an CMake für eine angegebene Konfiguration und Compilerumgebung übergeben werden. Eine Konfiguration gibt Eigenschaften an, die für eine bestimmte Plattform und einen bestimmten Buildtyp gelten, z. B. x86-Debug oder Linux-Release. Jede Konfiguration gibt eine Umgebung an, die Informationen zum Compilertoolset kapselt, z. B. MSVC, GCC oder Clang. CMake verwendet die Befehlszeilenargumente, um die Stammdatei CMakeCache.txt sowie andere Projektdateien für das Projekt erneut zu generieren. Die Werte können in den CMakeLists.txt-Dateien überschrieben werden.

Sie können Konfigurationen in der IDE hinzufügen oder entfernen und sie dann direkt in der JSON-Datei bearbeiten oder den Editor für CMake-Einstellungen verwenden (Visual Studio 2019 und höher). Sie können in der IDE einfach zwischen den Konfigurationen wechseln, um die verschiedenen Projektdateien zu generieren. Weitere Informationen finden Sie unter Anpassen von CMake-Buildeinstellungen.

Konfigurationen

Das configurations-Array enthält alle Konfigurationen für ein CMake-Projekt. Weitere Informationen zu vordefinierten Konfigurationen finden Sie unter Vordefinierte CMake-Buildkonfigurationen. Sie können der Datei eine beliebige Anzahl vordefinierter oder benutzerdefinierter Konfigurationen hinzufügen.

Eine configuration verfügt über die folgenden Eigenschaften:

• addressSanitizerEnabled: Wenn der Wert dieser Eigenschaft true lautet, wird das Programm mit AddressSanitizer kompiliert. Unter Linux wird mit -fno-omit-frame-pointer kompiliert. Die Compileroptimierungsebene -Os oder -Oo liefert die besten Ergebnisse.

• addressSanitizerRuntimeFlags: Hierbei handelt es sich um die Runtimeflags, die über die Umgebungsvariable ASAN_OPTIONS an AddressSanitizer übergeben werden. Format: flag1=Wert:flag2=Wert2.

• buildCommandArgs: Gibt native Buildoptionen an, die nach --build -- an CMake übergeben werden. Beispielsweise wird beim Übergeben von -v bei Verwendung des Ninja-Generators erzwungen, dass Ninja Befehlszeilen ausgibt. Weitere Informationen zu Ninja-Befehlen finden Sie unter Ninja-Befehlszeilenargumente.

• buildRoot: Gibt das Verzeichnis an, in dem CMake Buildskripts für den ausgewählten Generator erstellt. Ist dem Schalter -DCMAKE_BINARY_DIR zugeordnet und gibt an, wo CMakeCache.txt erstellt wird. Wenn der Ordner nicht vorhanden ist, wird er erstellt. Unterstützte Makros sind ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.

• cacheGenerationCommand: Gibt ein Befehlszeilentool und Argumente an, z. B. gencache.bat debug, um den Cache zu generieren. Der Befehl wird in der Shell in der für die Konfiguration angegebenen Umgebung ausgeführt, wenn der Benutzer die erneute Generierung explizit anfordert. Andernfalls wird die Datei CMakeLists.txt oder CMakeSettings.json geändert.

• cacheRoot: Gibt den Pfad zu einem CMake-Cache an. Dieses Verzeichnis sollte eine vorhandene CMakeCache.txt-Datei enthalten.

• clangTidyChecks: Durch Kommas getrennte Liste der Warnungen, die an clang-tidy übergeben werden. Platzhalter sind zulässig, und durch das Präfix „-“ werden Überprüfungen entfernt.

• cmakeCommandArgs: Gibt zusätzliche Befehlszeilenoptionen an, die beim Aufruf zum Generieren der Projektdateien an CMake übergeben werden.

• cmakeToolchain: Gibt die Toolkettendatei an. Sie wird mit -DCMAKE_TOOLCHAIN_FILE an CMake übergeben.

• codeAnalysisRuleset: Gibt den Regelsatz an, der beim Ausführen der Codeanalyse verwendet werden soll. Sie können einen vollständigen Pfad oder den Dateinamen einer Regelsatzdatei verwenden, die von Visual Studio installiert wird.

• configurationType: Gibt die Buildtypkonfiguration für den ausgewählten Generator an. Folgende stehen zur Auswahl:

  • Debug
  • Release
  • MinSizeRel
  • RelWithDebInfo

• ctestCommandArgs: Gibt zusätzliche Befehlszeilenoptionen an, die beim Ausführen der Tests an CTest übergeben werden sollen.

• description: Die Beschreibung dieser Konfiguration, die in Menüs angezeigt wird.

• enableClangTidyCodeAnalysis: Clang-Tidy wird für die Codeanalyse verwendet.

• enableMicrosoftCodeAnalysis: Codeanalysetools von Microsoft werden für die Codeanalyse verwendet.

• generator: Gibt den CMake-Generator an, der für diese Konfiguration verwendet werden soll. Folgende stehen zur Auswahl:

  Nur Visual Studio 2019:

  • Visual Studio 16 2019
  • Visual Studio 16 2019 Win64
  • Visual Studio 16 2019 ARM

  Visual Studio 2017 und höher:

  • 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
  • Unix Makefiles
  • Ninja

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. Im Fall eines Buildfehlers können Sie CMake anweisen, stattdessen Visual Studio-Projekte zu erstellen.

Öffnen Sie den Einstellungs-Editor über das Hauptmenü, indem Sie auf CMake > CMake-Einstellungen klicken, um einen Visual Studio-Generator in Visual Studio 2017 anzugeben. Löschen Sie „Ninja“, und geben Sie „V“ ein. Durch diese Änderung wird IntelliSense aktiviert, und Sie können den gewünschten Generator auswählen.

Wenn Sie einen Visual Studio-Generator in Visual Studio 2019 angeben möchten, klicken Sie mit der rechten Maustaste auf die CMakeLists.txt Datei in Projektmappen-Explorer, und wählen Sie "CMake-Einstellungen" für Projekt>"Erweiterte Einstellungen>für CMake-Generator anzeigen" aus.

Wenn in der aktiven Konfiguration ein Visual Studio-Generator angegeben ist, wird standardmäßig MSBuild mit -m -v:minimal-Argumenten aufgerufen. Verwenden Sie die buildCommandArgs Eigenschaft innerhalb der CMakeSettings.json Datei, um den Build anzupassen. Hier können Sie MSBuild-Befehlszeilenargumente angeben, die an das Buildsystem übergeben werden:

"buildCommandArgs": "-m:8 -v:minimal -p:PreferredToolArchitecture=x64"

• installRoot: Gibt das Verzeichnis an, in dem CMake Installationsziele für den ausgewählten Generator erstellt. Unterstützte Makros sind ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.

• inheritEnvironments: Gibt mindestens eine Compilerumgebung an, von der diese Konfiguration abhängt. Dabei kann es sich um jede benutzerdefinierte Umgebung oder eine der vordefinierten Umgebungen handeln. Weitere Informationen finden Sie unter Umgebungen.

• intelliSenseMode: Gibt den Modus zum Berechnen von IntelliSense-Informationen an. Folgende Werte sind zulässig:

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

• name: Benennt die Konfiguration. Weitere Informationen zu vordefinierten Konfigurationen finden Sie unter Vordefinierte CMake-Buildkonfigurationen.

• wslPath: Der Pfad zum Startprogramm einer Instanz des Windows-Subsystems für Linux.

Einstellungen für CMake Linux-Projekte

• remoteMachineName: Gibt den Namen des Linux-Remotecomputers an, auf dem CMake, Builds und der Debugger gehostet werden. Verwenden Sie den Verbindungs-Manager zum Hinzufügen neuer Linux-Computer. Unterstützte Makros sind ${defaultRemoteMachineName}.
• remoteCopySourcesOutputVerbosity: Gibt den Ausführlichkeitsgrad des Quellkopiervorgangs zum Remotecomputer an. Dieser kann Normal, Verbose oder Diagnostic lauten.
• remoteCopySourcesConcurrentCopies: Gibt die gleichzeitigen Kopien an, die während der Synchronisierung der Quellen mit dem Remotecomputer verwendet werden (nur sftp).
• remoteCopySourcesMethod: Gibt die Methode zum Kopieren von Dateien auf den Remotecomputer an. Diese kann rsync oder sftp lauten.
• remoteCMakeListsRoot: Gibt das Verzeichnis auf dem Remotecomputer an, das das CMake-Projekt enthält. Unterstützte Makros sind ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator} und ${env.VARIABLE}.
• remoteBuildRoot: Gibt das Verzeichnis auf dem Remotecomputer an, in dem CMake Buildskripts für den ausgewählten Generator erstellt. Unterstützte Makros sind ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.
• remoteInstallRoot: Gibt das Verzeichnis auf dem Remotecomputer an, in dem CMake Installationsziele für den ausgewählten Generator erstellt. Unterstützte Makros sind ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator} und ${env.VARIABLE}, wobei VARIABLE eine Umgebungsvariable ist, die auf System-, Benutzer- oder Sitzungsebene definiert wurde.
• remoteCopySources: Ein boolean Wert, der angibt, ob Visual Studio Quelldateien auf den Remotecomputer kopieren soll. Der Standardwert ist „true“. Legen Sie diesen Wert auf FALSE fest, wenn Sie die Dateisynchronisierung selbst verwalten.
• remoteCopyBuildOutput: Ein boolean Wert, der angibt, ob die Buildausgabe aus dem Remotesystem kopiert werden soll.
• remoteCopyAdditionalIncludeDirectories: Zusätzlich sind Verzeichnisse enthalten, die vom Remotecomputer kopiert werden sollen, um IntelliSense zu unterstützen. Format: „/Pfad1;/Pfad2…“.
• remoteCopyExcludeDirectories: Verzeichnisse einschließen, die nicht vom Remotecomputer kopiert werden sollen. Format: „/Pfad1;/Pfad2…“.
• remoteCopyUseCompilerDefaults: Gibt an, ob die Standardeinstellung des Compilers definiert und Pfade für IntelliSense enthalten soll. Hier sollte nur FALSE gewählt werden, wenn der verwendete Compiler gcc-Argumente nicht unterstützen soll.
• rsyncCommandArgs: Gibt Befehlszeilenoptionen an, die an rsync übergeben werden.
• remoteCopySourcesExclusionList: Ein array, das eine Liste mit Pfaden angibt, die beim Kopieren von Quelldateien ausgeschlossen werden sollen: Als Pfad kann der Name einer Datei/eines Verzeichnisses oder ein relativer Pfad vom Stammverzeichnis der Kopie angegeben werden. Die Platzhalter * und ? können für einen Globmusterabgleich verwendet werden.
• cmakeExecutable: Gibt den vollständigen Pfad zur ausführbaren CMake-Programmdatei an, einschließlich des Dateinamens und der Dateierweiterung.
• remotePreGenerateCommand: Gibt den Befehl an, der vor der Ausführung von CMake zum Analysieren der Datei CMakeLists.txt ausgeführt werden soll.
• remotePrebuildCommand: Gibt den Befehl an, der vor der Erstellung auf dem Remotecomputer ausgeführt wird.
• remotePostbuildCommand: Gibt den Befehl an, der nach der Erstellung auf dem Remotecomputer ausgeführt wird.
• 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 Datei CMakeCache.txt festlegen, wird empfohlen, diese stattdessen hier hinzuzufügen. In diesem Beispiel wird gezeigt, wie Sie die Name-Wert-Paare für das MSVC-Toolset 14.14.26428 angeben können:

"variables": [
    {
      "name": "CMAKE_CXX_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    },
    {
      "name": "CMAKE_C_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    }
  ]

Wenn Sie den "type" nicht definieren, wird standardmäßig der Typ "STRING" angenommen.

• remoteCopyOptimizations: Visual Studio 2019, Version 16.5 oder höher , Eigenschaften zum Steuern der Quellkopie in das Remoteziel. Optimierungen sind standardmäßig aktiviert. Schließt remoteCopyUseOptimizations, rsyncSingleDirectoryCommandArgs und remoteCopySourcesMaxSmallChange ein.

Umgebungen

Eine Umgebung kapselt die Umgebungsvariablen, die im Prozess festgelegt werden, den Visual Studio verwendet, um CMake aufzurufen. Bei MSVC-Projekten werden die Variablen erfasst, die in einer Developer-Eingabeaufforderung für eine bestimmte Plattform festgelegt werden. Die Umgebung entspricht beispielsweise msvc_x64_x64 der Ausführung der Entwickler-Eingabeaufforderung für VS {version} mit dem Argument "-arch=amd64 -host_arch=amd64 ". Sie können die env.{<variable_name>}-Syntax in CMakeSettings.json verwenden, um auf die einzelnen Umgebungsvariablen zu verweisen, z. B. um Pfade zu Ordnern zu erstellen. Die folgenden vordefinierten Umgebungen werden bereitgestellt:

• linux_arm: Hiermit wird ARM Linux als Remotezielversion festgelegt.
• linux_x64: Hiermit wird x64 Linux als Remotezielversion festgelegt.
• linux_x86: Hiermit wird x86 Linux als Remotezielversion festgelegt.
• msvc_arm: Hiermit wird ARM Windows mit dem MSVC-Compiler als Zielversion festgelegt.
• msvc_arm_x64: Hiermit wird ARM Windows mit dem 64-Bit-MSVC-Compiler als Zielversion festgelegt.
• msvc_arm64: Hiermit wird ARM64 Windows mit dem MSVC-Compiler als Zielversion festgelegt.
• msvc_arm64_x64: Hiermit wird ARM64 Windows mit dem 64-Bit-MSVC-Compiler als Zielversion festgelegt.
• msvc_arm64ec: Ziel ARM64EC Windows mit dem MSVC-Compiler.
• msvc_arm64ec_x64: Ziel ARM64EC Windows mit dem 64-Bit-MSVC-Compiler.
• msvc_x64: Hiermit wird x64 Windows mit dem MSVC-Compiler als Zielversion festgelegt.
• msvc_x64_x64: Hiermit wird x64 Windows mit dem 64-Bit-MSVC-Compiler als Zielversion festgelegt.
• msvc_x86: Hiermit wird x86 Windows mit dem MSVC-Compiler als Zielversion festgelegt.
• msvc_x86_x64: Hiermit wird x86 Windows mit dem 64-Bit-MSVC-Compiler als Zielversion festgelegt.

Zugreifen auf Umgebungsvariablen in CMakeLists.txt

In der Datei CMakeLists.txt wird mit der Syntax $ENV{variable_name} auf alle Umgebungsvariablen verwiesen. Öffnen Sie die entsprechende Eingabeaufforderung und geben Sie SET ein, damit die verfügbaren Variablen für eine Umgebung angezeigt werden. Einige der Informationen in Umgebungsvariablen sind auch über Variablen für die CMake-Systemintrospektion verfügbar. Die Verwendung der Umgebungsvariable ist jedoch möglicherweise bequemer für Sie. Beispielsweise können Sie die MSVC-Compiler- oder die Windows-SDK-Version über die Umgebungsvariablen einfach abrufen.

Benutzerdefinierte Umgebungsvariablen

In CMakeSettings.json können Sie benutzerdefinierte Umgebungsvariablen global oder pro Konfiguration im environments-Array definieren. Eine benutzerdefinierte Umgebung bietet eine einfache Möglichkeit zum Gruppieren von Eigenschaften. Sie können sie anstelle einer vordefinierten Umgebung verwenden oder eine vordefinierte Umgebung erweitern oder ändern. Jedes Element im environments-Array besteht aus Folgendem:

• namespace: Benennt die Umgebung, sodass durch die Form namespace.variable über eine Konfiguration auf deren Variablen verwiesen werden kann. Das Standardumgebungsobjekt wird env genannt und mit bestimmten Systemumgebungsvariablen aufgefüllt, darunter %USERPROFILE%.
• environment: Identifiziert die Gruppe von Variablen eindeutig. Ermöglicht der Gruppe, später in einem inheritEnvironments-Eintrag geerbt zu werden.
• groupPriority: Eine ganze Zahl, die die Priorität dieser Variablen beim Auswerten angibt. Elemente mit höherer Nummer werden zuerst ausgewertet.
• inheritEnvironments: Ein Array von Werten, die den Satz von Umgebungen angeben, die von dieser Gruppe geerbt werden. Dieses Feature ermöglicht das Erben von Standardumgebungen und das Erstellen benutzerdefinierter Umgebungsvariablen, die bei der Ausführung an CMake übergeben werden.

Visual Studio 2019, Version 16.4 und höher: Debugziele werden mithilfe der in CMakeSettings.json angegebenen Umgebung automatisch gestartet. Sie können Umgebungsvariablen pro Ziel oder pro Aufgabe in launch.vs.json und tasks.vs.json überschreiben oder hinzufügen.

Im folgenden Beispiel wird die globale Variable BuildDir definiert, die in den Konfigurationen „x86-Debug“ und „x64-Debug“ geerbt wird. Jede Konfiguration verwendet die Variable, um den Wert für die Eigenschaft buildRoot der Konfiguration anzugeben. Beachten Sie ebenfalls, wie jede Konfiguration die Eigenschaft inheritEnvironments verwendet, um eine Variable anzugeben, die nur für diese Konfiguration gilt.

{
  // The "environments" property is an array of key-value pairs of the form
  // { "EnvVar1": "Value1", "EnvVar2": "Value2" }
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x86 compiler.
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.BuildDir}\\${name}"    },
    {
      "name": "x64-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x64 compiler.
      "inheritEnvironments": [ "msvc_x64" ],
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

Im nächsten Beispiel definiert die x86-Debug-Konfiguration einen eigenen Wert für die Eigenschaft BuildDir. Dieser Wert überschreibt den Wert, der von der globalen Eigenschaft BuildDir festgelegt wird, sodass BuildRoot zu D:\custom-builddir\x86-Debug ausgewertet wird.

{
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",

      // The syntax for this property is the same as the global one above.
      "environments": [
        {
          // Replace the global property entirely.
          "BuildDir": "D:\\custom-builddir"
          // This environment does not specify a namespace, hence by default "env" is assumed.
          // "namespace" : "name" would require that this variable be referenced with "${name.BuildDir}".
        }
      ],

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      // Evaluates to "D:\custom-builddir\x86-Debug"
      "buildRoot": "${env.BuildDir}\\${name}"
    },
    {
      "name": "x64-Debug",

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x64" ],
      // Since this configuration doesn't modify BuildDir, it inherits
      // from the one defined globally.
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

Makros

Die folgenden Makros können in CMakeSettings.json verwendet werden:

• ${workspaceRoot}: Der vollständige Pfad zum Arbeitsbereichsordner
• ${workspaceHash}: Hash des Speicherorts für den Arbeitsbereich; nützlich für das Erstellen eines eindeutigen Bezeichners für den aktuellen Arbeitsbereich (z.B. für die Verwendung in Ordnerpfaden)
• ${projectFile}: Der vollständige Pfad der CMakeLists.txt-Stammdatei
• ${projectDir}: Der vollständige Pfad des Ordners, der die CMakeLists.txt-Stammdatei enthält
• ${projectDirName}: Der Name des Ordners, der die CMakeLists.txt-Stammdatei enthält
• ${thisFile} – der vollständige Pfad der CMakeSettings.json Datei
• ${name}: der Name der Konfiguration
• ${generator}: der Name des CMake-Generators, der in dieser Konfiguration verwendet wurde

Alle Verweise auf Makros und Umgebungsvariablen in CMakeSettings.json werden erweitert, bevor sie an die CMake-Befehlszeile übergeben werden.

Ninja-Befehlszeilenargumente

Wenn keine Ziele festgelegt sind, wird von Ninja das Standardziel erstellt.

C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise>ninja -?
ninja: invalid option -- `-?'
usage: ninja [options] [targets...]