Проекты 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++.

В установщике выбран раскрывающийся список "Рабочий стол" с помощью C плюс плюс C плюс C Make tools for Windows".

Дополнительные сведения см. в разделе Установка рабочей нагрузки 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 и нажмите клавишу ВВОД, чтобы открыть представление целевых объектов:

Нажмите кнопку Показать все файлы в верхней части Обозревателя решений, чтобы просмотреть все выходные данные, созданные 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. Вы можете вызвать шаг настройки вручную: выберите "Настройка кэша проекта>" на панели инструментов. Вы также можете изменить параметры конфигурации в разделе "Параметры CMake">, а также в разделе "Параметры>CMake".>

Параметры настройки CMake вызываются. Выбраны уведомления кэша C Make. В разделе "Когда кэш устарел:" выбран параметр "Никогда не запускать шаг настройки автоматически".

Если шаг настройки завершается без ошибок, имеющиеся данные становятся доступны в 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 о преобразованиях, которые могут привести к потере данных, например преобразованию из float в целое число, видны. :::image-end:::

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

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

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

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

В раскрывающемся списке есть следующие параметры: отображение и скрытие целевых объектов отладки, текущий документ, примеры (выделенные), box2d_tests и примеры noGUI.

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

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

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

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

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

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

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-подключениях см. в разделе Диспетчер подключений

В диалоговом окне доступны следующие параметры: тип подключения (для параметра SSH), целевой объект подключения (для параметра demo@ 172. 20. 60. 6) и список доступных процессов, к которому можно подключиться".

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

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

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

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

Вы можете получить доступ CMakeWorkspaceSettings.json к команде меню параметров рабочей области Project>CMake в любое время, даже если функция 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.

Он содержит проект строк (hello-cmake), add_subdirectory (тесты), add_executable (hello hello.cpp) и установку (TARGETS hello DESTINATION hello/bin). Сообщение в верхней части окна говорит, что данные c плюс IntelliSense будут обновляться после завершения создания кэша C Make.

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

Выделено сообщение об ошибке C Make в строке 3 CMakeLists.txt. Сведения о том, что C Make не удалось найти файл конфигурации пакета, предоставленный sqlite3. C Make искал его в CMAKE_MODULE_PATH, но не смог найти его. Предложение заключается в добавлении префикса установки "sqlite3" для CMAKE_PREFIX_PATH или задания sqlite3_DIR в каталог, содержащий sqlite3Config.cmake и/или sqlitet3-config.cmake.

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

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

Результаты отображения SUPERTUX_SOURCES_CXX. Например, в list(SORT SSUPERTUX_SOURCES_CXX), file(GLOB SUPERTUX_SOURCES_CXX) и т. д.

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

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

В представлении дерева отображаются CMakeLists.txt, под которыми находятся два элемента: add_executable и набор. Установлен флажок. В окне предварительного просмотра показано, где будут вноситься изменения. Набор строк (PROJECT_SRC "CmakeProject4.cpp" CMakeProject4.h отображает значение "Demo.cpp" перед закрывающей скобкой. Кнопка "Применить" принимает изменение или можно нажать кнопку отмены.

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 см. в следующих статье:

• Установка и использование пакетов с CMake в Visual Studio
• vcpkg в проектах CMake

Если 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
vcpkg в проектах CMake
Установка и использование пакетов с CMake в Visual Studio