共用方式為

CMakePresets.json 和 CMakeUserPresets.json Microsoft 廠商地圖

  • 發行項

CMake 支援兩個檔案和 CMakePresets.json CMakeUserPresets.json，可讓使用者指定一般設定、建置和測試選項，並與其他人共用。

CMakePresets.json 和 CMakeUserPresets.json 可用來在Visual Studio、Visual Studio Code、持續整合 （CI） 管線中，以及從命令行驅動 CMake。

CMakePresets.json 是用來儲存整個項目的組建，而且 CMakeUserPresets.json 適用於開發人員儲存自己的本機組建。 這兩個檔案的架構都相同。

CMakePresets.json 和支援 CMakeUserPresets.json 廠商會對應至儲存廠商特定資訊。 Microsoft會維護兩個廠商對應，其中包含Visual Studio和Visual Studio Code特有的選項。 在這裡，我們會記錄兩個Microsoft廠商地圖和廠商巨集。 如需架構其餘部分的詳細資訊，請參閱官方 CMake 檔。 其中包含設定預設、建置預設和測試預設的相關信息。

如需如何在Visual Studio中使用 CMakePresets.json 的詳細資訊，請參閱 在Visual Studio中使用 CMake 預設值進行設定和建置

如需如何在 Visual Studio Code 中使用 CMakePresets.json 的詳細資訊，請參閱 在 VS Code 中使用 CMake 預設值進行設定和建置

Visual Studio 設定廠商對應

每個設定預設值允許一個廠商對應與廠商 URI microsoft.com/VisualStudioSettings/CMake/<version> ，並包含 Visual Studio 和 Visual Studio Code 中 CMake 整合特有的選項。 廠商對應中的所有選項都會套用至 Visual Studio。 已明確標記適用於 Visual Studio 和 Visual Studio Code 的選項。

Visual Studio 設定廠商對應中的所有設定都是選擇性的，而且繼承自密鑰所 inherits 指定的 [設定預設]。 只有已修改的選項會寫入檔案。 和CMakeUserPresets.json都支援 CMakePresets.json Visual Studio 設定廠商對應。

Visual Studio 設定廠商對應中的選項不會影響 CMake 或 CTest 命令行的建構。 因此， CMakePresets.json 相同的檔案可用來使用 Visual Studio、Visual Studio Code 和命令行來驅動 CMake。 例外狀況為 cacheRoot 和 cmakeGenerateCommand 選項。 這些選項是 Visual Studio 中開啟現有快取案例的特定選項，無法從命令行重現。

設定 描述
hostOS 支援的操作系統陣列（OS）。 可接受的值為 Windows、Linux 和 macOS。

hostOS的值是由 Visual Studio 和 Visual Studio Code 用來隱藏未套用至目標系統的 OS 的設定預設值，並提供更佳的用戶體驗。

如果未 hostOS 指定，則 Visual Studio 和 Visual Studio Code 一律會顯示所有 [設定預設值] 以供選取。 此欄位也可以是字串，相當於包含一個字串的陣列

Visual Studio 和 Visual Studio Code 都支援此選項。
intelliSenseMode 指定以 格式 <target>-<toolset>-<arch>計算 Visual Studio 中 IntelliSense 資訊的模式。

接受的值：

android-clang-arm
android-clang-arm64
android-clang-x6
android-clang-x86
ios-clang-ar
ios-clang-arm64
ios-clang-x6
ios-clang-x86
linux-gcc-arm
linux-gcc-x64
linux-gcc-x86
windows-clang-arm
windows-clang-arm64
windows-clang-x64
windows-clang-x86
windows-msvc-arm
windows-msvc-arm64
windows-msvc-x64
windows-msvc-x86

如果未 intelliSenseMode 指定，則 Visual Studio 會使用符合您指定編譯程式和目標架構的 IntelliSense 模式。 intelliSenseMode 通常用來提供改善的 IntelliSense 以進行交叉編譯。

在 Visual Studio 2019 中，您必須使用 clang 或 clang-cl 建置時明確指定 clang IntelliSense 模式。
intelliSenseOptions 額外的 IntelliSense 組態選項對應。

useCompilerDefaultsbool：，指定是否要使用編譯程式預設定義並包含 IntelliSense 的路徑。 只有在 false 使用中的編譯程式不支援 gcc 樣式自變數時，才應為 。 預設為 true。

