Microsoft-Anbieterzuordnungen für CMakePresets.json und CMakeUserPresets.json

  • Artikel

CMake unterstützt die zwei Dateien CMakePresets.json und CMakeUserPresets.json, die es Benutzern ermöglichen, gemeinsame Konfigurations-, Build- und Testoptionen anzugeben und mit anderen zu teilen.

CMakePresets.json und CMakeUserPresets.json können zum Steuern von CMake in Visual Studio, Visual Studio Code, einer CI-Pipeline (Continuous Integration) oder von der Befehlszeile aus verwendet werden.

CMakePresets.json dient zum Speichern projektweiter Builds, und CMakeUserPresets.json ist für Entwickler konzipiert, die damit ihre eigenen lokalen Builds speichern können. Das Schema für beide Dateien ist identisch.

CMakePresets.json und CMakeUserPresets.json unterstützen Anbieterzuordnungen zum Speichern von anbieterspezifischen Informationen. Microsoft verwaltet zwei Anbieterzuordnungen mit spezifischen Optionen für Visual Studio und Visual Studio Code. Hier dokumentieren wir zwei Microsoft-Anbieterzuordnungen und -Anbietermakros. Weitere Informationen zum Rest des Schemas finden Sie in der offiziellen CMake-Dokumentation. Sie enthält Informationen zu Konfigurationsvoreinstellungen, Buildvoreinstellungen und Testvoreinstellungen.

Weitere Informationen zur Verwendung von CMakePresets.json in Visual Studio finden Sie unter Konfigurieren und Erstellen mit CMake-Voreinstellungen in Visual Studio.

Weitere Informationen zur Verwendung von CMakePresets.json in Visual Studio Code finden Sie unter Konfigurieren und Erstellen mit CMake-Voreinstellungen in VS Code.

Anbieterzuordnung für Visual Studio-Einstellungen

Pro Konfigurationsvoreinstellung ist eine Anbieterzuordnung mit dem Anbieter-URI microsoft.com/VisualStudioSettings/CMake/<version> zulässig. Diese enthält spezifische Optionen für die CMake-Integration in Visual Studio und Visual Studio Code. Alle Optionen in der Anbieterzuordnung gelten für Visual Studio. Optionen, die sowohl für Visual Studio als auch für Visual Studio Code gelten, wurden explizit gekennzeichnet.

Alle Einstellungen in der Anbieterzuordnung für Visual Studio-Einstellungen sind optional und werden von den vom inherits-Schlüssel angegebenen Konfigurationsvoreinstellungen geerbt. Nur geänderte Optionen werden in die Datei geschrieben. Die Anbieterzuordnung für Visual Studio-Einstellungen wird sowohl von CMakePresets.json als auch von CMakeUserPresets.json unterstützt.

Die Optionen in der Anbieterzuordnung für Visual Studio-Einstellungen wirken sich nicht auf die Konstruktion der CMake- oder CTest-Befehlszeile aus. Dadurch wird sichergestellt, dass dieselbe CMakePresets.json-Datei zum Steuern von CMake mit Visual Studio, Visual Studio Code und von der Befehlszeile aus verwendet werden kann. Die einzigen Ausnahmen sind die Optionen cacheRoot und cmakeGenerateCommand. Diese Optionen gelten speziell für das Szenario Öffnen von vorhandenem Cache in Visual Studio und können nicht von der Befehlszeile aus reproduziert werden.

Einstellung Beschreibung
hostOS Dies ist ein Array unterstützter Betriebssysteme (OS). Zulässige Werte sind Windows, Linux und macOS.

Der Wert hostOS wird von Visual Studio und Visual Studio Code verwendet, um Konfigurationsvoreinstellungen auszublenden, die nicht für das Betriebssystem des Zielsystems gelten, und dadurch die Benutzerfreundlichkeit zu verbessern.

