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 組態選項對應。useCompilerDefaults bool :,指定是否要使用編譯器預設定義並包含 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
。