Проекты CMake в Visual Studio

CMake — это кроссплатформенное средство с открытым кодом, которое позволяет определять процессы сборки, выполняемые на множестве платформ. В этой статье предполагается, что вы уже знакомы с CMake. См. документацию по CMake для получения дополнительных сведений. Рекомендуем воспользоваться учебником по CMake в качестве отправной точки.

Примечание

За последние несколько выпусков была улучшена интеграция CMake с Visual Studio. Чтобы ознакомиться с документацией по предпочтительной версии Visual Studio, используйте селектор Версия. Он находится в верхней части оглавления на этой странице.

Встроенная поддержка CMake в Visual Studio позволяет изменять проекты CMake, а также выполнять их сборку и отладку в Windows, в подсистеме Windows для Linux (WSL) и в удаленных системах из одного и того же экземпляра Visual Studio. Файлы проекта CMake (например, CMakeLists.txt ) используются непосредственно Visual Studio в целях IntelliSense и для обзора. cmake.exe вызывается напрямую средой Visual Studio для конфигурации и сборки CMake.

Установка

Средства C++ CMake для Windows устанавливаются в рамках рабочих нагрузок Разработка классических приложений на C++ и Разработка приложений для Linux на C++ . Для кроссплатформенного развертывания с использованием CMake требуются инструменты C++ CMake для Windows и разработка Linux на C++ .

Дополнительные сведения см. в разделе Установка рабочей нагрузки Linux для проектов C++ в Visual Studio.

Интеграция с IDE

Если открыть папку, содержащую файл CMakeLists.txt , происходит следующее:

• Visual Studio добавляет пункт CMake в меню Проект с командами для просмотра и редактирования сценариев CMake.

• В обозревателе решений отображаются структура папок и файлы.

• Visual Studio запускает CMake и создает файл кэша CMake ( CMakeCache.txt ) для конфигурации по умолчанию. В окне вывода отображается командная строка CMake, а также прочие выходные данные CMake.

• В фоновом режиме Visual Studio индексирует исходные файлы для поддержки функций IntelliSense, просмотра информации, рефакторинга и т. д. По мере работы Visual Studio отслеживает изменения в редакторе, а также на диске, чтобы синхронизировать индекс с источниками.

Примечание

Начиная с Visual Studio 2022 версии 17.1 , предварительная версия 2, если ваш верхний уровень CMakeLists.txt существует во вложенной папке, а не в корне рабочей области, вам будет предложено включить интеграцию CMake или нет. Дополнительные сведения см. в разделе Частичная активация CMake.

После успешного создания кэша CMake можно также просмотреть проекты, логически упорядоченные по целевым объектам. Нажмите кнопку Выбрать вид на панели инструментов Обозреватель решений. В списке в Обозреватель решений — Представления выберите CMake Targets View (Представление целевых объектов CMake) и нажмите клавишу ВВОД, чтобы открыть представление целевых объектов:

Нажмите кнопку Показать все файлы в верхней части Обозревателя решений, чтобы просмотреть все выходные данные, созданные CMake, в папках out/build/<config> .

Используйте файл CMakeLists.txt в каждой папке проекта так же, как в любом проекте CMake. Вы можете указывать исходные файлы, находить библиотеки, устанавливать параметры компилятора и компоновщика и указывать другие сведения о системе сборки. Дополнительные сведения о языковых службах CMake, предоставляемых Visual Studio, см. в разделе Редактирование файлов CMakeLists.txt.

Visual Studio использует файл конфигурации CMake для управления созданием кэша CMake и его сборкой. Дополнительные сведения см. в статьях Настройка проектов CMake и Создание проектов CMake.

При передаче аргументов для исполняемого файла во время отладки, можно использовать другой файл с именем launch.vs.json . Дополнительные сведения об отладке кроссплатформенных проектов CMake в Visual Studio см. в разделе Отладка проектов CMake.

Большинство функций Visual Studio и языка C++ поддерживаются проектами CMake в Visual Studio. Примеры приведены ниже:

• Изменение и продолжение проектов CMake