Wenn hostOS nicht angegeben wird, zeigen Visual Studio und Visual Studio Code immer alle Konfigurationsvoreinstellungen zur Auswahl an. Für dieses Feld kann auch eine Zeichenfolge angegeben werden, die einem Array mit einer Zeichenfolge entspricht.

Diese Option wird sowohl von Visual Studio als auch von Visual Studio Code unterstützt.
intelliSenseMode Diese Einstellung gibt den Modus, der zum Berechnen von IntelliSense-Informationen in Visual Studio verwendet wird, im Format <target>-<toolset>-<arch> an.

Zulässige Werte:

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

Wenn intelliSenseMode nicht angegeben wird, verwendet Visual Studio den IntelliSense-Modus, der mit Ihren angegebenen Compilern und der angegebenen Zielarchitektur übereinstimmt. intelliSenseMode wird häufig verwendet, um verbessertes IntelliSense für die Kreuzkompilierung bereitzustellen.

In Visual Studio 2019 müssen Sie für die Builderstellung mit clang oder clang-cl explizit einen Clang-IntelliSense-Modus angeben.
intelliSenseOptions Dies ist eine Zuordnung zusätzlicher IntelliSense-Konfigurationsoptionen.

useCompilerDefaults: A bool that specifies whether to use the compiler default defines and include paths for IntelliSense. Es sollte nur false ausgewählt werden, wenn die verwendeten Compiler keine gcc-Argumente unterstützen. Wird standardmäßig auf true festgelegt.

additionalCompilerArgs: Dies ist ein Array zusätzlicher Optionen zum Steuern von IntelliSense in Visual Studio. Diese Option unterstützt die Makroerweiterung.
enableMicrosoftCodeAnalysis Mit diesem bool-Wert wird die Microsoft-Codeanalyse in Visual Studio aktiviert, wenn die Builderstellung mit cl oder clang-cl erfolgt. Wird standardmäßig auf false festgelegt.
codeAnalysisRuleset Diese Einstellung gibt den Regelsatz an, der beim Ausführen der Microsoft-Codeanalyse in Visual Studio verwendet werden soll. Sie können einen Pfad zu einer Regelsatzdatei oder den Namen einer Regelsatzdatei verwenden, die mit Visual Studio installiert wurde. Diese Option unterstützt die Makroerweiterung.
disableExternalAnalysis Dies ist ein bool-Wert, der angibt, ob die Codeanalyse auf externen Headern in Visual Studio ausgeführt werden soll.
codeAnalysisExternalRuleset Diese Einstellung gibt den Regelsatz an, der beim Ausführen der Microsoft-Codeanalyse auf externen Headern in Visual Studio verwendet werden soll. Sie können einen Pfad zu einer Regelsatzdatei oder den Namen einer Regelsatzdatei verwenden, die mit Visual Studio installiert wurde. Diese Option unterstützt die Makroerweiterung.
enableClangTidyCodeAnalysis Dies ist ein boolescher Wert, der die Clang-Tidy-Codeanalyse in Visual Studio aktiviert, wenn die Builderstellung mit clang-cl erfolgt. Wird standardmäßig auf false festgelegt.
clangTidyChecks Dies ist eine durch Trennzeichen getrennte Liste von Warnungen, die beim Ausführen der Clang-Tidy-Codeanalyse in Visual Studio an Clang-Tidy übergeben werden. Platzhalter sind zulässig, und durch das Präfix - werden Überprüfungen entfernt.
cacheRoot Diese Einstellung gibt den Pfad zu einem CMake-Cache an. Dieses Verzeichnis sollte eine vorhandene CMakeCache.txt-Datei enthalten. Dieser Schlüssel wird nur vom Szenario zum Öffnen von vorhandenem Cache in Visual Studio unterstützt. Diese Option unterstützt die Makroerweiterung.
cmakeGenerateCommand Dies ist ein Befehlszeilentool (angegeben als Befehlszeilenprogramm und Argumente, z. B. gencache.bat debug) zum Generieren des CMake-Caches. Dieser Befehl wird in der Shell mithilfe der angegebenen Umgebung der Voreinstellung ausgeführt, wenn die CMake-Konfiguration aufgerufen wird. Dieser Schlüssel wird nur vom Szenario zum Öffnen von vorhandenem Cache in Visual Studio unterstützt. Diese Option unterstützt die Makroerweiterung.

