`CMakeSettings.json` odwołanie do schematu

Artykuł
10/12/2023

Projekty CMake są obsługiwane w programie Visual Studio 2017 lub nowszym.

Plik CMakeSettings.json zawiera informacje używane przez program Visual Studio dla funkcji IntelliSense oraz konstruowanie argumentów wiersza polecenia, które przekazuje do narzędzia CMake dla określonego środowiska konfiguracji i 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 o zestawie narzędzi kompilatora, na przykład MSVC, GCC lub Clang. Narzędzie CMake używa argumentów wiersza polecenia do ponownego wygenerowania pliku głównego CMakeCache.txt i innych plików projektu dla projektu. Wartości można zastąpić w plikach CMakeLists.txt .

Konfiguracje można dodawać lub usuwać w środowisku IDE, a następnie edytować je bezpośrednio w pliku JSON lub użyć edytora ustawień narzędzia CMake (Visual Studio 2019 i nowszych). Możesz łatwo przełączać się między konfiguracjami w środowisku IDE, aby wygenerować różne pliki projektu. Aby uzyskać więcej informacji, zobacz Dostosowywanie ustawień kompilacji narzędzia CMake w programie 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 (Dokumentacja wstępnie zdefiniowanej konfiguracji narzędzia CMake). Do pliku można dodać dowolną liczbę wstępnie zdefiniowanych lub niestandardowych konfiguracji.

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

addressSanitizerEnabled: Jeśli trueprogram skompiluje program przy użyciu narzędzia AddressSanitizer. W systemie Linux skompiluj -fno-omit-frame-pointer poziom -Os -Oo optymalizacji kompilatora i w celu uzyskania najlepszych wyników.
addressSanitizerRuntimeFlags: flagi środowiska uruchomieniowego przekazane do elementu AddressSanitizer w zmiennej środowiskowej ASAN_OPTIONS . Format: flag1=value:flag2=value2.
buildCommandArgs: Określa natywne przełączniki kompilacji przekazywane do narzędzia CMake po --build --. Na przykład przekazywanie -v w przypadku używania generatora Ninja wymusza, aby ninja wyprowadzało wiersze polecenia. Aby uzyskać więcej informacji na temat poleceń ninja, zobacz Ninja command line arguments (Argumenty wiersza polecenia Ninja).
buildRoot: określa katalog, w którym narzędzie CMake generuje skrypty kompilacji dla wybranego generatora. Mapuje na -DCMAKE_BINARY_DIR przełącznik i określa miejsce CMakeCache.txt utworzenia. Jeśli folder nie istnieje, zostanie utworzony. Obsługiwane makra obejmują ${workspaceRoot}, ${workspaceHash}${thisFile}${projectDir}${projectFile}${thisFileDir}, ${name}, . ${generator}${env.VARIABLE}
cacheGenerationCommand: Określa narzędzie wiersza polecenia i argumenty, na przykład gencache.bat debug w celu wygenerowania pamięci podręcznej. Polecenie jest uruchamiane z powłoki w określonym środowisku dla konfiguracji, gdy użytkownik jawnie żąda ponownego uruchomienia lub plik lub CMakeLists.txt CMakeSettings.json jest modyfikowany.
cacheRoot: określa ścieżkę do pamięci podręcznej CMake. Ten katalog powinien zawierać istniejący CMakeCache.txt plik.
clangTidyChecks: rozdzielona przecinkami lista ostrzeżeń przekazanych do clang-tidy; Symbole wieloznaczne są dozwolone, a prefiks "-" usuwa kontrole.
cmakeCommandArgs: określa wszelkie dodatkowe opcje wiersza polecenia, które mają być przekazywane do narzędzia CMake po wywołaniu w celu wygenerowania plików projektu.
cmakeToolchain: określa plik łańcucha narzędzi. Jest on przekazywany do narzędzia CMake przy użyciu polecenia -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 to być jeden z:
- Debug
- Release
- MinSizeRel
- RelWithDebInfo
ctestCommandArgs: Określa wszelkie dodatkowe opcje wiersza polecenia, które mają być przekazywane do narzędzia CTest podczas uruchamiania testów.
description: opis tej konfiguracji, która jest wyświetlana w menu.
enableClangTidyCodeAnalysis: Użyj języka Clang-Tidy do analizy kodu.
enableMicrosoftCodeAnalysis: użyj narzędzi do analizy kodu firmy Microsoft na potrzeby analizy kodu.
generator: określa generator CMake do użycia dla tej konfiguracji. Może to być jeden z:

Tylko program Visual Studio 2019:
- Visual Studio 16 2019
- Visual Studio 16 2019 Win64
- Visual Studio 16 2019 ARM
Program Visual Studio 2017 lub nowszy:
- 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 przeznaczony do szybkiego tworzenia szybkości zamiast elastyczności i funkcji, jest ustawiony jako domyślny. Jednak niektóre projekty narzędzia CMake mogą nie być w stanie poprawnie skompilować przy użyciu narzędzia Ninja. Jeśli wystąpi błąd kompilacji, możesz poinstruować narzędzie CMake, aby zamiast tego wygenerować projekty programu Visual Studio.

Aby określić generator programu Visual Studio w programie Visual Studio 2017, otwórz edytor ustawień z menu głównego, wybierając pozycję CMake | Zmień ustawienia narzędzia CMake. Usuń "Ninja" i wprowadź "V". Ta zmiana aktywuje funkcję IntelliSense, która umożliwia wybranie żądanego generatora.

Aby określić generator programu Visual Studio w programie Visual Studio 2019, kliknij prawym przyciskiem myszy CMakeLists.txt plik w Eksplorator rozwiązań i wybierz pozycję Ustawienia narzędzia CMake dla projektu>Pokaż zaawansowane ustawienia>Generator CMake.

Domyślnie, gdy aktywna konfiguracja określa generator programu Visual Studio, wywołuje program MSBuild z -m -v:minimal argumentami. Aby dostosować kompilację, użyj buildCommandArgs właściwości wewnątrz CMakeSettings.json pliku. W tym miejscu można określić argumenty wiersza polecenia MSBuild, które mają być przekazywane do systemu kompilacji:

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

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

Ustawienia projektów CMake w systemie Linux

remoteMachineName: określa nazwę zdalnej maszyny z systemem Linux, która hostuje narzędzie 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 maszynie zdalnej. Może być jednym z Normalelementów , Verboselub Diagnostic.
remoteCopySourcesConcurrentCopies: określa współbieżne kopie do użycia podczas synchronizacji źródeł na maszynie zdalnej (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óra zawiera projekt CMake. Obsługiwane makra obejmują ${workspaceRoot}, , ${workspaceHash}, ${projectDir}${thisFile}${thisFileDir}${projectFile}, ${name}, , ${generator}, i .${env.VARIABLE}
remoteBuildRoot: określa katalog na komputerze zdalnym, w którym narzędzie CMake generuje skrypty kompilacji dla wybranego generatora. Obsługiwane makra obejmują ${workspaceRoot}, ${workspaceHash}${thisFile}${projectDir}${projectFile}${thisFileDir}, ${name}, . ${generator}${env.VARIABLE}
remoteInstallRoot: określa katalog na komputerze zdalnym, w którym narzędzie CMake generuje obiekty docelowe instalacji dla wybranego generatora. Obsługiwane makra obejmują ${workspaceRoot}, , ${projectFile}${thisFileDir}${projectDir}${workspaceHash}${name}${generator}${thisFile}i ${env.VARIABLE}, gdzie VARIABLE jest zmienną środowiskową zdefiniowaną na poziomie systemu, użytkownika lub sesji.
remoteCopySources: Element boolean określający, czy program Visual Studio powinien kopiować pliki źródłowe na maszynę zdalną. Wartość domyślna to true. Ustaw wartość false, jeśli samodzielnie zarządzasz synchronizacją plików.
remoteCopyBuildOutput: Element boolean określający, czy skopiować dane wyjściowe kompilacji z systemu zdalnego.
remoteCopyAdditionalIncludeDirectories: Dodatkowe katalogi dołączane do skopiowania z maszyny zdalnej do obsługi funkcji IntelliSense. Formatuj jako "/path1;/path2...".
remoteCopyExcludeDirectories: Dołącz katalogi NIE do kopiowania z komputera zdalnego. Formatuj jako "/path1;/path2...".
remoteCopyUseCompilerDefaults: określa, czy używać domyślnych definiowania i dołączania ścieżek dla funkcji IntelliSense w kompilatorze. Powinny być fałszywe tylko wtedy, gdy kompilatory w użyciu nie obsługują argumentów w stylu gcc.
rsyncCommandArgs: Określa zestaw opcji wiersza polecenia przekazywanych do rsync.
remoteCopySourcesExclusionList: Element array określający listę ścieżek, które mają być wykluczone 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 wzorców glob.
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 narzędzia CMake, aby przeanalizować CMakeLists.txt plik.
remotePrebuildCommand: Określa polecenie do uruchomienia na maszynie zdalnej przed kompilacją.
remotePostbuildCommand: Określa polecenie do uruchomienia na maszynie zdalnej po utworzeniu.
variables: zawiera parę zmiennych CMake, które są przekazywane do -D name=value narzędzia CMake. Jeśli instrukcje kompilacji projektu CMake określają dodanie dowolnych zmiennych bezpośrednio do CMakeCache.txt pliku, zalecamy dodanie ich tutaj. W tym przykładzie pokazano, jak określić pary name-value do użycia zestawu narzędzi MSVC 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"
    }
  ]