• Интеграция IncrediBuild для проектов CMake

• Поддержка AddressSanitizer для проектов CMake

• Поддержка Clang/LLVM

Примечание

Для других проектов в виде папок используется дополнительный файл JSON CppProperties.json . Этот файл не относится к проектам CMake.

Настройка проектов CMake

На этапе настройки CMake создается система сборки проекта. Это эквивалентно вызову cmake.exe из командной строки. Дополнительные сведения о шаге настройки CMake см. в документации по CMake.

Visual Studio использует файл конфигурации CMake для управления созданием CMake и его сборкой. CMakePresets.json поддерживается в Visual Studio 2019 версии 16.10 или более поздней и является рекомендуемом файлом конфигурации CMake. CMakePresets.json поддерживается непосредственно CMake и может использоваться для создания и сборки CMake из Visual Studio, ИЗ VS Code, в конвейере непрерывной интеграции, а также из командной строки в Windows, Linux и Mac. Дополнительные сведения о см. в CMakePresets.jsonразделе Настройка и сборка с помощью предустановок CMake. CMakeSettings.json доступен для клиентов, использующих более раннюю версию Visual Studio. Дополнительные сведения о см. в CMakeSettings.jsonразделе Настройка параметров сборки CMake.

При внесении значительных изменений в файл конфигурации CMake или файл CMakeLists.txt среда Visual Studio автоматически запустит этап настройки CMake. Вы можете вызвать шаг настройки вручную: выберите Project Configure Cache (Настройка кэша проекта>) на панели инструментов. Вы также можете изменить параметры конфигурации в разделе Сервис>Параметры>CMake>General.

Если шаг настройки завершается без ошибок, имеющиеся данные становятся доступны в C++ IntelliSense и языковых службах. Они также используются в операциях сборки и отладки.

Можно также открыть существующий кэш CMake в Visual Studio. Дополнительные сведения см. в статье Открытие существующего кэша.

Отзывы и уведомления о настройке конфигурации

По умолчанию большинство сообщений конфигурации подавляются, если нет ошибки. Чтобы просмотреть все сообщения, выберите Сервис>Параметры>CMake>Включить подробные выходные диагностические данные CMake.

Можно также отключить все уведомления кэша CMake (полоски золотистого цвета), сняв флажок Показать уведомления кэша CMake.

Устранение ошибок кэша CMake

Если вам нужны дополнительные сведения о состоянии кэша CMake для диагностики проблемы, откройте главное меню Проект или контекстное меню CMakeLists.txt в обозревателе решений, чтобы выполнить одну из следующих команд:

• Параметр Просмотреть CMakeCache.txt позволяет открыть в редакторе файл CMakeCache.txt из каталога сборки. Любые внесенные здесь изменения в CMakeCache.txt удаляются при очистке кэша. Чтобы внести изменения, которые сохраняются после очистки кэша, см. статью Настройка параметров CMake или Настройка и сборка с помощью предустановок CMake.

• Параметр Удаление кэша и перенастройка позволяет удалить каталог сборки и выполнить повторную настройку из чистого кэша.

• Параметр Создать кэшпозволяет принудительно создать шаг для выполнения, даже если Visual Studio считает среду актуальной.

Создание проектов CMake

На этапе сборки CMake создается уже сгенерированное двоичное дерево проекта. Это эквивалентно вызову cmake --build из командной строки. Дополнительные сведения о шаге сборки CMake см. в документации по CMake.

Для создания проекта CMake доступны следующие варианты:

1. На панели инструментов найдите раскрывающийся список Автозапускаемый элемент. Выберите предпочтительный целевой объект и нажмите клавишу F5 или кнопку Выполнить на панели инструментов. Сначала автоматически выполняется сборка проекта как решения Visual Studio.

2. Щелкните правой кнопкой мыши целевой объект CMake, для которого в обозревателе решений активен параметр Просмотр целевых объектов CMake и выберите в контекстном меню пункт Сборка.

3. В главном меню выберите Сборка > все. Убедитесь, что целевой объект CMake уже выбран в раскрывающемся списке Автозапускаемый элемент на панели инструментов.