Anbieterzuordnung für Visual Studio-Remoteeinstellungen

Pro Konfigurationsvoreinstellung ist eine Anbieterzuordnung mit dem Anbieter-URI microsoft.com/VisualStudioRemoteSettings/CMake/<version> zulässig. Diese enthält spezifische Optionen für die Remoteentwicklung in Visual Studio. Remoteentwicklung bedeutet, dass Sie CMake über eine SSH-Remoteverbindung oder WSL aufrufen. Keine der Optionen in der Anbieterzuordnung für Visual Studio-Remoteeinstellungen gilt für Visual Studio Code.

Alle Einstellungen in der Anbieterzuordnung für Visual Studio-Remoteeinstellungen sind optional und werden von den vom inherits-Schlüssel angegebenen Konfigurationsvoreinstellungen geerbt. Nur geänderte Optionen werden in die Datei geschrieben. Die Anbieterzuordnung für Visual Studio-Remoteeinstellungen wird sowohl von CMakePresets.json als auch von CMakeUserPresets.json unterstützt.

Die Optionen in der Anbieterzuordnung für Visual Studio-Einstellungen wirken sich nicht auf die Konstruktion der CMake- oder CTest-Befehlszeile aus. Dadurch wird sichergestellt, dass dieselbe CMakePresets.json-Datei zum Steuern von CMake mit Visual Studio, Visual Studio Code und von der Befehlszeile aus verwendet werden kann.

Viele der Optionen in der Anbieterzuordnung für Visual Studio-Remoteeinstellungen werden ignoriert, wenn WSL1 als Ziel verwendet wird. Dies liegt daran, dass das WSL1-Toolset alle Befehle lokal ausführt und Windows-Laufwerke verwendet, die unter dem Ordner /mnt eingebunden werden, um von WSL1 aus auf lokale Quelldateien zuzugreifen. Es ist kein Kopieren der Quelldatei erforderlich. Optionen, die ignoriert werden, wenn WSL1 als Ziel verwendet wird, wurden explizit gekennzeichnet.

Einstellung Beschreibung
sourceDir Dies ist der Pfad zum Verzeichnis auf dem Remotesystem, in das das Projekt kopiert wird. Wird standardmäßig auf $env{HOME}/.vs/$ms{projectDirName} festgelegt. Diese Option unterstützt die Makroerweiterung.

In Remotekopierszenarios gibt das Makro ${sourceDir} das Projektquellenverzeichnis auf dem Remotesystem an und nicht das Projektquellenverzeichnis auf dem Windows-Computer. Remotekopierszenarios umfassen das Festlegen einer SSH-Remoteverbindung als Ziel. In diesen Fällen wird das Projektquellenverzeichnis auf dem Remotesystem durch den Wert von sourceDir in der Anbieterzuordnung für Visual Studio-Remoteeinstellungen bestimmt. Diese Option wird ignoriert, wenn WSL1 als Ziel verwendet wird.
copySources Wenn true festgelegt ist, kopiert Visual Studio Quellen von Windows in das Remotesystem. Legen Sie false fest, wenn Sie die Dateisynchronisierung selbst verwalten. Wird standardmäßig auf true festgelegt. Diese Option wird ignoriert, wenn WSL1 als Ziel verwendet wird.
copySourcesOptions Dies ist ein Objekt von Optionen, die im Zusammenhang mit dem Kopiervorgang der Quelle von Windows in das Remotesystem stehen. Dieses Objekt wird ignoriert, wenn WSL1 als Ziel verwendet wird.

