`CMakeSettings.json` Referenční dokumentace schématu

Článek
10/12/2023

Projekty CMake se podporují v sadě Visual Studio 2017 a novějších verzích.

Soubor CMakeSettings.json obsahuje informace, které Sada Visual Studio používá pro IntelliSense, a k vytvoření argumentů příkazového řádku, které předává CMake pro zadané prostředí konfigurace a kompilátoru. Konfigurace určuje vlastnosti, které se vztahují na konkrétní platformu a typ sestavení, x86-Debug například nebo Linux-Release. Každá konfigurace určuje prostředí, které zapouzdřuje informace o sadě nástrojů kompilátoru, například MSVC, GCC nebo Clang. CMake používá argumenty příkazového řádku k opětovnému vygenerování kořenového CMakeCache.txt souboru a dalších souborů projektu pro projekt. Hodnoty lze v souborech CMakeLists.txt přepsat.

V integrovaném vývojovém prostředí můžete přidat nebo odebrat konfigurace a pak je upravit přímo v souboru JSON nebo použít editor nastavení CMake (Visual Studio 2019 a novější). Mezi konfiguracemi v integrovaném vývojovém prostředí (IDE) můžete snadno přepínat a vygenerovat různé soubory projektu. Další informace najdete v tématu Přizpůsobení nastavení sestavení CMake v sadě Visual Studio.

Konfigurace

Pole configurations obsahuje všechny konfigurace projektu CMake. Další informace o předdefinovaných konfiguracích najdete v referenčních informacích k předdefinovaným konfiguracím CMake. Do souboru můžete přidat libovolný počet předem definovaných nebo vlastních konfigurací.

A configuration má tyto vlastnosti:

addressSanitizerEnabled: Pokud true, kompiluje program pomocí AddressSanitizer. V Linuxu zkompilujte úroveň -Os optimalizace kompilátoru -fno-omit-frame-pointer nebo -Oo pro zajištění nejlepších výsledků.
addressSanitizerRuntimeFlags: Příznaky modulu runtime předané AddressSanitizer v ASAN_OPTIONS proměnné prostředí. Formát: flag1=value:flag2=value2.
buildCommandArgs: Určuje nativní přepínače sestavení předané CMake po --build --. Předání například -v při použití generátoru Ninja vynutí Ninja výstup příkazové řádky. Další informace o příkazech Ninja naleznete v části Argumenty příkazového řádku Ninja.
buildRoot: Určuje adresář, ve kterém CMake generuje skripty sestavení pro zvolený generátor. Mapuje pro -DCMAKE_BINARY_DIR přepnutí a určuje, kde CMakeCache.txt se vytvoří. Pokud složka neexistuje, vytvoří se. Mezi podporovaná makra patří , , , ${thisFile}${name}${projectDir}${projectFile}${thisFileDir}, ${generator}, . ${env.VARIABLE}${workspaceHash}${workspaceRoot}
cacheGenerationCommand: Určuje nástroj příkazového řádku a argumenty, například gencache.bat debug pro vygenerování mezipaměti. Příkaz se spustí z prostředí v zadaném prostředí pro konfiguraci, když uživatel explicitně požádá o regeneraci nebo CMakeLists.txt se upraví soubor CMakeSettings.json .
cacheRoot: Určuje cestu k mezipaměti CMake. Tento adresář by měl obsahovat existující CMakeCache.txt soubor.
clangTidyChecks: čárkami oddělený seznam upozornění, která se předají clang-tidy; Zástupné kóty jsou povolené a předpona -odebere kontroly.
cmakeCommandArgs: Určuje všechny další možnosti příkazového řádku, které se mají předat CMake při vyvolání pro vygenerování souborů projektu.
cmakeToolchain: Určuje soubor sady nástrojů. Předá se CMake pomocí -DCMAKE_TOOLCHAIN_FILE.
codeAnalysisRuleset: Určuje sadu pravidel, která se má použít při spouštění analýzy kódu. Můžete použít úplnou cestu nebo název souboru sady pravidel nainstalovaný v sadě Visual Studio.
configurationType: Určuje konfiguraci typu sestavení pro vybraný generátor. Může to být jedna z těchto možností:
- Debug
- Release
- MinSizeRel
- RelWithDebInfo
ctestCommandArgs: Určuje všechny další možnosti příkazového řádku, které se mají předat CTest při spuštění testů.
description: Popis této konfigurace, která se zobrazí v nabídkách.
enableClangTidyCodeAnalysis: Pro analýzu kódu použijte Clang-Tidy.
enableMicrosoftCodeAnalysis: Použijte nástroje microsoftu pro analýzu kódu pro analýzu kódu.
generator: Určuje generátor CMake, který se má použít pro tuto konfiguraci. Může to být jedna z těchto možností:

Jenom Visual Studio 2019:
- Visual Studio 16 2019
- Visual Studio 16 2019 Win64
- Visual Studio 16 2019 ARM
Visual Studio 2017 a novější:
- 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

Protože Ninja je navržen pro rychlé rychlosti sestavení místo flexibility a funkce, je nastavena jako výchozí. Některé projekty CMake ale nemusí být schopny správně sestavovat pomocí Ninja. Pokud dojde k selhání sestavení, můžete dát CMake pokyn, aby místo toho vygeneroval projekty sady Visual Studio.

Pokud chcete zadat generátor sady Visual Studio v sadě Visual Studio 2017, otevřete editor nastavení z hlavní nabídky výběrem CMake | Změňte nastavení CMake. Odstraňte "Ninja" a zadejte "V". Tato změna aktivuje Technologii IntelliSense, která umožňuje zvolit požadovaný generátor.

Pokud chcete v sadě Visual Studio 2019 zadat generátor sady Visual Studio, klikněte pravým tlačítkem myši na CMakeLists.txt soubor v Průzkumník řešení a zvolte Nastavení CMake pro projekt>Zobrazit generátor CMake Advanced Settings.>

Ve výchozím nastavení, když aktivní konfigurace určuje generátor sady Visual Studio, vyvolá NÁSTROJ MSBuild s -m -v:minimal argumenty. K přizpůsobení sestavení použijte buildCommandArgs vlastnost uvnitř CMakeSettings.json souboru. Tady můžete zadat argumenty příkazového řádku MSBuild, které se předávají do systému sestavení:

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

installRoot: Určuje adresář, ve kterém CMake generuje cíle instalace pro zvolený generátor. Mezi podporovaná makra patří , , , ${thisFile}${name}${projectDir}${projectFile}${thisFileDir}, ${generator}, . ${env.VARIABLE}${workspaceHash}${workspaceRoot}
inheritEnvironments: Určuje jedno nebo více prostředí kompilátoru, na které tato konfigurace závisí. Může to být jakékoli vlastní prostředí nebo jedno z předdefinovaných prostředí. Další informace naleznete v tématu Prostředí.
intelliSenseMode: Určuje režim používaný pro výpočetní informace technologie IntelliSense. Hodnota může být jedna z těchto hodnot:
- 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: pojmenuje konfiguraci. Další informace o předdefinovaných konfiguracích najdete v referenčních informacích k předdefinovaným konfiguracím CMake.
wslPath: cesta ke spouštěči instance Subsystém Windows pro Linux.

Nastavení pro projekty CMake Linux

