Карты поставщиков Майкрософт CMakePresets.json и CMakeUserPresets.json
CMake поддерживает два файла: CMakePresets.json и CMakeUserPresets.json, которые позволяют пользователям указывать общие параметры настройки, сборки и тестирования, а также делиться ими с другими пользователями.
CMakePresets.json и CMakeUserPresets.json могут использоваться для управления CMake в Visual Studio, в Visual Studio Code, в конвейере непрерывной интеграции (CI) и из командной строки.
CMakePresets.json предназначен для сохранения сборок на уровне проекта, а CMakeUserPresets.json предназначен для разработчиков, позволяя им сохранять собственные локальные сборки. Схема для обоих файлов идентична.
CMakePresets.json и CMakeUserPresets.json поддерживают хранение сведений, относящихся к поставщику, в самих картах поставщиков. Корпорация Майкрософт поддерживает две карты поставщиков с параметрами, специфичными для Visual Studio и Visual Studio Code. Здесь мы рассмотрим две карты поставщиков Майкрософт и макросы поставщиков. Дополнительные сведения об оставшейся части схемы см. в официальной документации по CMake. Содержит сведения о настройках предустановках, предустановках сборки и тестовых предустановках.
Дополнительные сведения об использовании CMakePresets.json в Visual Studio см. в статье Настройка и сборка с помощью предустановок CMake
Дополнительные сведения об использовании CMakePresets.json в Visual Studio Code см. в статье Настройка и сборка с помощью предустановок CMake в VS Code
Карта поставщика параметров Visual Studio
Для каждой предопределенной конфигурации допускается одна карта поставщика с URI поставщика microsoft.com/VisualStudioSettings/CMake/<version>, которая также содержит параметры, относящиеся к интеграции CMake в Visual Studio и Visual Studio Code. Все параметры в карте поставщика применяются к Visual Studio. Параметры, применяемые к Visual Studio и Visual Studio Code, помечены явным образом.
Все параметры в карте поставщика параметров Visual Studio являются необязательными и наследуются от предустановок настройки, заданных ключом inherits. В файл записываются только измененные параметры. Карта поставщика параметров Visual Studio поддерживается как в CMakePresets.json, так и в CMakeUserPresets.json.
Параметры в карте поставщика параметров Visual Studio не влияют на конструкцию CMake или командной строки CTest. То есть один и тот же файл CMakePresets.json можно использовать для управления CMake с помощью Visual Studio, Visual Studio Code и из командной строки. Исключениями являются параметры cacheRoot и cmakeGenerateCommand. Эти параметры относятся к сценарию открытия существующего кэша в Visual Studio. Их невозможно воспроизвести из командной строки.
| Параметр | Description |
|---|---|
hostOS |
Массив поддерживаемых операционных систем (ОС). Допустимые значения: Windows, Linux и macOS.Значение hostOS используется Visual Studio и Visual Studio Code для скрытия предустановок настройки, которые не применяются к ОС целевой системы и обеспечивают большее удобство использования.Если параметр hostOS не указан, Visual Studio и Visual Studio Code будут всегда показывать все предустановки настройки для выбора. Это поле также может быть строкой, которая эквивалентна массиву, содержащему одну строку.Этот параметр поддерживается как в Visual Studio, так и в Visual Studio Code. |
intelliSenseMode |
Задает режим, используемый для вычисления сведений IntelliSense в Visual Studio в формате <target>-<toolset>-<arch>. Допустимые значения: android-clang-armandroid-clang-arm64android-clang-x6android-clang-x86ios-clang-arios-clang-arm64ios-clang-x6ios-clang-x86linux-gcc-armlinux-gcc-x64linux-gcc-x86windows-clang-armwindows-clang-arm64windows-clang-x64windows-clang-x86windows-msvc-armwindows-msvc-arm64windows-msvc-x64windows-msvc-x86Если параметр intelliSenseMode не указан, Visual Studio будет использовать режим IntelliSense, соответствующий указанным компиляторам и целевой архитектуре. intelliSenseMode часто используется, чтобы обеспечить улучшенную технологию IntelliSense для перекрестной компиляции.В Visual Studio 2019 необходимо явно указать режим IntelliSense Clang во время сборки с помощью clang или clang-cl. |
intelliSenseOptions |
Карта дополнительных параметров конфигурации IntelliSense.useCompilerDefaults: указывает bool , следует ли использовать компилятор по умолчанию определяет и включает пути для IntelliSense. Значение false следует задавать только в том случае, если используемые компиляторы не поддерживают аргументы в стиле gcc. По умолчанию — true.additionalCompilerArgs: массив дополнительных параметров для управления IntelliSense в Visual Studio. Этот параметр поддерживает расширение макросов. |
enableMicrosoftCodeAnalysis |
bool, который включает анализ кода Майкрософт в Visual Studio при сборке с использованием cl или clang-cl. По умолчанию — false. |
codeAnalysisRuleset |
Указывает набор правил для использования при выполнении анализа кода Майкрософт в Visual Studio. Можно использовать путь к файлу набора правил или имя файла набора правил, установленного с помощью Visual Studio. Этот параметр поддерживает расширение макросов. |
disableExternalAnalysis |
Значение типа bool, указывающее, должен ли анализ кода запускаться для внешних заголовков в Visual Studio. |
codeAnalysisExternalRuleset |
Указывает набор правил для использования при выполнении анализа кода Майкрософт во внешнем заголовке в Visual Studio. Можно использовать путь к файлу набора правил или имя файла набора правил, установленного с помощью Visual Studio. Этот параметр поддерживает расширение макросов. |
enableClangTidyCodeAnalysis |
Логическое значение, которое включает анализ кода clang-tidy в Visual Studio при сборке с использованием clang-cl. По умолчанию — false. |
clangTidyChecks |
Разделенный запятыми список предупреждений, передаваемых в clang-tidy при выполнении анализа кода clang-tidy в Visual Studio. Допускаются подстановочные знаки, а префикс - удаляет проверки. |
cacheRoot |
Задает путь к кэшу CMake. Этот каталог должен содержать существующий файл CMakeCache.txt. Этот ключ поддерживается только в сценарии открытия существующего кэша в Visual Studio. Этот параметр поддерживает расширение макросов. |
cmakeGenerateCommand |
Средство командной строки (указанное в качестве программы командной строки + аргументы, например gencache.bat debug) для создания кэша CMake. Эта команда выполняется в оболочке, использующей указанную среду предустановки при вызове настроек CMake. Этот ключ поддерживается только в сценарии открытия существующего кэша в Visual Studio. Этот параметр поддерживает расширение макросов. |
Карта поставщика удаленных параметров Visual Studio
Для каждой предопределенной конфигурации допускается одна схема поставщика с URI поставщика microsoft.com/VisualStudioRemoteSettings/CMake/<version>, которая также содержит параметры, относящиеся к удаленной разработке в Visual Studio. Удаленная разработка означает, что вы вызываете CMake через удаленное SSH-подключение или WSL. Ни один из параметров в карте поставщика удаленных параметров Visual Studio не применяется к Visual Studio Code.
Все параметры в карте поставщика удаленных параметров Visual Studio являются необязательными и наследуются от предустановок настройки, заданных ключом inherits. В файл записываются только измененные параметры. Карта поставщика удаленных параметров Visual Studio поддерживается как в CMakePresets.json, так и в CMakeUserPresets.json.
Параметры в карте поставщика параметров Visual Studio не влияют на конструкцию CMake или командной строки CTest. То есть один и тот же файл CMakePresets.json можно использовать для управления CMake с помощью Visual Studio, Visual Studio Code и из командной строки.
Многие параметры в карте поставщика удаленных параметров Visual Studio игнорируются, когда целевой платформой является WSL1. Это связано с тем, что набор инструментов WSL1 выполняет все команды локально и использует диски Windows, подключенные к папке /mnt, для доступа к локальным исходным файлам из WSL1. Копировать исходный файл не требуется. Параметры, которые игнорируются, когда целевой платформой является WSL1, помечены явным образом.
| Параметр | Description |
|---|---|
sourceDir |
Путь к каталогу в удаленной системе, куда будет скопирован проект. По умолчанию — $env{HOME}/.vs/$ms{projectDirName}. Этот параметр поддерживает расширение макросов.В сценариях удаленного копирования макрос ${sourceDir} оценивает исходный каталог проекта в удаленной системе, а не исходный каталог проекта на компьютере Windows. Сценарии удаленного копирования включают в себя назначение удаленного SSH-подключения. В таких случаях исходный каталог проекта в удаленной системе определяется значением sourceDir в карте поставщика удаленных параметров Visual Studio. Этот параметр игнорируется, когда целевой платформой является 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 всегда будет использовать набор инструментов WSL1 при нацеливании на WSL из Visual Studio. Набор инструментов WSL1 выполняет все команды локально и использует диски Windows, подключенные к папке /mnt, для доступа к локальным исходным файлам из WSL. Эти параметры могут работать медленнее с WSL2. По умолчанию — false.В Visual Studio 2019 версии 16.10 всегда будет использоваться набор инструментов WSL1. Этот параметр будет важен после того, как будет доступна собственная поддержка WSL2. |
Удаленные события перед сборкой и после сборки
Параметры для remotePrebuildEvent и remotePostbuildEvent больше не рекомендуются при внедрении CMakePresets.json.
Используйте кодирование событий перед сборкой, перед компоновкой и после сборки в CMakeLists.txt с помощью add_custom_command. Это обеспечит такое же поведение при построении с помощью Visual Studio и из командной строки.
Если требуется поведение, характерное для Visual Studio, можно добавить пользовательскую удаленную задачу в tasks.vs.json. Чтобы начать работу, щелкните правой кнопкой мыши корень CMakeLists.txt в обозревателе решений из представления папки и выберите пункт Настроить задачи. Затем можно добавить новую удаленную задачу в файл tasks.vs.json.
Следующая удаленная задача создает каталог с именем test в удаленной системе Linux:
{
"taskLabel": "mkdir",
"appliesTo": "CMakeLists.txt",
"type": "remote",
"command": "mkdir test",
"remoteMachineName": "localhost"
}
Щелкните любой элемент CMakeLists.txt правой кнопкой мыши и выберите параметр mkdir, чтобы выполнить эту задачу.
Значение remoteMachineName должно соответствовать имени узла соединения в диспетчере подключений.
Макросы поставщиков Майкрософт
Две карты поставщиков Майкрософт, Visual Studio Settings и Visual Studio Remote Settings, поддерживают все макросы, определенные с помощью CMake. Наши карты поставщиков поддерживают все макросы, определенные с помощью CMake. Дополнительные сведения см. в разделе Расширение макросов предустановок CMake. Все макросы и переменные среды расширяются до их передачи в CMake.
Visual Studio поддерживает макросы поставщика с префиксом ms. Макросы поставщиков Майкрософт можно использовать только в картах поставщиков Майкрософт. CMake не может использовать предустановки, имеющие макросы поставщика за пределами карты поставщика.
| Макрос | Description |
|---|---|
$ms{projectDirName} |
Возвращает имя открытой папки в Visual Studio. Этот макрос используется для задания значения по умолчанию для sourceDir в сценариях удаленного копирования. Этот макрос не поддерживается Visual Studio Code. Вместо этого используйте ${sourceDirName}. |
Переменные среды
| Макрос | Description |
|---|---|
$env{<variable-name>}$penv{<variable-name>} |
Ссылочные переменные среды, использующие этот синтаксис, поддерживаются CMake. Дополнительные сведения см. в разделе Расширение макросов предустановок CMake. |
Устаревшие макросы
Некоторые макросы, поддерживаемые CMakeSettings.json, не рекомендуется использовать при внедрении CMakePresets.json.
Используйте макросы, поддерживаемые CMake, для создания путей к файлам. Использование этих макросов позволяет гарантировать, что один и тот же файл CMakePresets.json будет работать и в Visual Studio, и из командной строки.
| Устаревший макрос | Рекомендация |
|---|---|
${projectFile} |
${sourceDir}/CMakeLists.txt |
${thisFile} |
${sourceDir}/CMakePresets.json |
Допустимый синтаксис оболочки
Используйте синтаксис $env{HOME}, чтобы сослаться на $HOME при создании путей Linux в картах поставщиков Майкрософт.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по