`CMakeSettings.json` スキーマリファレンス

[アーティクル]
04/03/2023

CMake プロジェクトは Visual Studio 2017 以降でサポートされます。

CMakeSettings.json ファイルには、Visual Studio が IntelliSense に使用する情報と、指定された構成とコンパイラの環境用の CMake に渡すコマンドライン引数を作成するための情報が含まれています。 "構成" では、特定のプラットフォームおよびビルドの種類に適用されるプロパティ (x86-Debug や Linux-Release など) が指定されます。各構成では、コンパイラツールセット (MSVC、GCC、Clang など) に関する情報をカプセル化する "環境" が指定されます。 CMake では、コマンドライン引数を使用して、プロジェクトのルートの CMakeCache.txt ファイルおよびその他のプロジェクトファイルが再生成されます。値は CMakeLists.txt ファイルでオーバーライドできます。

IDE で構成を追加または削除できます。また、JSON ファイルで直接編集したり、CMake 設定エディター (Visual Studio 2019 以降) を使用したりすることができます。 IDE で構成を簡単に切り替えてさまざまなプロジェクトファイルを生成できます。詳細については、「Visual Studio で CMake のビルド設定をカスタマイズする」を参照してください。

構成

configurations 配列には、1 つの CMake プロジェクトのすべての構成が含まれています。定義済みの構成の詳細については、「CMake 定義済み構成リファレンス」を参照してください。ファイルには、任意の数の事前定義済みまたはカスタムの構成を追加できます。

configuration には次のプロパティがあります。

addressSanitizerEnabled: true の場合、AddressSanitizer を使用してプログラムがコンパイルされます。 Linux の場合、最善の結果を得るには、-fno-omit-frame-pointer およびコンパイラ最適化レベル -Os または -Oo でコンパイルします。
addressSanitizerRuntimeFlags: ASAN_OPTIONS 環境変数の AddressSanitizer に渡されるランタイムフラグです。形式: フラグ 1=値:フラグ 2=値 2。
buildCommandArgs: --build -- の後に CMake に渡されるネイティブビルドスイッチが指定されます。たとえば、Ninja ジェネレーターの使用時に -v を渡すと、コマンドラインの出力が Ninja に強制されます。 Ninja コマンドの詳細については、「Ninja のコマンドライン引数」を参照してください。
buildRoot: 選択したジェネレーターに CMake がビルドスクリプトを生成するディレクトリが指定されます。 -DCMAKE_BINARY_DIR スイッチにマップし、CMakeCache.txt を作成する場所が指定されます。フォルダーが存在しない場合は、作成されます。サポートされているマクロには、${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE} などがあります。
cacheGenerationCommand: コマンドラインツールと引数が指定されます (キャッシュを生成するための gencache.bat debug など)。このコマンドは、ユーザーが再生成を明示的にリクエストした場合か、CMakeLists.txt または CMakeSettings.json ファイルが変更された場合に、構成に指定された環境のシェルから実行されます。
cacheRoot: CMake キャッシュへのパスが指定されます。このディレクトリには、既存の CMakeCache.txt ファイルが含まれている必要があります。
clangTidyChecks: clang-tidy に渡される警告のコンマ区切りリスト。ワイルドカードを使用でき、'-' プレフィックスによりチェックは削除されます。
cmakeCommandArgs: プロジェクトファイルを生成するために呼び出す場合に CMake に渡す追加のコマンドラインオプションが指定されます。
cmakeToolchain: ツールチェーンファイルが指定されます。 -DCMAKE_TOOLCHAIN_FILE を使用して CMake に渡されます。
codeAnalysisRuleset: コード分析を実行しているときに使用するルールセットが指定されます。 Visual Studio によってインストールされたルールセットファイルの完全なパスまたはファイル名を使用できます。
configurationType: 選択したジェネレーターにビルドの種類の構成が指定されます。次のいずれかを指定できます。
- Debug
- Release
- MinSizeRel
- RelWithDebInfo
ctestCommandArgs: テストの実行中に CTest に渡す追加のコマンドラインオプションが指定されます。
description: メニューに表示されるこの構成の説明。
enableClangTidyCodeAnalysis: コード分析に Clang-Tidy を使用します。
enableMicrosoftCodeAnalysis: コード分析に Microsoft コード分析ツールを使用します。
generator: この構成に使用する CMake ジェネレーターが指定されます。次のいずれかを指定できます。

