`CMakeSettings.json` informacje o schemacie

Artykuł
09/26/2022
Czas czytania: 11 min

Projekty CMake są obsługiwane w Visual Studio 2017 i nowszych.

Plik CMakeSettings.json zawiera informacje, które Visual Studio dla funkcji IntelliSense i konstruowania argumentów wiersza polecenia, które przekazuje do narzędzia CMake dla określonej konfiguracji i środowiska kompilatora. Konfiguracja określa właściwości, które mają zastosowanie do określonej platformy i typu kompilacji, na przykład x86-Debug lub Linux-Release. Każda konfiguracja określa środowisko, które hermetyzuje informacje dotyczące zestawu narzędzi kompilatora, na przykład MSVC, GCC lub Clang. CMake używa argumentów wiersza polecenia, aby ponownie wygenerować plik główny CMakeCache.txt i inne pliki projektu dla projektu. Wartości można przesłonić w plikach CMakeLists.txt .

Możesz dodawać lub usuwać konfiguracje w idee, a następnie edytować je bezpośrednio w pliku JSON lub użyć edytora CMake Ustawienia (program Visual Studio 2019 i nowsze). Można łatwo przełączać się między konfiguracjami w idee, aby wygenerować różne pliki projektu. Aby uzyskać więcej informacji, zobacz Dostosowywanie ustawień kompilacji CMake w Visual Studio.

Konfiguracje

Tablica configurations zawiera wszystkie konfiguracje projektu CMake. Aby uzyskać więcej informacji na temat wstępnie zdefiniowanych konfiguracji, zobacz CMake predefined configuration reference (Informacje dotyczące wstępnie zdefiniowanej konfiguracji programu CMake). Do pliku można dodać dowolną liczbę wstępnie zdefiniowanych lub niestandardowych konfiguracji.

Ma configuration następujące właściwości:

addressSanitizerEnabled: Jeśli true, program kompiluje przy użyciu narzędzia AddressSanitizer. W systemie Linux skompiluj z -fno-omit-frame-pointer poziomem optymalizacji kompilatora -Os lub w -Oo celu zachowania najlepszych wyników.
addressSanitizerRuntimeFlags: flagi środowiska uruchomieniowego przekazane do usługi AddressSanitizer w zmiennej ASAN_OPTIONS środowiskowej . Format: flag1 =value:flag2=value2.
buildCommandArgs: określa przełączniki kompilacji natywnej przekazywane do CMake po .--build -- Na przykład przekazywanie podczas korzystania -v z generatora Ninja wymusza, aby Ninja wyprowadzał wiersze poleceń. Aby uzyskać więcej informacji na temat poleceń Ninja, zobacz Argumenty wiersza polecenia Ninja.
buildRoot: określa katalog, w którym CMake generuje skrypty kompilacji dla wybranego generatora. Mapy przełącznika -DCMAKE_BINARY_DIR i określa, gdzie CMakeCache.txt jest tworzony. Jeśli folder nie istnieje, zostanie utworzony. Obsługiwane makra to ${workspaceRoot}, ${workspaceHash}, , ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.
cacheGenerationCommand: określa narzędzie wiersza polecenia i argumenty, na przykład w celu gencache.bat debug wygenerowania pamięci podręcznej. Polecenie jest uruchamiane z powłoki w CMakeLists.txt określonym środowisku dla konfiguracji, gdy użytkownik jawnie zażąda regeneruje lub plik lub CMakeSettings.json zostanie zmodyfikowany.
cacheRoot: określa ścieżkę do pamięci podręcznej CMake. Ten katalog powinien zawierać istniejący CMakeCache.txt plik.
clangTidyChecks: rozdzielana przecinkami lista ostrzeżeń przekazywanych do clang-tidy; Symbole wieloznaczne są dozwolone, a prefiks "-" usuwa kontrole.
cmakeCommandArgs: określa wszelkie dodatkowe opcje wiersza polecenia do przekazania do CMake po wywołaniu w celu wygenerowania plików projektu.
cmakeToolchain: określa plik toolchain. Jest on przekazywany do narzędzia CMake przy użyciu .-DCMAKE_TOOLCHAIN_FILE
codeAnalysisRuleset: określa zestaw reguł do użycia podczas uruchamiania analizy kodu. Możesz użyć pełnej ścieżki lub nazwy pliku zestawu reguł zainstalowanego przez program Visual Studio.
configurationType: określa konfigurację typu kompilacji dla wybranego generatora. Może być jednym z:
- Debug
- Release
- MinSizeRel
- RelWithDebInfo
ctestCommandArgs: określa wszelkie dodatkowe opcje wiersza polecenia do przekazania do CTest podczas uruchamiania testów.
description: opis tej konfiguracji, który jest wyświetlany w menu.
enableClangTidyCodeAnalysis: użyj Clang-Tidy do analizy kodu.
enableMicrosoftCodeAnalysis: użyj narzędzi firmy Microsoft do analizy kodu.
generator: określa generator CMake do użycia w tej konfiguracji. Może być jednym z:

Visual Studio 2019 r.:
- Visual Studio 16 2019
- Visual Studio 16 2019 Win64
- Visual Studio 16 2019 ARM
Visual Studio 2017 i nowsze:
- 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

Ponieważ ninja jest zaprojektowany z myślą o szybkich szybkościach kompilacji zamiast elastyczności i funkcji, jest ustawiany jako domyślny. Jednak niektóre projekty CMake mogą nie być w stanie poprawnie kompilować przy użyciu narzędzia Ninja. Jeśli wystąpi błąd kompilacji, możesz poinstruować CMake, aby zamiast Visual Studio projektów.

Aby określić generator Visual Studio w programie Visual Studio 2017, otwórz edytor ustawień z menu głównego, wybierając pozycję CMake | Zmień ustawienia CMake Ustawienia. Usuń "Ninja" i wprowadź "V". Ta zmiana aktywuje intellisense, co pozwala wybrać odpowiedni generator.

Aby określić generator Visual Studio w programie Visual Studio 2019, CMakeLists.txt kliknij prawym przyciskiem myszy plik w programie Eksplorator rozwiązań i wybierz pozycję CMake Ustawienia> dla projektuShow Advanced Ustawienia>CMake Generator.

Domyślnie, gdy aktywna konfiguracja określa Visual Studio, wywołuje ono MSBuild z argumentami-m -v:minimal. Aby dostosować kompilację, użyj właściwości buildCommandArgs wewnątrz CMakeSettings.json pliku . W tym miejscu możesz określić MSBuild wiersza polecenia do przekazania do systemu kompilacji:

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

installRoot: określa katalog, w którym CMake generuje obiekty docelowe instalacji dla wybranego generatora. Obsługiwane makra to ${workspaceRoot}, ${workspaceHash}, , ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.
inheritEnvironments: określa co najmniej jedno środowisko kompilatora, od których zależy ta konfiguracja. Może to być dowolne środowisko niestandardowe lub jedno ze wstępnie zdefiniowanych środowisk. Aby uzyskać więcej informacji, zobacz Environments (Środowiska).
intelliSenseMode: określa tryb używany do przetwarzania informacji intellisense". Wartość może być jedną z:
- 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: nazwa konfiguracji. Aby uzyskać więcej informacji na temat wstępnie zdefiniowanych konfiguracji, zobacz CMake predefined configuration reference (Informacje dotyczące wstępnie zdefiniowanej konfiguracji programu CMake).
wslPath: ścieżka do uruchamiania wystąpienia Podsystem Windows dla systemu Linux.

Ustawienia dla projektów CMake w systemie Linux