remoteMachineName: Určuje název vzdáleného počítače s Linuxem, který hostuje CMake, sestavení a ladicí program. K přidání nových počítačů s Linuxem použijte Správce připojení. Mezi podporovaná makra patří ${defaultRemoteMachineName}.
remoteCopySourcesOutputVerbosity: Určuje úroveň podrobností operace kopírování zdroje do vzdáleného počítače. Může být jedním z Normal, Verbosenebo Diagnostic.
remoteCopySourcesConcurrentCopies: Určuje souběžné kopie, které se mají použít při synchronizaci zdrojů do vzdáleného počítače (pouze sftp).
remoteCopySourcesMethod: Určuje metodu kopírování souborů do vzdáleného počítače. Může být rsync nebo sftp.
remoteCMakeListsRoot: Určuje adresář na vzdáleném počítači, který obsahuje projekt CMake. Mezi podporovaná makra patří , , , ${thisFile}${thisFileDir}${projectDir}${generator}${name}${projectFile}, a .${env.VARIABLE}${workspaceHash}${workspaceRoot}
remoteBuildRoot: Určuje adresář na vzdáleném počítači, ve kterém CMake generuje skripty sestavení pro zvolený generátor. Mezi podporovaná makra patří , , , ${thisFile}${name}${projectDir}${projectFile}${thisFileDir}, ${generator}, . ${env.VARIABLE}${workspaceHash}${workspaceRoot}
remoteInstallRoot: Určuje adresář na vzdáleném počítači, ve kterém CMake generuje cíle instalace pro zvolený generátor. Podporovaná makra zahrnují ${workspaceRoot}, ${workspaceHash}, , , ${thisFile}${name}${projectFile}${thisFileDir}${generator}${projectDir}a ${env.VARIABLE}, kde VARIABLE je proměnná prostředí definovaná na úrovni systému, uživatele nebo relace.
remoteCopySources: Určuje boolean , zda má visual Studio kopírovat zdrojové soubory do vzdáleného počítače. Výchozí hodnota je true. Pokud spravujete synchronizaci souborů sami, nastavte na hodnotu false.
remoteCopyBuildOutput: Určuje boolean , zda se mají kopírovat výstupy sestavení ze vzdáleného systému.
remoteCopyAdditionalIncludeDirectories: Další adresáře, které se mají zkopírovat ze vzdáleného počítače pro podporu Technologie IntelliSense. Formátovat jako /path1;/path2...".
remoteCopyExcludeDirectories: Zahrňte adresáře, které se nemají kopírovat ze vzdáleného počítače. Formátovat jako /path1;/path2...".
remoteCopyUseCompilerDefaults: Určuje, jestli se má výchozí definice kompilátoru definovat a zahrnout cesty pro IntelliSense. Měla by být false pouze v případě, že kompilátory, které se používají k tomu, aby nepodněly argumenty ve stylu gcc.
rsyncCommandArgs: Určuje sadu možností příkazového řádku předaných rsync.
remoteCopySourcesExclusionList: Určuje array seznam cest, které mají být vyloučeny při kopírování zdrojových souborů: cesta může být název souboru nebo adresáře nebo relativní cesta z kořenového adresáře kopie. Zástupné cardy * a ? lze je použít pro porovnávání vzorů globů.
cmakeExecutable: Určuje úplnou cestu ke spustitelnému souboru CMake, včetně názvu a přípony souboru.
remotePreGenerateCommand: Určuje příkaz, který se má spustit před spuštěním CMake pro parsování CMakeLists.txt souboru.
remotePrebuildCommand: Určuje příkaz, který se má spustit na vzdáleném počítači před sestavením.
remotePostbuildCommand: Určuje příkaz, který se má spustit na vzdáleném počítači po sestavení.
variables: Obsahuje dvojici name-value proměnných CMake, které se předávají jako -D name=value CMake. Pokud pokyny k sestavení projektu CMake určují přidání všech proměnných přímo do CMakeCache.txt souboru, doporučujeme je sem přidat. Tento příklad ukazuje, jak určit páry název-hodnota pro použití sady nástrojů 14.14.26428 MSVC:

"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"
    }
  ]

Pokud ho nedefinujete "type", předpokládá se "STRING" ve výchozím nastavení typ.