Как и следовало ожидать, результаты сборки отображаются в окне вывода и списке ошибок.

Изменение параметров сборки

Для управления сборками CMake Visual Studio использует файл конфигурации CMake. Файлы конфигурации CMake инкапсулируют параметры сборки, такие как параметры машинного кода и переменные среды сборки. Если CMakePresets.json является активным файлом конфигурации, см. статью Настройка и сборка с помощью предустановок CMake. Если CMakeSettings.json является активным файлом конфигурации, см . раздел Настройка параметров сборки CMake. CMakePresets.json доступен в Visual Studio 2019 версии 16.10 или более поздней. Это рекомендуемый файл конфигурации CMake.

Отладка проектов CMake

Все исполняемые целевые объекты CMake отображаются в раскрывающемся списке Автозапускаемый элемент в панели инструментов. Чтобы начать отладку, выберите один из них и нажмите кнопку Отладка > Начать отладку на панели инструментов. В проекте CMake параметр "Текущий документ" допустим только для файлов CPP.

Команды Отладка или F5 сначала выполняют сборку проекта, если с момента предыдущей сборки были внесены изменения. Изменения в файле конфигурации CMake (CMakePresets.json или CMakeSettings.json) или CMakeLists.txt вызывают повторное создание кэша CMake.

Вы можете настроить сеанс отладки CMake, задав свойства в файле launch.vs.json. Чтобы настроить параметры отладки для определенного целевого объекта, выберите целевой объект в раскрывающемся списке Элемент запуска и нажмите кнопки Отладка > Отладка и Параметры запуска для <активного целевого объекта>. Дополнительные сведения о сеансах отладки CMake см. в разделе Настройка сеансов отладки CMake.

"Только мой код" для проектов CMake

При сборке для Windows с помощью компилятора MSVC в проектах CMake поддерживается отладка "Только мой код". Чтобы изменить параметр "Только мой код", перейдите в раздел Сервис>Параметры>Отладка>Общие.

Изменение и продолжение проектов CMake

При сборке для Windows с помощью компилятора MSVC в проектах CMake предусмотрена поддержка функции "Изменение и продолжение". Добавьте следующий код в файл CMakeLists.txt , чтобы включить функцию "Изменение и продолжение".

if(MSVC)
  target_compile_options(<target> PUBLIC "/ZI")
  target_link_options(<target> PUBLIC "/INCREMENTAL")
endif()

Подключение к проекту CMake, запущенному в Linux

Visual Studio позволяет выполнять отладку процесса, выполняющегося в удаленной системе Linux или WSL, и отлаживать его с помощью отладчика GDB. Для начала выберите Отладка>Подключение к процессу, задайте для параметра Тип подключения значение SSH и выберите Цель подключения из списка в диспетчере подключений. Выберите процесс из списка доступных процессов и нажмите кнопку Подключить. На компьютере Linux должен быть установлен GDB. Дополнительные сведения о SSH-подключениях см. в разделе Диспетчер подключений

Частичная активация CMake

В Visual Studio 2022 версии 17.1 и более поздних функция CMake не будет включена автоматически, если корневая CMakeLists.txt папка не содержит файл. Вместо этого появится диалоговое окно с запросом на включение функций CMake для проекта. Если вы отклоните, создание кэша CMake не запустится, а конфигурации CMake (из CMakeSettings.json или CMakePresets.json) не будут отображаться в раскрывающемся списке конфигурации. Если вы согласитесь, вы перейдете в файл CMakeWorkspaceSettings.json конфигурации уровня рабочей области (хранящийся в .vs каталоге), чтобы указать папки, для которые вы хотите включить CMake. (Эти папки содержат корневые CMakeLists.txt файлы.)

Допустимые свойства:

Свойство	Описание
enableCMake	Включите интеграцию Visual Studio для этой рабочей области.
sourceDirectory	Строка или массив строк, указывающих каталог или каталоги с CMakeLists.txtпомощью . Макросы (например, ${workspaceRoot}) разрешены. Относительные пути основаны на корневом каталоге рабочей области. Каталоги за пределами текущей рабочей области будут игнорироваться.