remoteMachineName: określa nazwę zdalnej maszyny z systemem Linux, która hostuje program CMake, kompilacje i debuger. Użyj Menedżer połączeń do dodawania nowych maszyn z systemem Linux. Obsługiwane makra obejmują .${defaultRemoteMachineName}
remoteCopySourcesOutputVerbosity: określa poziom szczegółowości operacji kopiowania źródła na maszynę zdalną. Może to być jeden z Normal, Verboselub Diagnostic.
remoteCopySourcesConcurrentCopies: określa współbieżne kopie do użycia podczas synchronizacji źródeł z maszyną zdalną (tylko sftp).
remoteCopySourcesMethod: określa metodę kopiowania plików na maszynę zdalną. Może to być rsync lub sftp.
remoteCMakeListsRoot: określa katalog na maszynie zdalnej, który zawiera projekt CMake. Obsługiwane makra to ${workspaceRoot}, ${workspaceHash}, ${projectFile}, , ${projectDir}, ${thisFile}, ${name}${thisFileDir}, ${generator}, i ${env.VARIABLE}.
remoteBuildRoot: określa katalog na maszynie zdalnej, w którym CMake generuje skrypty kompilacji dla wybranego generatora. Obsługiwane makra to ${workspaceRoot}, ${workspaceHash}, , ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}, ${env.VARIABLE}.
remoteInstallRoot: określa katalog na maszynie zdalnej, w którym CMake generuje obiekty docelowe instalacji dla wybranego generatora. Obsługiwane makra to ${workspaceRoot}, ${workspaceHash}, ${projectFile}, ${projectDir}, ${thisFile}, ${thisFileDir}, ${name}, ${generator}i ${env.VARIABLE}, gdzie VARIABLE jest zmienną środowiskową zdefiniowaną na poziomie systemu, użytkownika lub sesji.
remoteCopySources: określaboolean, czy Visual Studio kopiować pliki źródłowe na maszynę zdalną. Wartość domyślna to true. Jeśli samodzielnie zarządzasz synchronizacją plików, ustaw wartość false.
remoteCopyBuildOutput: Określa boolean , czy kopiować dane wyjściowe kompilacji z systemu zdalnego.
remoteCopyAdditionalIncludeDirectories: dodatkowe katalogi dołączania, które mają zostać skopiowane z komputera zdalnego w celu obsługi funkcji IntelliSense. Formatuj jako "/path1;/path2...".
remoteCopyExcludeDirectories: dołącz katalogi, które NIE mają być kopiowane z maszyny zdalnej. Formatuj jako "/path1;/path2...".
remoteCopyUseCompilerDefaults: określa, czy używać domyślnych ścieżek kompilatora do definiowania i dołączania dla funkcji IntelliSense. Powinna mieć wartość false tylko wtedy, gdy kompilatory w użyciu nie obsługują argumentów w stylu gcc.
rsyncCommandArgs: określa zestaw opcji wiersza polecenia przekazanych do rsync.
remoteCopySourcesExclusionList: element array określający listę ścieżek do wykluczenia podczas kopiowania plików źródłowych: ścieżka może być nazwą pliku/katalogu lub ścieżką względną z katalogu głównego kopii. Symbole wieloznaczne * i ? mogą być używane do dopasowywania wzorca symboli wieloznacznych.
cmakeExecutable: określa pełną ścieżkę do pliku wykonywalnego programu CMake, w tym nazwę pliku i rozszerzenie.
remotePreGenerateCommand: określa polecenie do uruchomienia przed uruchomieniem CMake w celu analizy CMakeLists.txt pliku.
remotePrebuildCommand: określa polecenie do uruchomienia na maszynie zdalnej przed rozpoczęciem tworzenia.
remotePostbuildCommand: określa polecenie do uruchomienia na maszynie zdalnej po zakończeniu tworzenia.
variables: zawiera parę nazwa-wartość zmiennych CMake, które są przekazywane jako do -D name=value CMake. Jeśli instrukcje kompilacji projektu CMake CMakeCache.txt określają dodawanie dowolnych zmiennych bezpośrednio do pliku, zalecamy dodanie ich w tym miejscu. W tym przykładzie pokazano, jak określić pary nazwa-wartość, aby użyć zestawu narzędzi 14.14.26428 MSVC narzędzi:

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

Jeśli nie zdefiniujesz "type"typu , "STRING" typ jest zakładany domyślnie.

remoteCopyOptimizations: Visual Studio 2019 w wersji 16.5 lub nowszej do kontrolowania kopii źródłowej do zdalnego obiektu docelowego. Optymalizacje są domyślnie włączone. Obejmuje remoteCopyUseOptimizationselementy , rsyncSingleDirectoryCommandArgsi remoteCopySourcesMaxSmallChange.

Środowiska

