Поделиться через

Карты поставщиков Майкрософт 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-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 , следует ли использовать компилятор по умолчанию определяет и включает пути для 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 в картах поставщиков Майкрософт.