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 Eigenschafttrue
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 UmgebungsvariableASAN_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, woCMakeCache.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 DateiCMakeLists.txt
oderCMakeSettings.json
geändert.cacheRoot
: Gibt den Pfad zu einem CMake-Cache an. Dieses Verzeichnis sollte eine vorhandeneCMakeCache.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.
Um einen Visual Studio-Generator in Visual Studio 2019 anzugeben, klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf die CMakeLists.txt
Datei, und wählen Sie "CMake Einstellungen für Projekt>"Erweiterten Einstellungen> 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 kannNormal
,Verbose
oderDiagnostic
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 kannrsync
odersftp
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}
, wobeiVARIABLE
eine Umgebungsvariable ist, die auf System-, Benutzer- oder Sitzungsebene definiert wurde.remoteCopySources
: Einboolean
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
: Einboolean
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
: Einarray
, 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 DateiCMakeLists.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 DateiCMakeCache.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ßtremoteCopyUseOptimizations
,rsyncSingleDirectoryCommandArgs
undremoteCopySourcesMaxSmallChange
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 Formnamespace.variable
über eine Konfiguration auf deren Variablen verwiesen werden kann. Das Standardumgebungsobjekt wirdenv
genannt und mit bestimmten Systemumgebungsvariablen aufgefüllt, darunter%USERPROFILE%
.environment
: Identifiziert die Gruppe von Variablen eindeutig. Ermöglicht der Gruppe, später in eineminheritEnvironments
-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 derCMakeLists.txt
-Stammdatei${projectDir}
: Der vollständige Pfad des Ordners, der dieCMakeLists.txt
-Stammdatei enthält${projectDirName}
: Der Name des Ordners, der dieCMakeLists.txt
-Stammdatei enthält${thisFile}
– der vollständige Pfad derCMakeSettings.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...]
Option | Beschreibung |
---|---|
--version |
Ausgabe der Ninja-Version („1.7.1“) |
-C DIR |
Wechsel zu DIR, bevor andere Aktionen ausgeführt werden |
-f FILE |
Angabe der Eingabedatei für den Build (Standard: build.ninja ) |
-j N |
Ausführen von N gleichzeitigen Aufträgen (Standard: 14, abgeleitet von den verfügbaren CPUs) |
-k N |
Fortsetzen, bis N Aufträge fehlschlagen (Standard: 1) |
-l N |
Kein Starten von neuen Aufträgen, wenn die durchschnittliche Auslastung größer als N ist |
-n |
Testausführung (Befehle werden nicht ausgeführt, verhalten sich jedoch, als wären sie erfolgreich) |
-v |
Anzeigen aller Befehlszeilen während des Builds |
-d MODE |
Aktivieren des Debuggens (verwenden Sie -d list , um Modi aufzulisten) |
-t TOOL |
Ausführen eines Zusatztools (verwenden Sie -t list , um zusätzliche Tools aufzulisten) Beendet Optionen auf oberster Ebene; weitere Flags werden an das Tool übergeben |
-w FLAG |
Anpassen von Warnungen (verwenden Sie -w list , um Warnungen aufzulisten) |