Jeśli nie zdefiniujesz "type"elementu , "STRING" typ jest przyjmowany domyślnie.

remoteCopyOptimizations: Właściwości programu 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 remoteCopyUseOptimizations, rsyncSingleDirectoryCommandArgsi remoteCopySourcesMaxSmallChange.

Środowiska

Środowisko hermetyzuje zmienne środowiskowe ustawione w procesie używanym przez program Visual Studio do wywoływania narzędzia CMake. W przypadku projektów MSVC przechwytuje zmienne ustawione w wierszu polecenia dewelopera dla określonej platformy. Na przykład msvc_x64_x64 środowisko jest takie samo, jak w przypadku wiersza polecenia dewelopera dla programu VS {version} z argumentami -arch=amd64 -host_arch=amd64 . Składnię env.{<variable_name>} można użyć do CMakeSettings.json odwoływania 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 skierować usługę ARM do systemu Linux.
linux_x64: Docelowy system x64 Linux zdalnie.
linux_x86: Docelowy system x86 Linux zdalnie.
msvc_arm: Docelowy system ARM systemu Windows za pomocą kompilatora MSVC.
msvc_arm_x64: Docelowy system ARM z 64-bitowym kompilatorem MSVC.
msvc_arm64: Docelowy system Windows ARM64 za pomocą kompilatora MSVC.
msvc_arm64_x64: Docelowy system Windows ARM64 z 64-bitowym kompilatorem MSVC.
msvc_arm64ec: docelowy ARM64EC windows za pomocą kompilatora MSVC.
msvc_arm64ec_x64: docelowy ARM64EC windows z 64-bitowym kompilatorem MSVC.
msvc_x64: Docelowy system Windows x64 za pomocą kompilatora MSVC.
msvc_x64_x64: Docelowy system Windows x64 z 64-bitowym kompilatorem MSVC.
msvc_x86: Docelowy system Windows x86 za pomocą kompilatora MSVC.
msvc_x86_x64: Docelowy system Windows x86 z 64-bitowym kompilatorem MSVC.

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

CMakeLists.txt Z pliku wszystkie zmienne środowiskowe odwołują się do składni $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 może się okazać, że bardziej wygodne jest użycie zmiennej środowiskowej. Można na przykład łatwo pobrać wersję kompilatora MSVC lub wersję zestawu Windows SDK za pomocą zmiennych środowiskowych.

Niestandardowe zmienne środowiskowe

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