Środowisko hermetyzuje zmienne środowiskowe ustawione w procesie, który Visual Studio wywoływania CMake. W MSVC przechwytuje zmienne ustawione w wierszu polecenia dewelopera dla określonej platformy. msvc_x64_x64 Na przykład środowisko jest takie samo jak uruchamianie programu wiersz polecenia dla deweloperów dla programu VS 2017 lub wiersz polecenia dla deweloperów dla programu VS 2019 z argumentami -arch=amd64 -host_arch=amd64. Składni w programie env.{<variable_name>} można użyć do CMakeSettings.json odwołania się do poszczególnych zmiennych środowiskowych, na przykład do konstruowania ścieżek do folderów. Dostępne są następujące wstępnie zdefiniowane środowiska:

linux_arm: zdalnie przekieruj system ARM do systemu Linux.
linux_x64: zdalne kierowanie do systemu Linux x64.
linux_x86: zdalne kierowanie do systemu Linux x86.
msvc_arm: docelowe Windows ARM za pomocą MSVC kompilatora.
msvc_arm_x64: docelowa Windows ARM za pomocą 64-bitowego MSVC kompilatora.
msvc_arm64: docelowa Windows ARM64 za pomocą MSVC kompilatora.
msvc_arm64_x64: docelowa Windows ARM64 za pomocą 64-bitowego MSVC kompilatora.
msvc_arm64ec: docelowa Windows ARM64EC za pomocą MSVC kompilatora.
msvc_arm64ec_x64: docelowa Windows ARM64EC za pomocą 64-bitowego MSVC kompilatora.
msvc_x64: docelowa Windows x64 za pomocą MSVC kompilatora.
msvc_x64_x64: docelowa Windows x64 za pomocą 64-bitowego MSVC kompilatora.
msvc_x86: docelowa Windows x86 za pomocą MSVC kompilatora.
msvc_x86_x64: docelowa Windows x86 za pomocą 64-bitowego MSVC kompilatora.

Uzyskiwanie dostępu do zmiennych środowiskowych z `CMakeLists.txt`

W pliku CMakeLists.txt do wszystkich zmiennych środowiskowych odwołuje się składnia $ENV{variable_name}. Aby wyświetlić dostępne zmienne dla środowiska, otwórz odpowiedni wiersz polecenia i wpisz SET. Niektóre informacje w zmiennych środowiskowych są również dostępne za pośrednictwem zmiennych introspekcji systemu CMake, ale korzystanie ze zmiennej środowiskowej może okazać się wygodniejsze. Na przykład można łatwo pobrać wersję kompilatora MSVC lub wersję Windows SDK za pośrednictwem zmiennych środowiskowych.

Niestandardowe zmienne środowiskowe

W CMakeSettings.jsonpliku można definiować niestandardowe zmienne środowiskowe globalnie lub dla konfiguracji w tablicy environments . Środowisko niestandardowe to wygodny sposób grupowania zestawu właściwości. Można go użyć w miejsce wstępnie zdefiniowanego środowiska albo rozszerzyć lub zmodyfikować wstępnie zdefiniowane środowisko. Każdy element w tablicy environments składa się z:

namespace: nazwij środowisko, aby można było odwoływać się do jego zmiennych z konfiguracji w postaci namespace.variable. Domyślny obiekt środowiska jest wywoływany i env jest wypełniany pewnymi zmiennymi środowiskowym systemu, w tym %USERPROFILE%.
environment: unikatowo identyfikuje tę grupę zmiennych. Umożliwia dziedziczenie grupy w dalszej części inheritEnvironments wpisu.
groupPriority: liczba całkowita określająca priorytet tych zmiennych podczas ich oceny. Elementy o większej liczbie są oceniane jako pierwsze.
inheritEnvironments: tablica wartości określająca zestaw środowisk dziedziczonych przez tę grupę. Ta funkcja umożliwia dziedziczenie środowisk domyślnych i tworzenie niestandardowych zmiennych środowiskowych w celu przekazania ich do CMake podczas jego pracy.

Visual Studio 2019 w wersji 16.4 lub nowszej: obiekty docelowe debugowania są automatycznie uruchamiane w środowisku, które określono w programie CMakeSettings.json. Zmienne środowiskowe można przesłonić lub dodać dla każdego obiektu docelowego lub zadania w programie launch.vs.json i tasks.vs.json.