Вы можете получить доступ CMakeWorkspaceSettings.json с помощью > команды менюProject CMake Workspace Settings в любое время, даже если функции CMake в настоящее время отключены.

Открытие существующего кэша

При открытии существующего файла кэша CMake ( CMakeCache.txt ) Visual Studio не пытается управлять кэшем и деревом сборки. Настраиваемые или предпочтительные инструменты имеют полный контроль над тем, как CMake настраивает проект.

Существующий кэш CMake можно добавить в открытый проект. Этот процесс аналогичен добавлению новой конфигурации. Дополнительные сведения см. в записи блога об открытии существующего кэша в Visual Studio.

Примечание

По умолчанию для работы с существующим кэшем используется режим cmake-server, который был удален из CMake в версии 3.20. Чтобы продолжить использовать эти функции в Visual Studio 2019 версии 16.10 и выше, выполните одно из следующих действий:

• Установите CMake версии 3.19 или ниже вручную. Затем в конфигурации существующего кэша задайте свойство cmakeExecutable так, чтобы использовать эту версию CMake.
• В конфигурации существующего кэша задайте свойство cacheGenerationCommand, чтобы позволить Visual Studio запрашивать нужные файлы для файлового API-интерфейса CMake. Дополнительные сведения об этом свойстве см. в Справочнике по CMakeSettings.json.
• Используйте файл запроса, чтобы запрашивать файлы для файлового API-интерфейса CMake при создании кэша перед его открытием в Visual Studio. Инструкции по файлу запроса см. в следующем разделе Дополнительные способы устранения неполадок с кэшем CMake.

Дополнительные способы устранения неполадок с кэшем CMake

Visual Studio использует API на основе файлов в CMake (версия 3.14 и более поздние) для заполнения редактора сведениями, связанными со структурой проекта. Дополнительные сведения см. в записи блога команды C++, посвященной использованию рабочих областей с несколькими корнями и API на основе файлов.

Перед созданием кэша CMake вашим пользовательским или предпочтительным средствам может потребоваться создать файл запроса с именем .cmake/api/v1/query/client-MicrosoftVS/query.json в выходной папке сборки (папке, содержащей CMakeCache.txt ). Файл запроса должен содержать следующее содержимое:

{"requests":[{"kind":"cache","version":2},{"kind":"cmakeFiles","version":1},{"kind":"codemodel","version":2}]}

Когда пользовательские или предпочтительные средства создают ваш кэш, CMake помещает файлы в расположение .cmake/api/v1/response , которое Visual Studio использует для заполнения редактора сведениями, связанными со структурой вашего проекта.

Редактирование CMakeLists.txt файлов

Чтобы изменить файл CMakeLists.txt , щелкните его правой кнопкой мыши в обозревателе решений и выберите пункт Открыть. Если вы вносите изменения в файл, отображается желтая строка состояния, которая сообщает о предстоящем обновлении IntelliSense. Это дает возможность отменить операцию обновления. Дополнительные сведения о CMakeLists.txt см. в документации по Windows.

Сразу после сохранения файла автоматически перезапускается этап настройки, отображающий информацию в окне вывода. Ошибки и предупреждения отображаются в списке ошибок или окне вывода. Дважды щелкните ошибку в окне Список ошибок, чтобы перейти к строке с ошибкой в CMakeLists.txt .

Языковые службы для CMake

Языковые службы для CMake доступны в Visual Studio 2019 версии 16.5 или более поздней. Он поддерживает такие функции навигации по коду, как Перейти к определению, Показать определение и Найти все ссылки для переменных, функций и целевых объектов CMake в файлах скриптов CMake. Дополнительные сведения см. в разделе Навигация по коду для сценариев CMake.

Управление проектами CMake

