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

CMake 支援兩個檔案和 CMakePresets.jsonCMakeUserPresets.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 Remote 設定廠商對應中的所有設定都是選擇性的，而且繼承自金鑰所 inherits 指定的設定預設值。 只有已修改的選項會寫入檔案。 和 CMakeUserPresets.json 都支援 CMakePresets.json Visual Studio 遠端設定廠商對應。

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

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

設定	描述
sourceDir	將複製專案之遠端系統上目錄的路徑。 預設為 $env{HOME}/.vs/$ms{projectDirName}。 此選項支援宏擴充。 在遠端複製案例中，宏 ${sourceDir} 會評估為遠端系統上的專案來原始目錄，而不是 Windows 電腦上的專案來原始目錄。 遠端複製案例包括以遠端 SSH 連線為目標。 在這些情況下，遠端系統上的專案來原始目錄是由 Visual Studio Remote 設定 廠商對應中的 值 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 必須符合 連線ion Manager 中連線的 主機名稱。

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 。