CMakeSettings.json Referenční dokumentace schématu

Projekty CMake jsou podporovány v aplikaci 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 zadanou konfiguraci a prostředí 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. V souborech CMakeLists.txt lze hodnoty 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. Na Linuxu zkompilujte s -fno-omit-frame-pointer a s úrovní optimalizace kompilátoru -Os 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: Specifikuje nativní parametry sestavení předávané do CMake po --build --. Předání například -v při použití generátoru Ninja přinutí Ninja k výpisu příkazových řádků. 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ří , , , ${workspaceRoot}${workspaceHash}${projectFile}${projectDir}${thisFile}, ${thisFileDir}, . ${name}${generator}${env.VARIABLE}

  • 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í ze shellu v zadaném prostředí pro konfiguraci, když uživatel explicitně požádá o regeneraci nebo se upraví soubor CMakeLists.txt nebo 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é znaky 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ů. Je předáno 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 zobrazuje 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 rychlost sestavení namísto flexibility a funkčnosti, je nastaven 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, klikněte pravým tlačítkem myši na soubor v Průzkumník řešení a zvolte Nastavení CMake pro projektZobrazit Pokročilá nastaveníGenerátor CMake.

Ve výchozím nastavení, když aktivní konfigurace určuje generátor Visual Studio, vyvolá 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ří , , , ${workspaceRoot}${workspaceHash}${projectFile}${projectDir}${thisFile}, ${thisFileDir}, . ${name}${generator}${env.VARIABLE}

  • 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žitý pro výpočet informací 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 Windows Subsystem for Linux.

Nastavení pro projekty CMake Linux

  • remoteMachineName: Určuje název vzdáleného počítače s Linuxem, který hostuje CMake, procesy sestavení a debugger. 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ří ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator} a ${env.VARIABLE}.
  • 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ří , , , ${workspaceRoot}${workspaceHash}${projectFile}${projectDir}${thisFile}, ${thisFileDir}, . ${name}${generator}${env.VARIABLE}
  • 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}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator} 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 zahrnující soubory, které se mají zkopírovat ze vzdáleného počítače pro podporu 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, zda se mají použít výchozí definice a zahrnout cesty kompilátoru pro IntelliSense. Měla by být false pouze v případě, že kompilátory, které se používají, nepodporují 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é znaky * a ? lze použít pro srovnávání vzorů pomocí globu.
  • 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í sestavovacích nástrojů MSVC verze 14.14.26428:
"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 nedefinujete "type", předpokládá se typ "STRING" ve výchozím nastavení.

  • 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. Například, prostředí je stejné jako spuštění příkazového řádku pro vývojáře pro VS {version} s argumenty -arch=amd64 -host_arch=amd64. Syntaxi env.{<variable_name>} můžete použít CMakeSettings.json 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: Cílit na ARM Linux vzdáleně.
  • linux_x64: Vzdálené cílení na x64 Linux.
  • linux_x86: Cílit vzdáleně na x86 Linux.
  • msvc_arm: Zacílit na Windows ARM s kompilátorem MSVC.
  • msvc_arm_x64: Zaměřte se na ARM Windows 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: Windows pro ARM64EC s kompilátorem MSVC.
  • msvc_arm64ec_x64: Cílové Windows systém ARM64EC s 64-bitový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: Zamířit na 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 proměnných systémové introspekce CMake, ale může být 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í se nazývá env a obsahuje určité systémové proměnné prostředí, včetně %USERPROFILE%.
  • environment: Jednoznačně identifikuje tuto skupinu proměnných. Umožňuje, aby skupina byla později zděděna v položce inheritEnvironments.
  • 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ílové objekty pro ladění se automaticky spustí s prostředím, které zadáte CMakeSettings.json. Můžete přepsat nebo přidat proměnné prostředí na základě konkrétního cíle nebo úkolu v launch.vs.json 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í vlastností BuildDir, takže BuildRoot se vyhodnotí 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} – hash umístění pracovního prostoru; užitečné pro vytvoření jedinečného identifikátoru pro současný 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

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

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 verze Ninja ("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 Testovací spuštění (nespouštět příkazy, ale předstírat, že byly ú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 základní možnosti; nástroji se předají další parametry.
-w FLAG Úprava upozornění (použití -w list k zobrazení seznamu upozornění)
  • Last updated on