Visual Studio 2019 のみ:
- Visual Studio 16 2019
- Visual Studio 16 2019 Win64
- Visual Studio 16 2019 ARM
Visual Studio 2017 以降:
- 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

Ninja は柔軟性や機能ではなく、ビルド速度が速いことを目的に設計されているため、既定値としてこれが設定されます。ただし、CMake プロジェクトによっては、Ninja を使うと正しくビルドできないことがあります。ビルドの失敗が発生する場合は、代わりに Visual Studio プロジェクトを生成するように CMake に指示できます。

Visual Studio 2017 で Visual Studio ジェネレーターを指定するには、メインメニューから [CMake] > [CMake の設定を変更] を選択して、設定エディターを開きます。 "Ninja" を削除して「V」と入力します。この変更により IntelliSense がアクティブになり、必要なジェネレーターを選択できます。

Visual Studio 2019 で Visual Studio ジェネレーターを指定するには、ソリューションエクスプローラーの CMakeLists.txt ファイルを右クリックし、[プロジェクトの CMake の設定]>[詳細設定の表示]>[CMake ジェネレーター] を選択します。

アクティブな構成で Visual Studio ジェネレーターを指定すると、既定では -m -v:minimal 引数を指定して MSBuild が呼び出されます。ビルドをカスタマイズするには、CMakeSettings.json ファイル内で buildCommandArgs プロパティを使用します。ここでは、ビルドシステムに渡す MSBuild コマンドライン引数を指定できます。

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

installRoot: 選択したジェネレーターに CMake がインストールターゲットを生成するディレクトリが指定されます。サポートされているマクロには、${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE} などがあります。
inheritEnvironments: この構成が依存している 1 つまたは複数のコンパイラ環境が指定されます。任意のカスタム環境を使用することも、定義済みの環境を使用することもできます。詳細については、環境に関するページを参照してください。
intelliSenseMode: IntelliSense の情報を計算するために使用するモードが指定されます。値は次のいずれかにすることができます。
- 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: 構成に名前を付けます。定義済みの構成の詳細については、「CMake 定義済み構成リファレンス」を参照してください。
wslPath: Linux 用 Windows サブシステムインスタンスの起動ツールへのパスです。

CMake Linux プロジェクトの設定

remoteMachineName: CMake、ビルド、およびデバッガーをホストするリモートの Linux マシンの名前が指定されます。新しい Linux マシンを追加するには、接続マネージャーを使用します。サポートされているマクロには、${defaultRemoteMachineName} が含まれます。
remoteCopySourcesOutputVerbosity: リモートマシンへのソースコピー操作の詳細レベルが指定されます。 Normal、Verbose、または Diagnostic のいずれかを指定できます。
remoteCopySourcesConcurrentCopies: ソースからリモートマシンへの同期中に使用される同時コピー数が指定されます (sftp のみ)。
remoteCopySourcesMethod: リモートマシンにファイルをコピーするメソッドが指定され rsync または sftp を指定できます。
remoteCMakeListsRoot: CMake プロジェクトを含むリモートマシン上のディレクトリが指定されます。サポートされているマクロには、${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE} などがあります。
remoteBuildRoot: 選択したジェネレーターに CMake がビルドスクリプトを生成するリモートマシン上のディレクトリが指定されます。サポートされているマクロには、${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE} などがあります。
remoteInstallRoot: 選択したジェネレーターに CMake がインストールターゲットを生成するリモートマシン上のディレクトリが指定されます。サポートされているマクロには、${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE} などがあります。VARIABLE は、システム、ユーザー、またはセッションレベルで定義されている環境変数です。
remoteCopySourcesboolean: Visual Studio でソースファイルをリモートコンピューターにコピーするかどうかを指定する A。既定値は true です。自分でファイルの同期を管理する場合は、false に設定します。
remoteCopyBuildOutputboolean: リモートシステムからビルド出力をコピーするかどうかを指定する A。
remoteCopyAdditionalIncludeDirectories: IntelliSense をサポートするためにリモートコンピューターからコピーする追加のインクルードディレクトリ。 "/path1;/path2..." の形式にします。
remoteCopyExcludeDirectories: リモートコンピューターからコピーしないディレクトリを含めます。 "/path1;/path2..." の形式にします。
remoteCopyUseCompilerDefaults: コンパイラの既定の定義と IntelliSense のインクルードパスを使用するかどうかを指定します。使用中のコンパイラが GCC 風の引数をサポートしていない場合に限り、false にする必要があります。
rsyncCommandArgs: rsync に渡されるコマンドラインオプションのセットが指定されます。
remoteCopySourcesExclusionList: ソースファイルのコピー中に除外するパスの一覧を指定する array: パスには、ファイルまたはディレクトリの名前か、コピーのルートに対する相対パスを指定できます。 glob パターンマッチング用のワイルドカード * および ? を使用できます。
cmakeExecutable: CMake プログラムの実行可能ファイルへの完全なパスが指定されます。ファイル名と拡張子を含めます。
remotePreGenerateCommand: CMakeLists.txt ファイルを解析するために CMake の実行前に実行するコマンドが指定されます。
remotePrebuildCommand: ビルド前にリモートマシン上で実行するコマンドが指定されます。
remotePostbuildCommand: ビルド後にリモートマシン上で実行するコマンドが指定されます。
variables: -D name=value として CMake に渡される CMake 変数の名前と値のペアを含みます。 CMake プロジェクトのビルド命令で CMakeCache.txt ファイルに直接変数を追加するように指定している場合は、代わりにここで追加することをお勧めします。次の例は、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"
    }
  ]