Управление проектами CMake доступно в Visual Studio 2019 версии 16.5 или более поздней. С помощью функции управления проектами можно добавлять, удалять и переименовывать исходные файлы и целевые объекты в проектах CMake без изменения сценариев CMake вручную. При добавлении или удалении файлов из Обозреватель решений Visual Studio автоматически изменяет проект CMake. Существует несколько мест, где имеет смысл добавить или удалить ссылку на скрипт CMake. Если это так, Visual Studio спросит, где вы хотите внести изменения, и отобразит предварительный просмотр предлагаемых изменений. Пошаговые инструкции см. в разделе Простое добавление, удаление и переименование файлов и целевых объектов в проектах CMake.

IntelliSense для проектов CMake

По умолчанию Visual Studio использует режим IntelliSense, соответствующий компилятору и целевой архитектуре, заданным активной конфигурацией CMake.

Если CMakePresets.json является активным файлом конфигурации CMake, можно указать параметры IntelliSense с помощью intelliSenseMode и intelliSenseOptions на карте поставщика параметров Visual Studio. Дополнительные сведения см. в справочнике по карте поставщиков параметров Visual Studio.

Если CMakeSettings.json является активным файлом конфигурации CMake, можно указать параметры IntelliSense с помощью intelliSenseMode в CMakeSettings.json. Дополнительные сведения см. в справочникеCMakeSettings.json.

Настройка IntelliSense с помощью файлов цепочки инструментов CMake

В Visual Studio 2019 версии 16.9 и более поздних visual Studio автоматически настраивает IntelliSense в проектах CMake на основе переменных CMake при использовании файла цепочки инструментов CMake. Дополнительные сведения см. в статье Настройка IntelliSense с помощью файла цепочки инструментов CMake.

Интеграция с vcpkg

Проекты CMake, открытые в Visual Studio интегрируются с vcpkg, с помощью кроссплатформенного диспетчера зависимостей C/C++. Прежде чем приступить к использованию vcpkg с Visual Studio, необходимо выполнить команду vcpkg integrate install. Инструкции и дополнительные сведения о vcpkg см. в документации по vcpkg.

Если CMakeSettings.json является активным файлом конфигурации, Visual Studio автоматически передает файл цепочки инструментов vcpkg (vcpkg.cmake) в CMake. Это поведение автоматически отключается при указании любых других цепочек инструментов в конфигурации параметров CMake.

Если CMakePresets.json является активным файлом конфигурации, необходимо задать путь к vcpkg.cmake в CMakePresets.json. Чтобы сохранить общий доступ к файлу, рекомендуется использовать переменную среды VCPKG_ROOT вместо абсолютного пути. Дополнительные сведения см. в разделе Включение интеграции vcpkg с предварительными настройками CMake. CMakePresets.json доступен в Visual Studio 2019 версии 16.10 или более поздней. Это рекомендуемый файл конфигурации CMake.

Запуск CMake из командной строки

Если CMakePresets.json является активным файлом конфигурации CMake, вы можете легко воспроизвести локальные сборки за пределами Visual Studio. Дополнительные сведения см. в разделе Запуск CMake из командной строки или конвейера непрерывной интеграции. CMakePresets.json поддерживается в Visual Studio 2019 версии 16.10 или более поздней и является рекомендуемой конфигурацией CMake.

Если CMakeSettings.json является активным файлом конфигурации CMake, необходимо вручную передать аргументы, закодированные в файле CMakeSettings.json , в CMake. Если вы установили CMake из Visual Studio Installer, можете запустить это средство из командной строки, сделав следующее:

1. Запустите соответствующий файл vsdevcmd.bat (x86/x64). Дополнительные сведения см. в статье Сборка из командной строки.

2. Перейдите в папку выходных данных.

3. Запустите CMake, чтобы создать или настроить приложение.

См. также

Учебник. Создание кроссплатформенных проектов C++ в Visual Studio
Настройка проекта Linux CMake
Подключение к удаленному компьютеру Linux
Настройка параметров сборки CMake
CMakeSettings.jsonСправочник схем
Настройка сеансов отладки CMake
Развертывание, запуск и отладка проекта Linux
Справочник по предопределенной конфигурации CMake