namespace: nazwij środowisko tak, aby można było odwoływać się do jego zmiennych z konfiguracji w formularzu namespace.variable. Domyślny obiekt środowiska jest wywoływany env i wypełniany określonymi zmiennymi środowiskowymi systemu, w tym %USERPROFILE%.
environment: jednoznacznie identyfikuje tę grupę zmiennych. Umożliwia dziedziczenie grupy w inheritEnvironments dalszej części wpisu.
groupPriority: Liczba całkowita określająca priorytet tych zmiennych podczas ich oceniania. Większa liczba elementów jest oceniana jako pierwsza.
inheritEnvironments: tablica wartości, które określają zestaw środowisk dziedziczone przez tę grupę. Ta funkcja umożliwia dziedziczenie środowisk domyślnych i tworzenie niestandardowych zmiennych środowiskowych do przekazywania do narzędzia CMake podczas jego uruchamiania.

Program Visual Studio 2019 w wersji 16.4 lub nowszej: Obiekty docelowe debugowania są automatycznie uruchamiane przy użyciu środowiska określonego w elem CMakeSettings.json. Możesz zastąpić lub dodać zmienne środowiskowe dla poszczególnych obiektów docelowych lub poszczególnych zadań w usługach launch.vs.json i tasks.vs.json.

W poniższym przykładzie zdefiniowano jedną zmienną globalną , BuildDirktóra jest dziedziczona zarówno w konfiguracjach x86-Debug, jak i x64-Debug. Każda konfiguracja używa zmiennej do określenia wartości właściwości buildRoot dla tej konfiguracji. Należy również pamiętać, jak każda konfiguracja używa inheritEnvironments właściwości 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 , aby wartość BuildRoot została obliczona na D:\custom-builddir\x86-Debugwartość .

{
  "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 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 główny CMakeLists.txt
${projectDirName}— nazwa folderu zawierającego plik główny CMakeLists.txt
${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 w programie CMakeSettings.json są rozwinięte przed przekazaniem do wiersza polecenia narzędzia CMake.

Argumenty wiersza polecenia ninja

Jeśli obiekty docelowe nie są określone, Ninja tworzy element docelowy "domyślny".

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

Opcja	Opis
`--version`	Drukuj wersję ninja ("1.7.1")
`-C DIR`	Przed wykonaniem niczego innego zmień na DIR
`-f FILE`	Określ wejściowy plik kompilacji (default=`build.ninja`)
`-j N`	Uruchamianie `N` zadań równolegle (wartość domyślna= 14, pochodząca z dostępnych procesorów CPU)
`-k N`	Kontynuuj przechodzenie do czasu `N` niepowodzenia zadań (default=1)
`-l N`	Nie uruchamiaj nowych zadań, jeśli średnia obciążenia jest większa niż `N`
`-n`	Uruchamianie suche (nie uruchamiaj poleceń, ale działają tak, jakby zakończyły się powodzeniem)
`-v`	Pokaż wszystkie wiersze polecenia podczas kompilowania
`-d MODE`	Włączanie debugowania (używanie `-d list` do wyświetlania listy trybów)
`-t TOOL`	Uruchom podtool (użyj `-t list` polecenia , aby wyświetlić listę podrzędnych narzędzi). Kończy wszystkie opcje najwyższego poziomu; dalsze flagi są przekazywane do narzędzia
`-w FLAG`	Dostosowywanie ostrzeżeń (użyj `-w list` polecenia , aby wyświetlić listę ostrzeżeń)

Udostępnij za pośrednictwem

`CMakeSettings.json` odwołanie do schematu

Konfiguracje

Ustawienia projektów CMake w systemie Linux

Środowiska

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

Niestandardowe zmienne środowiskowe

Makra

Argumenty wiersza polecenia ninja

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

CMakeSettings.json odwołanie do schematu

Konfiguracje

Ustawienia projektów CMake w systemie Linux

Środowiska

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

Niestandardowe zmienne środowiskowe

Makra

Argumenty wiersza polecenia ninja

Opinia

Dodatkowe zasoby

`CMakeSettings.json` odwołanie do schematu

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