additionalCompilerArgs：在 Visual Studio 中控制 IntelliSense 的額外選項陣列。 此選項支援巨集擴充。
enableMicrosoftCodeAnalysis bool，可在使用 cl 或 clang-cl建置時，在 Visual Studio 中啟用Microsoft程式代碼分析。 預設為 false。
codeAnalysisRuleset 指定在 Visual Studio 中執行 Microsoft 程式代碼分析時要使用的規則集。 您可以使用規則集檔案的路徑，或隨 Visual Studio 一起安裝的規則集檔案名稱。 此選項支援巨集擴充。
disableExternalAnalysis bool，指定程式代碼分析是否應在 Visual Studio 中的外部標頭上執行。
codeAnalysisExternalRuleset 指定在 Visual Studio 中執行 Microsoft 程式代碼分析時要使用的規則集。 您可以使用規則集檔案的路徑，或隨 Visual Studio 一起安裝的規則集檔案名稱。 此選項支援巨集擴充。
enableClangTidyCodeAnalysis 布爾，可在使用 建 clang-cl置時，在Visual Studio中啟用 clang-tidy 程式代碼分析。 預設為 false。
clangTidyChecks 在 Visual Studio 中執行 clang-tidy 程式代碼分析時，傳遞至 clang-tidy 的警告逗號分隔清單。 允許通配符，前置 - 詞將會移除檢查。
cacheRoot 指定 CMake 快取的路徑。 此目錄應該包含現有的 CMakeCache.txt 檔案。 只有在 Visual Studio 中開啟現有的快取案例才支援此機碼。 此選項支援巨集擴充。
cmakeGenerateCommand 命令行工具（例如 gencache.bat debug，指定為命令行程式和自變數），以產生 CMake 快取。 當叫用 CMake 設定時，此命令會使用預設的指定環境在殼層中執行。 只有在 Visual Studio 中 開啟現有的快取 案例才支援此機碼。 此選項支援巨集擴充。

Visual Studio 遠端設定廠商對應

每個設定預設值允許一個廠商對應與廠商 URI microsoft.com/VisualStudioRemoteSettings/CMake/<version> ，並包含 Visual Studio 中遠端開發專屬的選項。 遠端開發表示您要在遠端 SSH 連線或 WSL 上叫用 CMake。 Visual Studio 遠端設定廠商對應中沒有任何選項適用於 Visual Studio Code。

Visual Studio 遠端設定廠商對應中的所有設定都是選擇性的，而且繼承自機碼所 inherits 指定的 [設定預設]。 只有已修改的選項會寫入檔案。 和CMakeUserPresets.json都支援 CMakePresets.json Visual Studio 遠端設定廠商對應。

Visual Studio 設定廠商對應中的選項不會影響 CMake 或 CTest 命令行的建構。 因此， CMakePresets.json 相同的檔案可用來使用 Visual Studio、Visual Studio Code 和命令行來驅動 CMake。

當目標為WSL1時，會忽略Visual Studio遠端設定廠商對應中的許多選項。 這是因為 WSL1 工具組會在本機執行所有命令，並依賴掛接在 /mnt 資料夾下的 Windows 磁碟驅動器，以從 WSL1 存取本機來源檔案。 不需要原始程式檔複製。 以 WSL1 為目標時忽略的選項已明確標記。

設定 描述
sourceDir 將複製專案之遠端系統上目錄的路徑。 預設為 $env{HOME}/.vs/$ms{projectDirName}。 此選項支援巨集擴充。

在遠端複製案例中，巨集 ${sourceDir} 會評估為遠端系統上的專案來源目錄，而不是 Windows 電腦上的專案來源目錄。 遠端複製案例包括以遠端 SSH 連線為目標。 在這些情況下，遠端系統上的專案來源目錄取決於 Visual Studio 遠端設定廠商對應中的值 sourceDir 。 以 WSL1 為目標時，會忽略此選項。
copySources 如果 true為 ，Visual Studio 會將來源從 Windows 複製到遠端系統。 如果您自行管理檔案同步處理，請將 設定為 false 。 預設為 true。 以 WSL1 為目標時，會忽略此選項。
copySourcesOptions 與來源從 Windows 複製到遠端系統相關的選項物件。 以 WSL1 為目標時，會忽略此物件。

copySourcesOptions.exclusionList：將來源檔案複製到遠端系統時要排除的路徑清單。 路徑可以是檔案或目錄的名稱，或是複製根目錄中的相對路徑。 預設為 [ ".vs", ".git", "out" ]。 此選項支援巨集擴充。

copySourcesOptions.method：用來將來源檔案複製到遠端系統的方法。 接受的值是 rsync 和 sftp。 預設為 rsync。

copySourcesOptions.concurrentCopies：同步處理來源至遠端系統期間所使用的並行複本數目。 預設為 5。

