Карты поставщиков Майкрософт 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. Их невозможно воспроизвести из командной строки.

Настройка	Описание
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-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 необходимо явно указать режим IntelliSense Clang во время сборки с помощью clang или clang-cl.
intelliSenseOptions	Карта дополнительных параметров конфигурации IntelliSense. useCompilerDefaults: bool, указывает, следует ли использовать определения по умолчанию компилятора и пути include для 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, помечены явным образом.

Настройка	Описание
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 не может использовать предустановки, имеющие макросы поставщика за пределами карты поставщика.

Макрос	Описание
$ms{projectDirName}	Возвращает имя открытой папки в Visual Studio. Этот макрос используется для задания значения по умолчанию для sourceDir в сценариях удаленного копирования. Этот макрос не поддерживается Visual Studio Code. Вместо этого используйте ${sourceDirName}.

Переменные среды

Макрос	Описание
$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 в картах поставщиков Майкрософт.