remoteCopyOptimizations: Visual Studio 2019 verze 16.5 nebo novější vlastnosti pro řízení kopírování zdroje do vzdáleného cíle. Optimalizace jsou ve výchozím nastavení povolené. Zahrnuje remoteCopyUseOptimizations, rsyncSingleDirectoryCommandArgsa remoteCopySourcesMaxSmallChange.

Prostředí

Prostředí zapouzdřuje proměnné prostředí nastavené v procesu, který Visual Studio používá k vyvolání CMake. V případě projektů MSVC zachycuje proměnné nastavené v příkazovém řádku pro vývojáře pro konkrétní platformu. Prostředí je například stejné jako msvc_x64_x64 spuštění příkazového řádku pro vývojáře pro VS {version} s argumenty -arch=amd64 -host_arch=amd64 . Syntaxi CMakeSettings.json můžete použít env.{<variable_name>} k odkazování na jednotlivé proměnné prostředí, například k vytvoření cest ke složkám. K dispozici jsou následující předdefinovaná prostředí:

linux_arm: Vzdáleně zaměřte LINUX na ARM.
linux_x64: Vzdáleně cílí na platformu x64 Linux.
linux_x86: Vzdáleně cílí na platformu x86 Linux.
msvc_arm: Cílová okna ARM s kompilátorem MSVC.
msvc_arm_x64: Cílová okna ARM s 64bitovým kompilátorem MSVC.
msvc_arm64: Cílový systém Windows ARM64 s kompilátorem MSVC.
msvc_arm64_x64: Cílový systém Windows ARM64 s 64bitovým kompilátorem MSVC.
msvc_arm64ec: Cílová ARM64EC Windows s kompilátorem MSVC.
msvc_arm64ec_x64: Cílová ARM64EC Windows s 64bitovým kompilátorem MSVC.
msvc_x64: Cíl x64 Windows pomocí kompilátoru MSVC.
msvc_x64_x64: Cílení na systém Windows x64 pomocí 64bitového kompilátoru MSVC.
msvc_x86: Cíl x86 Windows pomocí kompilátoru MSVC.
msvc_x86_x64: Cíl x86 Windows s 64bitovým kompilátorem MSVC.

Přístup k proměnným prostředí z `CMakeLists.txt`

CMakeLists.txt Ze souboru jsou všechny proměnné prostředí odkazovány syntaxí $ENV{variable_name}. Pokud chcete zobrazit dostupné proměnné pro prostředí, otevřete odpovídající příkazový řádek a zadejte SET. Některé informace v proměnných prostředí jsou k dispozici také prostřednictvím systémových introspekcí CMake, ale možná je vhodnější použít proměnnou prostředí. Můžete například snadno načíst verzi kompilátoru MSVC nebo verzi sady Windows SDK prostřednictvím proměnných prostředí.

Vlastní proměnné prostředí

V CMakeSettings.jsonpoli můžete definovat vlastní proměnné prostředí globálně nebo podle konfigurace v environments poli. Vlastní prostředí je pohodlný způsob, jak seskupit sadu vlastností. Můžete ho použít místo předdefinovaného prostředí nebo rozšířit nebo upravit předdefinované prostředí. Každá položka v environments poli se skládá z:

namespace: Pojmenuje prostředí tak, aby na jeho proměnné bylo možné odkazovat z konfigurace ve formuláři namespace.variable. Výchozí objekt prostředí je volána env a je naplněna určitými systémovými proměnnými prostředí, včetně %USERPROFILE%.
environment: Jednoznačně identifikuje tuto skupinu proměnných. Umožňuje, aby se skupina zdědila později v inheritEnvironments položce.
groupPriority: Celé číslo, které určuje prioritu těchto proměnných při vyhodnocování. Položky s vyšším číslem se vyhodnocují jako první.
inheritEnvironments: Pole hodnot, které určují sadu prostředí, která jsou zděděna touto skupinou. Tato funkce umožňuje dědit výchozí prostředí a vytvářet vlastní proměnné prostředí, které se při spuštění předávají CMake.