copySourcesOptions.outputVerbosity：來源複製作業的詳細資訊層級至遠端系統。 接受層級為 Normal、 Verbose與 Diagnostic。 預設為 Normal。
rsyncCommandArgs 傳遞至 rsync的命令行自變數清單。 預設為 [ "-t", "--delete", "--delete-excluded" ]。 此選項支援巨集擴充，且在以 WSL1 為目標時會忽略。
copyBuildOutput 指定是否要將組建輸出從遠端系統複製到 Windows。 預設為 false。 以 WSL1 為目標時，會忽略此選項。
copyOptimizations 與來源複製優化相關的選項物件。 當以 WSL1 為目標時，會忽略這些選項。

copyOptimizations.maxSmallChange：使用 sftp 複製的檔案數目上限，而不是 rsync。 預設為 10。

copyOptimizations.useOptimizations：指定使用中的複製優化。 接受的值不是複製優化 （None）、僅限 rsync 優化 （RsyncOnly）， 或 rsync 和 sftp 優化 （RsyncAndSftp）。 預設為 RsyncAndSftp。

copyOptimizations.rsyncSingleDirectoryCommandArgs：將單一目錄的內容複製到遠端系統時，傳遞給 rsync 的命令行自變數清單。 預設為 [ "-t", "-d" ]。 此選項支援巨集擴充。
copyAdditionalIncludeDirectoriesList 要針對 IntelliSense 在本機複製之遠端標頭目錄的路徑清單。 此選項支援巨集擴充。
copyExcludeDirectoriesList IntelliSense 不會在本機複製遠端標頭目錄的路徑清單。 此選項支援巨集擴充。
forceWSL1Toolset 如果 true為 ，Visual Studio 在從 Visual Studio 以 WSL 為目標時，一律會使用 WSL1 工具組。 WSL1 工具組會在本機執行所有命令，並依賴掛接在 /mnt 資料夾下的 Windows 磁碟驅動器，從 WSL 存取本機來源檔案。 WSL2 可能較慢這些選項。 預設為 false。

WSL1 工具組一律會在 Visual Studio 2019 16.10 版中使用。 一旦提供 WSL2 的原生支援，此選項將會相關。

遠端建置前和建置後事件

remotePrebuildEvent與 remotePostbuildEvent 選項已被取代，並已採用 CMakePresets.json。

使用add_custom_command編碼建置前、連結前和建置後事件CMakeLists.txt。 使用 Visual Studio 和從命令行建置時，可確保相同的行為。

如果您需要 Visual Studio 特有的行為，您可以在 中 tasks.vs.json新增自定義遠端工作。 若要開始使用，請以滑鼠右鍵按兩下 [資料夾檢視] 方案總管 中的根目錄CMakeLists.txt，然後選取 [設定工作]。 然後 ，您可以將新的遠端工作 新增至檔案 tasks.vs.json 。

下列遠端工作會在遠端 Linux 系統上建立名為 test 的目錄：

{
      "taskLabel": "mkdir",
      "appliesTo": "CMakeLists.txt",
      "type": "remote",
      "command": "mkdir test",
      "remoteMachineName": "localhost"
  }

以滑鼠右鍵按兩下任一 CMakeLists.txt 項目，然後選取 [mkdir ] 選項來執行這項工作。

的值remoteMachineName必須符合 連線管理員 中連線的主機名。

Microsoft廠商巨集

這兩個Microsoft廠商對應 Visual Studio Settings 和 Visual Studio Remote Settings支援 CMake 定義的所有巨集。 我們的廠商對應支援 CMake 定義的所有巨集。 如需詳細資訊，請參閱 cmake-presets Macro Expansion。 所有巨集和環境變數都會在傳遞至 CMake 之前展開。

Visual Studio 支援前置詞 ms為 的廠商巨集。 Microsoft廠商巨集只能在Microsoft廠商對應中使用。 CMake 無法使用在廠商對應外部具有廠商巨集的預設。

Macro 描述
$ms{projectDirName} 評估為 Visual Studio 中開啟資料夾的名稱。 此巨集可用來設定遠端複製案例中的 預設值 sourceDir 。 Visual Studio Code 不支援此巨集。 請改用 ${sourceDirName}。

環境變數

Macro 描述
$env{<variable-name>}
$penv{<variable-name>}		 使用 CMake 支援的這個語法參考環境變數。 如需詳細資訊，請參閱 cmake-presets Macro Expansion。

已被取代的巨集

支援的 CMakeSettings.json 一些巨集已被取代，並採用 CMakePresets.json。

使用 CMake 支援的巨集來建構您的檔案路徑。 當您使用巨集時，它會確保相同的 CMakePresets.json 檔案可在Visual Studio和命令行內運作。

已被取代的巨集 建議
${projectFile} ${sourceDir}/CMakeLists.txt
${thisFile} ${sourceDir}/CMakePresets.json

接受的殼層語法

在 $env{HOME} Microsoft廠商對應中建構 Linux 路徑時，請使用 語法來參考 $HOME 。