"type" を定義しない場合、既定では "STRING" 型が想定されます。

remoteCopyOptimizations: リモートターゲットへのソースのコピーを制御するための Visual Studio 2019 バージョン 16.5 以降のプロパティ。既定で最適化が有効になっています。 remoteCopyUseOptimizations、rsyncSingleDirectoryCommandArgs、および remoteCopySourcesMaxSmallChange が含まれます。

環境

"環境" では、Visual Studio がCMake を呼び出すために使用するプロセスに設定された環境変数がカプセル化されます。 MSVC プロジェクトの場合、特定のプラットフォーム用に開発者コマンドプロンプトで設定された変数がカプセル化されます。たとえば、環境は、msvc_x64_x64-arch=amd64 -host_arch=amd64 引数を指定して VS {version} の開発者コマンドプロンプトを実行する場合と同じです。たとえば、フォルダーへのパスを作成する場合などに、CMakeSettings.json で env.{<variable_name>} 構文を使用して、個々の環境変数を参照できます。次の定義済みの環境が用意されています。

linux_arm: ARM Linux をリモートでターゲットにします。
linux_x64: x64 Linux をリモートでターゲットにします。
linux_x86: x86 Linux をリモートでターゲットにします。
msvc_arm: MSVC コンパイラを使用して ARM Windows をターゲットとします。
msvc_arm_x64: 64 ビットの MSVC コンパイラを使用して ARM Windows をターゲットとします。
msvc_arm64: MSVC コンパイラを使用して ARM64 Windows をターゲットとします。
msvc_arm64_x64: 64 ビットの MSVC コンパイラを使用して ARM64 Windows をターゲットとします。
msvc_arm64ec: MSVC コンパイラを使用して ARM64EC Windows をターゲットにします。
msvc_arm64ec_x64: 64 ビット MSVC コンパイラを使用して ARM64EC Windows をターゲットにします。
msvc_x64: MSVC コンパイラを使用して x64 Windows をターゲットとします。
msvc_x64_x64: 64 ビットの MSVC コンパイラを使用して x64 Windows をターゲットとします。
msvc_x86: MSVC コンパイラを使用して x86 Windows をターゲットとします。
msvc_x86_x64: 64 ビットの MSVC コンパイラを使用して x86 Windows をターゲットとします。

`CMakeLists.txt` から環境変数へのアクセス

CMakeLists.txt ファイルからは、すべての環境変数が $ENV{variable_name} 構文によって参照されます。環境で使用できる変数を確認するには、対応するコマンドプロンプトを開いて「SET」と入力します。環境変数の一部の情報は、CMake システムのイントロスペクション変数でも取得できますが、環境変数を使用する方が便利な場合があります。たとえば、MSVC コンパイラバージョンまたは Windows SDK バージョンは、環境変数によって簡単に取得できます。

カスタム環境変数

CMakeSettings.json では、グローバルに、または environments 配列を使用して構成ごとに、カスタム環境変数を定義できます。カスタム環境を使用すると、プロパティのセットを簡単にグループ化できます。定義済みの環境の代わりにこれを使用することも、定義済みの環境を拡張または変更することもできます。 environments 配列内の各項目は以下で構成されています。