copySourcesOptions.exclusionList: Dies ist eine Liste von Pfaden, die ausgeschlossen werden, wenn Quelldateien in das Remotesystem kopiert werden. Ein Pfad kann der Name einer Datei oder eines Verzeichnisses oder ein relativer Pfad vom Stamm der Kopie sein. Wird standardmäßig auf [ ".vs", ".git", "out" ] festgelegt. Diese Option unterstützt die Makroerweiterung.

copySourcesOptions.method: Dies ist die Methode, die zum Kopieren von Quelldateien in das Remotesystem verwendet wird. Zulässige Werte sind rsync und sftp. Wird standardmäßig auf rsync festgelegt.

copySourcesOptions.concurrentCopies: Dies ist die Anzahl gleichzeitiger Kopiervorgänge, die während der Synchronisierung von Quellen mit dem Remotesystem ausgeführt werden. Wird standardmäßig auf 5 festgelegt.

copySourcesOptions.outputVerbosity: Dies ist der Ausführlichkeitsgrad der Kopiervorgänge von Quellen in das Remotesystem. Zulässige Grade sind Normal, Verbose und Diagnostic. Wird standardmäßig auf Normal festgelegt.
rsyncCommandArgs Hierbei handelt es sich um Befehlszeilenargumente, die an rsync übergeben werden. Wird standardmäßig auf [ "-t", "--delete", "--delete-excluded" ] festgelegt. Diese Option unterstützt die Makroerweiterung und wird ignoriert, wenn WSL1 als Ziel verwendet wird.
copyBuildOutput Sie gibt an, ob die Buildausgabe vom Remotesystem zurück zu Windows kopiert werden soll. Wird standardmäßig auf false festgelegt. Diese Option wird ignoriert, wenn WSL1 als Ziel verwendet wird.
copyOptimizations Dies ist ein Objekt aus Optionen im Zusammenhang mit Optimierungen von Quellkopiervorgängen. Diese Optionen werden ignoriert, wenn WSL1 als Ziel verwendet wird.

copyOptimizations.maxSmallChange: Dies ist die maximale Anzahl von Dateien, die mithilfe von sftp anstelle von rsync kopiert werden sollen. Der Standardwert ist 10.

copyOptimizations.useOptimizations: Diese Option gibt die verwendeten Kopieroptimierungen an. Zulässige Werte sind keine Kopieroptimierungen (None), nur rsync-Optimierungen (RsyncOnly) oder rsync- und sftp-Optimierungen (RsyncAndSftp). Wird standardmäßig auf RsyncAndSftp festgelegt.

copyOptimizations.rsyncSingleDirectoryCommandArgs: Dies ist eine Liste mit Befehlszeilenargumenten, die an rsync übergeben werden, wenn der Inhalt eines einzelnen Verzeichnisses in das Remotesystem kopiert wird. Wird standardmäßig auf [ "-t", "-d" ] festgelegt. Diese Option unterstützt die Makroerweiterung.
copyAdditionalIncludeDirectoriesList Dies ist eine Liste mit Pfaden zu Remoteheaderverzeichnissen, die lokal für IntelliSense kopiert werden sollen. Diese Option unterstützt die Makroerweiterung.
copyExcludeDirectoriesList Dies ist eine Liste mit Pfaden zu Remoteheaderverzeichnissen, die nicht lokal für IntelliSense kopiert werden sollen. Diese Option unterstützt die Makroerweiterung.
forceWSL1Toolset Wenn true festgelegt ist, verwendet Visual Studio immer das WSL1-Toolset, wenn WSL von Visual Studio als Ziel verwendet wird. Das WSL1-Toolset führt alle Befehle lokal aus und verwendet Windows-Laufwerke, die unter dem Ordner /mnt bereitgestellt werden, um von WSL aus auf lokale Quelldateien zuzugreifen. Diese Optionen sind mit WSL2 möglicherweise langsamer. Wird standardmäßig auf false festgelegt.