W poniższym przykładzie zdefiniowano jedną zmienną globalną, BuildDir, która jest dziedziczona zarówno w konfiguracjach x86-Debug, jak i x64-Debug. Każda konfiguracja używa zmiennej , aby określić wartość właściwości buildRoot dla tej konfiguracji. Należy również zauważyć, że każda konfiguracja używa właściwości inheritEnvironments do określenia zmiennej, która ma zastosowanie tylko do tej konfiguracji.

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

W następnym przykładzie konfiguracja x86-Debug definiuje własną wartość właściwości BuildDir . Ta wartość zastępuje wartość ustawioną przez globalną właściwość BuildDir , dzięki czemu właściwość BuildRoot ma wartość 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

W programie można używać następujących makr CMakeSettings.json:

${workspaceRoot} — pełna ścieżka folderu obszaru roboczego
${workspaceHash} — skrót lokalizacji obszaru roboczego; przydatne do tworzenia unikatowego identyfikatora dla bieżącego obszaru roboczego (na przykład do użycia w ścieżkach folderów)
${projectFile}— pełna ścieżka pliku głównego CMakeLists.txt
${projectDir} — pełna ścieżka folderu zawierającego plik CMakeLists.txt główny
${projectDirName} — nazwa folderu zawierającego plik CMakeLists.txt główny
${thisFile} — pełna ścieżka CMakeSettings.json pliku
${name} — nazwa konfiguracji
${generator} — nazwa generatora CMake używanego w tej konfiguracji

Wszystkie odwołania do makr i zmiennych środowiskowych CMakeSettings.json w programie są rozwinięte przed ich przekazem do wiersza polecenia CMake.

Argumenty wiersza polecenia ninja

Jeśli cele są nieokreślone, Ninja tworzy "domyślny" element docelowy.

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

Opcja	Opis
`--version`	Print ninja version ("1.7.1")
`-C DIR`	Zmień katalog na DIR przed wykonaniem czegokolwiek innego
`-f FILE`	Określanie wejściowego pliku kompilacji (default=`build.ninja`)
`-j N`	Równoległe `N` uruchamianie zadań (wartość domyślna= 14, pochodząca z dostępnych procesorów CPU)
`-k N`	Nie wytrzymaj pracy do `N` momentu, gdy zadania nie powiodą się (wartość domyślna= 1)
`-l N`	Nie uruchamiaj nowych zadań, jeśli średnia obciążenia jest większa niż `N`
`-n`	Przebieg suchy (nie uruchamiaj poleceń, ale działaj tak, jakby zakończyły się pomyślnie)
`-v`	Pokaż wszystkie wiersze polecenia podczas budowania
`-d MODE`	Włącz debugowanie (użyj do `-d list` wyświetlania listy trybów)
`-t TOOL`	Uruchom podnarzędzia (użyj , `-t list` aby wyświetlić listę podnarzędń). Kończy wszystkie opcje najwyższego poziomu; dalsze flagi są przekazywane do narzędzia
`-w FLAG`	Dostosowywanie ostrzeżeń (użyj , aby `-w list` wyświetlić listę ostrzeżeń)

`CMakeSettings.json` informacje o schemacie

Konfiguracje

Ustawienia dla projektów CMake w systemie Linux

Środowiska

Uzyskiwanie dostępu do zmiennych środowiskowych z `CMakeLists.txt`

Niestandardowe zmienne środowiskowe

Makra

Argumenty wiersza polecenia ninja

Dodatkowe zasoby

Dodatkowe zasoby

CMakeSettings.json informacje o schemacie

Konfiguracje

Ustawienia dla projektów CMake w systemie Linux

Środowiska

Uzyskiwanie dostępu do zmiennych środowiskowych z CMakeLists.txt

Niestandardowe zmienne środowiskowe

Makra

Argumenty wiersza polecenia ninja

Dodatkowe zasoby

Dodatkowe zasoby

`CMakeSettings.json` informacje o schemacie

Uzyskiwanie dostępu do zmiennych środowiskowych z `CMakeLists.txt`