Visual Studio 2019 verze 16.4 a novější: Cíle ladění se automaticky spustí s prostředím, ve CMakeSettings.jsonkterém jste zadali . Proměnné prostředí můžete přepsat nebo přidat v rámci cíle nebo úkolu na launch.vs.json základě a tasks.vs.json.

Následující příklad definuje jednu globální proměnnou, BuildDirkterá je zděděna v konfiguraci x86-Debug i x64-Debug. Každá konfigurace používá proměnnou k určení hodnoty vlastnosti pro danou buildRoot konfiguraci. Všimněte si také, jak každá konfigurace používá inheritEnvironments vlastnost k určení proměnné, která se vztahuje pouze na tuto konfiguraci.

{
  // 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}"
    }
  ]
}

V dalším příkladu definuje konfigurace x86-Debug vlastní hodnotu pro BuildDir vlastnost. Tato hodnota přepíše hodnotu nastavenou globální BuildDir vlastnost, aby BuildRoot vyhodnocen jako D:\custom-builddir\x86-Debug.

{
  "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}"
    }
  ]
}

Makra

Následující makra lze použít v CMakeSettings.json:

${workspaceRoot} – úplná cesta ke složce pracovního prostoru
${workspaceHash} – hodnota hash umístění pracovního prostoru; Užitečné pro vytvoření jedinečného identifikátoru pro aktuální pracovní prostor (například pro použití v cestách ke složkám)
${projectFile} – úplná cesta kořenového CMakeLists.txt souboru
${projectDir} – úplná cesta ke složce obsahující kořenový CMakeLists.txt soubor.
${projectDirName} – název složky obsahující kořenový CMakeLists.txt soubor
${thisFile} – úplná cesta k CMakeSettings.json souboru
${name} – název konfigurace
${generator} – název generátoru CMake použitého v této konfiguraci

Před předáním do příkazového řádku CMake se rozbalí všechny odkazy na makra a proměnné CMakeSettings.json prostředí.

Argumenty příkazového řádku Ninja

Pokud cíle nejsou zadané, Ninja sestaví výchozí cíl.

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

Možnost	Popis
`--version`	Tisk ninja verze ("1.7.1")
`-C DIR`	Před provedením čehokoli jiného změňte na DIR.
`-f FILE`	Zadání vstupního souboru sestavení (default=`build.ninja`)
`-j N`	Paralelní spouštění `N` úloh (default=14, odvozené z dostupných procesorů)
`-k N`	Pokračujte, dokud `N` úlohy selžou (default=1)
`-l N`	Nespouštět nové úlohy, pokud je průměr zatížení větší než `N`
`-n`	Suché spuštění (nespouštět příkazy, ale fungují jako úspěšné)
`-v`	Zobrazit všechny příkazové řádky při sestavování
`-d MODE`	Povolení ladění (použití `-d list` k výpisu režimů)
`-t TOOL`	Spusťte podnástroj (slouží `-t list` k výpisu podnástrojů). Ukončí všechny možnosti nejvyšší úrovně; nástroji se předají další příznaky.
`-w FLAG`	Úprava upozornění (použití `-w list` k zobrazení seznamu upozornění)

Sdílet prostřednictvím

`CMakeSettings.json` Referenční dokumentace schématu

Konfigurace

Nastavení pro projekty CMake Linux

Prostředí

Přístup k proměnným prostředí z `CMakeLists.txt`

Vlastní proměnné prostředí

Makra

Argumenty příkazového řádku Ninja

Váš názor

Další materiály

Sdílet prostřednictvím

CMakeSettings.json Referenční dokumentace schématu

Konfigurace

Nastavení pro projekty CMake Linux

Prostředí

Přístup k proměnným prostředí z CMakeLists.txt

Vlastní proměnné prostředí

Makra

Argumenty příkazového řádku Ninja

Váš názor

Další materiály

`CMakeSettings.json` Referenční dokumentace schématu

Přístup k proměnným prostředí z `CMakeLists.txt`