Das WSL1-Toolset wird immer in Version 16.10 von Visual Studio 2019 verwendet. Diese Option ist relevant, sobald die native Unterstützung für WSL2 verfügbar ist.

Remote-Prä- und -Postbuildereignisse

Optionen für remotePrebuildEvent und remotePostbuildEvent gelten seit der Einführung von CMakePresets.json als veraltet.

Codieren Sie Präbuild-, Prälink- und Postbuildereignisse in der CMakeLists.txt mithilfe von add_custom_command. Dadurch wird beim Erstellen mit Visual Studio und der Befehlszeile das gleiche Verhalten sichergestellt.

Wenn Sie ein spezifisches Verhalten für Visual Studio erreichen möchten, können Sie in tasks.vs.json einen benutzerdefinierten Remotetask hinzufügen. Klicken Sie zum Einstieg in der Ordneransicht im Projektmappen-Explorer mit der rechten Maustaste auf die Stammdatei CMakeLists.txt, und wählen Sie Tasks konfigurieren aus. Anschließend können Sie der Datei tasks.vs.jsoneinen neuen Remotetask hinzufügen.

Der folgende Remotetask erstellt ein Verzeichnis namens „test“ auf dem Linux-Remotesystem:

{
      "taskLabel": "mkdir",
      "appliesTo": "CMakeLists.txt",
      "type": "remote",
      "command": "mkdir test",
      "remoteMachineName": "localhost"
  }

Klicken Sie mit der rechten Maustaste auf eine beliebige CMakeLists.txt-Datei, und wählen Sie die Option mkdir aus, um diesen Task auszuführen.

Der Wert von remoteMachineName muss mit dem Hostnamen einer Verbindung im Verbindungs-Manager übereinstimmen.

Microsoft-Anbietermakros

Die beiden Microsoft-Anbieterzuordnungen Visual Studio Settings und Visual Studio Remote Settings unterstützen alle von CMake definierten Makros. Unsere Anbieterzuordnungen unterstützen alle von CMake definierten Makros. Weitere Informationen finden Sie in der Makroerweiterung zu CMake-Voreinstellungen. Alle Makros und Umgebungsvariablen werden erweitert, bevor sie an CMake übergeben werden.

Visual Studio unterstützt Anbietermakros mit dem Präfix ms. Microsoft-Anbietermakros können nur in Microsoft-Anbieterzuordnungen verwendet werden. CMake kann keine Voreinstellungen verwenden, die über Anbietermakros außerhalb einer Anbieterzuordnung verfügen.

Makro Beschreibung
$ms{projectDirName} Dieses Makro gibt den Namen des geöffneten Ordners in Visual Studio an. Dieses Makro wird verwendet, um den Standardwert von sourceDir in Remotekopierszenarios festzulegen. Dieses Makro wird von Visual Studio Code nicht unterstützt. Verwenden Sie stattdessen ${sourceDirName}.

Umgebungsvariablen

Makro Beschreibung
$env{<variable-name>}
$penv{<variable-name>}		 Verweisen Sie mithilfe dieser von CMake unterstützten Syntax auf Umgebungsvariablen. Weitere Informationen finden Sie in der Makroerweiterung zu CMake-Voreinstellungen.

Veraltete Makros

Einige Makros, die von CMakeSettings.json unterstützt wurden, gelten seit der Einführung von CMakePresets.json als veraltet.

Verwenden Sie die von CMake unterstützten Makros, um Ihre Dateipfade zu erstellen. Dadurch wird beim Verwenden der Makros sichergestellt, dass dieselbe CMakePresets.json-Datei in Visual Studio und über die Befehlszeile verwendet werden kann.

Veraltetes Makro Empfehlung
${projectFile} ${sourceDir}/CMakeLists.txt
${thisFile} ${sourceDir}/CMakePresets.json

Zulässige Shellsyntax

Verwenden Sie die Syntax $env{HOME}, um beim Erstellen von Linux-Pfaden in den Microsoft-Anbieterzuordnungen auf $HOME zu verweisen.