namespace: フォーム namespace.variable 内の構成から変数を参照できるように環境に名前を付けます。既定の環境オブジェクトは env と呼ばれ、%USERPROFILE% などの特定のシステム環境変数で設定されます。
environment: この変数グループを一意に識別します。後で inheritEnvironments エントリでグループが継承できるようにします。
groupPriority: これらの変数を評価するときの優先順位を指定する整数。数字が大きい大きい項目が最初に評価されます。
inheritEnvironments: このグループによって継承される環境のセットを指定する値の配列。この機能を使用すると、既定の環境を継承し、実行時に CMake に渡されるカスタム環境変数を作成することができます。

Visual Studio 2019 バージョン 16.4 以降:CMakeSettings.json で指定した環境を使用して、デバッグターゲットが自動的に起動されます。 launch.vs.json および tasks.vs.json では、ターゲットまたはタスクごとに環境変数をオーバーライドまたは追加できます。

次の例では、1 つのグローバル変数 BuildDir を定義します。これは、x86-Debug と x64-Debug の両方の構成で継承されます。各構成は、この変数を使って、その構成の buildRoot プロパティの値が指定されます。各構成が inheritEnvironments プロパティを使ってその構成のみに適用される変数を指定する方法にもご注意ください。

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

次の例では、x86 デバッグ構成が BuildDir プロパティに対して独自の値を定義します。この値は、BuildRoot が D:\custom-builddir\x86-Debug に評価されるように、グローバル BuildDir プロパティによって設定される値をオーバーライドします。

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

マクロ

CMakeSettings.json では、次のマクロを使用できます。

${workspaceRoot} - ワークスペースフォルダーへの完全なパスです
${workspaceHash} – ワークスペースの場所のハッシュです。現在のワークスペースの一意識別子を作成するのに便利です (たとえば、フォルダーのパスで使用する場合)
${projectFile} – ルート CMakeLists.txt ファイルの完全なパスです
${projectDir} – ルート CMakeLists.txt ファイルが格納されているフォルダーの完全なパスです
${projectDirName} – ルート CMakeLists.txt ファイルが格納されているフォルダーの名前です
${thisFile} – CMakeSettings.json ファイルの完全なパスです
${name} – 構成の名前です
${generator} – この構成で使用される CMake ジェネレーターの名前です

CMakeSettings.json のマクロと環境変数へのすべての参照は、CMake コマンドラインに渡される前に展開されます。

Ninja コマンドライン引数

ターゲットを指定しないと、Ninja では "default" ターゲットがビルドされます。

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

オプション	説明
`--version`	Ninja のバージョンを書き出します ("1.7.1")
`-C DIR`	何かを実行する前に、DIR (ディレクトリ) に変更します
`-f FILE`	入力ビルドファイルを指定します (既定値は `build.ninja`)
`-j N`	`N` 個のジョブを並列実行します (既定値は 14、使用可能な CPU の数から派生)
`-k N`	`N` 個のジョブが失敗するまで続けます (既定値は 1)
`-l N`	負荷の平均が `N` より大きい場合は、新しいジョブを開始しません
`-n`	ドライ実行 (コマンドを実行しませんが、成功したように動作します)
`-v`	ビルド中にすべてのコマンドラインを表示します
`-d MODE`	デバッグを有効にします (モードを一覧表示するには `-d list` を使用)
`-t TOOL`	サブツールを実行します (サブツールを一覧表示するには `-t list` を使用)。トップレベルのオプションを終了します。さらにフラグがツールに渡されます
`-w FLAG`	警告を調整します (警告を一覧表示するには `-w list` を使用)

`CMakeSettings.json` スキーマリファレンス

構成

CMake Linux プロジェクトの設定

環境

`CMakeLists.txt` から環境変数へのアクセス

カスタム環境変数

マクロ

Ninja コマンドライン引数

フィードバック

フィードバック

その他のリソース

CMakeSettings.json スキーマ リファレンス

構成

CMake Linux プロジェクトの設定

環境

CMakeLists.txt から環境変数へのアクセス

カスタム環境変数

マクロ

Ninja コマンド ライン引数

フィードバック

フィードバック

その他のリソース

`CMakeSettings.json` スキーマリファレンス

`CMakeLists.txt` から環境変数へのアクセス

Ninja コマンドライン引数