Знакомство с CMake. Часть 1. Установка, CMakeLists.txt, сборка.

Введение.

Многие, кто начинал создавать собственные программы, пользовался какой-либо системой сборки. В общем, система сборки – это набор инструментов, облегчающий работу с компилятором. Это включает в себя компиляцию, линковку, установку, а также сбор исходных файлов для передачи их компилятору и слежение за зависимостями. Также современные системы сборки облегчают работу с библиотеками, позволяют создавать переносимые проекты и выполняют ещё массу других вкусностей. Эта статья посвящена популярной системе сборки CMake и расскажет, как правильно её установить и настроить, а также будет рассмотрен простой пример её использования. Она рассчитана на тех, что хоть немного знаком с понятиями make, Makefile, компиляция, линковка.

Установка в Linux.

Для популярных дистрибутивов Linux типа Debian, Gentoo, Fedora и т.д. CMake давно лежит в официальных репозиториях. Нам нужно всего лишь установить пакет cmake с помощью менеджера пакетов. Как правило, он устанавливается в системные директории, и необходимости править переменные окружения нету. Можете проверить её работоспособность, выполнив

Если же в репозитории нет такого пакета, то можно его собрать вручную. Скачиваем Unix/Linux Source, например, cmake-3.5.0-rc3.tar.gz, распаковываем и собираем:

Если нет необходимости устанавливать в системную /usr директорию, можно в аргументе —prefix прописать нужный корень установки. По умолчанию, без явного указания —prefix, установка будет произведена в /usr/local. -j используется для ускорения сборки, например, на 4-х ядерном процессоре можно указать -j4, и сборка будет вестись параллельно в 4 потока.

Установка в Windows.

Для Windows на сайте CMake лежит установочный файл msi. Рекомендую при установке отметить галочку добавления пути в переменные окружения PATH для всех пользователей. Тогда, после перелогинивания, CMake будет доступен из любого места. Проверить можно, открыв cmd и выполнив тот же

Записки программиста

Основы сборки проектов на С/C++ при помощи CMake

Некоторое время назад мы с вами познакомились с Autotools. Несмотря на то, что Autotools до сих пор используется во многих известных проектах с открытым исходным кодом, инструмент этот трудно назвать особо удобным. Кроме того, нормально работает он только в *nix системах, а в каком-нибудь Windows пользоваться Autotools, скажем так, весьма непросто. В общем, Autotools — это легаси, и нормальные программисты в наше время пытаются использовать CMake или, например, SCons. В этой заметке мы познакомимся с CMake.

Говоря простыми словами, CMake — это такая штука, в которой вы описываете проект, а она вам генерирует Makefile’ы в *nix системах, проекты Visual Studio под Windows, файлы конкретных редакторов и IDE, например Sublime Text, Code::Blocks, Eclipse или KDevelop, и так далее. Несмотря на спорный в некоторых моментах синтаксис, в последнее время CMake становится стандартом де-факто в мире C/C++. В частности, CMake используется в LLVM, Qt, MariaDB, Blender, KiCad, GNU Radio и ряде других проектов. Кроме того, в CLion, IDE для C/C++ от компании JetBrains, по умолчанию также создаются проекты, основанные на CMake.

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

cmake_minimum_required ( VERSION 3.1 )

# так пишутся комментарии

find_library ( PTHREAD_LIBRARY pthread )
find_library ( PCRE_LIBRARY pcre )

include_directories ( include )
set ( CMAKE_CXX_STANDARD 17 )
set ( CMAKE_CXX_STANDARD_REQUIRED on )
set ( CMAKE_CXX_FLAGS » $ -Wall -Wextra -Werror» )

add_executable ( main src/Main.cpp src/HttpServer.cpp )

Хочется надеяться, какая строчка здесь что означает, пояснять не нужно. Затем исходники складываются в каталог src, а заголовочные файлы — в каталог include. Для сборки проекта говорим:

Просто, не правда ли?

Помимо приведенного выше find_library в CMake есть ряд скриптов для подключения конкретных библиотек. В частности, подключение OpenGL осуществляется как-то так:

find_package ( OpenGL REQUIRED )

CMake можно указать конкретный тип Makefile’ов, которые вы хотите получить на выходе:

В частности, многие программисты для ускорения сборки проектов предпочитают использовать Ninja:

Выбор между отладочной и релизной сборкой осуществляется так:

Вместо запуска напрямую make или ninja можно сказать что-то вроде:

Можно выбрать конкретный компилятор для сборки проекта

… а также указать дополнительные флаги компиляции:

В мире C/C++ нередко бывает, что сторонние библиотеки, использующие CMake, подключаются к проекту при помощи сабмодулей Git. Подключение таких библиотек к проекту осуществляется довольно просто:

cmake_minimum_required ( VERSION 2.8 )

include_directories ( deps/algorithms/include )
add_subdirectory ( deps/algorithms/src )

add_executable ( rbtree_example rbtree_example.c )
target_link_libraries ( rbtree_example CAlgorithms )

В свою очередь, у библиотеки файл src/CMakeList.txt должен быть примерно таким:

cmake_minimum_required ( VERSION 2.8 )

add_library ( CAlgorithms STATIC
struct/ilist.c
struct/rbtree.c
struct/htable.c
common/utils.c
)

Вообще, add_subdirectory может принимать путь до любого каталога, в котором есть файл CMakeLists.txt. Это позволяет разбивать проект на подпроекты даже в рамках одного репозитория. Опять же, в случае с библиотеками это позволяет поместить тесты в отдельный подпроект, который не будет собираться при подключении библиотеки в сторонние проекты.

Например, в корне библиотеки CMakeList.txt может быть таким:

cmake_minimum_required ( VERSION 2.8 )

add_subdirectory ( src )
add_subdirectory ( test )

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

cmake_minimum_required ( VERSION 2.8 )

set ( CMAKE_C_FLAGS » $ -O0 -g» )

add_executable ( test_htable test_htable.c )
target_link_libraries ( test_htable CAlgorithms )

add_executable ( test_rbtree test_rbtree.c )
target_link_libraries ( test_rbtree CAlgorithms )

add_test ( test_htable «./test_htable» )
add_test ( test_rbtree «./test_rbtree» )

Запуск тестов осуществляется простой командой:

… выполненной в каталоге build. Если вас интересует тема написания модульных тестов на C++, она более подробно раскрыта в заметке Тестирование кода на C++ с помощью Google Test.

Если же вы используете какой-нибудь PyTest, просто допишите в CMakeList.txt что-то вроде:

find_package ( PythonInterp REQUIRED )

add_test ( NAME python_test
COMMAND py.test —capture=no $ /tests/run.py )

Вывод тестов пишется в файл Testing/Temporary/LastTest.log. Кстати, подробности о переменных окружения, доступных в CMake, таких, как CMAKE_SOURCE_DIR, можно найти здесь.

Помимо рассмотренных выше возможностей часто можно встретить поддержку сборки проектов с различными опциями. В частности, это используется в Assimp и LLDB. При сборке проекта опции выбираются так:

Опции обычно описывают в документации, но в крайнем случае их можно посмотреть и через curses-интерфейс:

В рамках одного поста, конечно, не представляется возможным рассмотреть все возможности CMake. Однако представленной выше информации вам должно вполне хватить в 90% случаев. Полноценные рабочие примеры использования CMake вы найдете, например, в этом, этом, а также в этом репозиториях на GitHub. Примеры использования опций и условных операторов можно найти в репозиториях уже упомянутых Assimp и LLDB. Ну и, конечно же, массу полезного вы найдете на официальном сайте CMake.

А пользуетесь ли вы CMake и если да, используете ли какие-то его возможности, о которых не было рассказано выше?

Installing CMake

There are several ways to install CMake, depending on your platform.

Windows

There are pre-compiled binaries available on the Download page for Windows as MSI packages and ZIP files. One may alternatively download and build CMake from source. The Download page also provides source releases. In order to build CMake from a source tree on Windows, you must first install the latest binary version of CMake because it is used for building the source tree. Once the binary is installed, run it on CMake as you would any other project. Typically this means selecting CMake as the Source directory and then selecting a binary directory for the resulting executables.

Linux, macOS, UNIX

There are pre-compiled binaries available on the Download page for some UNIX platforms. One may alternatively download and build CMake from source. The Download page provides source releases. There are two possible approaches for building CMake from a source tree. If there is no existing CMake installation, a bootstrap script is provided:

(Note: the make install step is optional, cmake will run from the build directory.)

By default bootstrap will build CMake without any debug or optimization flags. To enable optimizations you will need to specify the CMAKE_BUILD_TYPE option to bootstrap like this: ./bootstrap — -DCMAKE_BUILD_TYPE:STRING=Release

For more options with bootstrap, run ./bootstrap —help .

Or, an existing CMake installation can be used to build a new version:

(Note: the make install step is optional, cmake will run from the build directory.) If you are not using the GNU C++ compiler, you need to tell the bootstrap script (or cmake) which compiler you want to use. This is done by setting the environment variables CC and CXX before running it. For example:

Проекты CMake в Visual Studio CMake projects in Visual Studio

CMake — это кроссплатформенное средство с открытым кодом, которое позволяет определять процессы сборки, выполняемые на множестве платформ. CMake is a cross-platform, open-source tool for defining build processes that run on multiple platforms. В этой статье предполагается, что вы уже знакомы с CMake. This article assumes you’re familiar with CMake. См. документацию по CMake для получения дополнительных сведений. For more information about CMake, see the CMake documentation. Рекомендуем воспользоваться учебником по CMake в качестве отправной точки. The CMake tutorial is a good starting point to learn more.

За последние несколько выпусков была улучшена интеграция CMake с Visual Studio. CMake has become more and more integrated with Visual Studio over the past few releases. Чтобы ознакомиться с документацией по предпочтительной версии Visual Studio, используйте селектор Версия. To see the documentation for your preferred version of Visual Studio, use the Version selector control. Он находится в верхней части оглавления на этой странице. It’s found at the top of the table of contents on this page.

Компонент Средства CMake C++ для Windows использует функцию Открыть папку, чтобы напрямую использовать файлы проекта CMake (например, CMakeLists.txt) для IntelliSense и просмотра. The C++ CMake tools for Windows component uses the Open Folder feature to consume CMake project files (such as CMakeLists.txt) directly for the purposes of IntelliSense and browsing. Поддерживаются генераторы Visual Studio и Ninja. Both Ninja and Visual Studio generators are supported. Если вы используете генератор Visual Studio, он создает временный файл проекта и передает его в msbuild.exe. If you use a Visual Studio generator, it generates a temporary project file and passes it to msbuild.exe. Однако проект никогда не загружается для IntelliSense или просмотра. However, the project is never loaded for IntelliSense or browsing purposes. Также можно импортировать существующий кэш CMake. You can also import an existing CMake cache.

Установка Installation

Средства C++ CMake для Windows устанавливаются в рамках рабочих нагрузок Разработка классических приложений на C++ и Разработка приложений для Linux на C++ . C++ CMake tools for Windows is installed as part of the Desktop development with C++ and Linux Development with C++ workloads. Дополнительные сведения см. в статье Кроссплатформенные проекты CMake. For more information, see Cross-platform CMake projects.

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

Если выбрать Файл > Открыть > Папка, чтобы открыть папку, содержащую файл CMakeLists.txt, происходит следующее: When you choose File > Open > Folder to open a folder containing a CMakeLists.txt file, the following things happen:

Visual Studio добавляет пункт CMake в меню Проект с командами для просмотра и редактирования сценариев CMake. Visual Studio adds CMake items to the Project menu, with commands for viewing and editing CMake scripts.

Обозреватель решений отображает структуру папок и файлы. Solution Explorer displays the folder structure and files.

Visual Studio запускает cmake.exe и создает файл кэша CMake (CMakeCache.txt) для конфигурации по умолчанию (x64-Debug). Visual Studio runs cmake.exe and generates the CMake cache file (CMakeCache.txt) for the default (x64 Debug) configuration. В окне вывода отображается командная строка CMake, а также дополнительные выходные данные CMake. The CMake command line is displayed in the Output Window, along with additional output from CMake.

В фоновом режиме Visual Studio индексирует исходные файлы для поддержки функций IntelliSense, просмотра информации, рефакторинга и т. д. In the background, Visual Studio starts to index the source files to enable IntelliSense, browsing information, refactoring, and so on. По мере работы Visual Studio отслеживает изменения в редакторе, а также на диске, чтобы синхронизировать индекс с источниками. As you work, Visual Studio monitors changes in the editor and also on disk to keep its index in sync with the sources.

Вы можете открыть папки, содержащие любое количество проектов CMake. You can open folders containing any number of CMake projects. Visual Studio обнаруживает и настраивает все «корневые» файлы CMakeLists.txt в рабочей области. Visual Studio detects and configures all the «root» CMakeLists.txt files in your workspace. Операции CMake (настройка, сборка, отладка), C++ IntelliSense и просмотр доступны для всех проектов CMake в вашей рабочей области. CMake operations (configure, build, debug), C++ IntelliSense, and browsing are available to all CMake projects in your workspace.

Вы также можете просмотреть проекты, логически упорядоченные по целевым объектам. You can also view your projects organized logically by targets. Выберите Представление целевых объектов из раскрывающегося списка на панели инструментов в обозревателе решений: Choose Targets view from the dropdown in the Solution Explorer toolbar:

Нажмите кнопку Показать все файлы в верхней части Обозревателя решений, чтобы просмотреть все выходные данные, созданные CMake, в папках out/build/ . Click the Show All Files button at the top of Solution Explorer to see all the CMake-generated output in the out/build/ folders.

Visual Studio использует файл конфигурации с именем CMakeSettings.json. Visual Studio uses a configuration file called CMakeSettings.json. Этот файл также позволяет определять и хранить несколько конфигураций сборки и с удобством переключаться между ними в IDE. This file lets you define and store multiple build configurations, and conveniently switch between them in the IDE. Конфигурация — это конструкция Visual Studio, которая инкапсулирует параметры, относящиеся к конкретному типу сборки. A configuration is a Visual Studio construct that encapsulates settings that are specific to a given build type. Параметры используются для настройки параметров командной строки по умолчанию, которые Visual Studio передает в cmake.exe. The settings are used to configure the default command-line options that Visual Studio passes to cmake.exe. Здесь также можно указать дополнительные параметры CMake и определить любые дополнительные переменные. You can also specify additional CMake options here, and define any additional variables you like. Все параметры записываются в кэш CMake как внутренние или внешние переменные. All options are written to the CMake cache either as internal or external variables. В Visual Studio 2019 редактор параметров CMake предоставляет удобный способ изменения параметров. In Visual Studio 2019, the CMake Settings Editor provides a convenient way to edit your settings. Дополнительные сведения см. в статье Настраиваемые параметры CMake. For more information, see Customize CMake settings.

Один параметр, intelliSenseMode , не передается в CMake и используется только в Visual Studio. One setting, intelliSenseMode isn’t passed to CMake, but is used only by Visual Studio.

Используйте файл CMakeLists.txt в каждой папке проекта так же, как в любом проекте CMake. Use the CMakeLists.txt file in each project folder just as you would in any CMake project. Вы можете указывать исходные файлы, находить библиотеки, устанавливать параметры компилятора и компоновщика и указывать другие сведения о системе сборки. You can specify source files, find libraries, set compiler and linker options, and specify other build system-related information.

Чтобы передавать аргументы для исполняемого файла во время отладки, можно использовать другой файл с именем launch.vs.json. To pass arguments to an executable at debug time, you can use another file called launch.vs.json. В некоторых сценариях Visual Studio автоматически создает эти файлы. In some scenarios, Visual Studio automatically generates these files. Вы можете изменить их вручную или даже создать файл самостоятельно. You can edit them manually, or even create the file yourself.

Для других типов проектов «Открыть папку» используются два дополнительных файла JSON: CppProperties.json и tasks.vs.json. For other kinds of Open Folder projects, two additional JSON files are used: CppProperties.json and tasks.vs.json. Ни один из них не связан с проектами CMake. Neither of these are relevant for CMake projects.

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

При открытии существующего файла кэша CMake (CMakeCache. txt) Visual Studio не пытается управлять кэшем и деревом сборки. When you open an existing CMake cache file (CMakeCache.txt), Visual Studio doesn’t try to manage your cache and build tree for you. Настраиваемые или предпочтительные инструменты имеют полный контроль над тем, как CMake настраивает проект. Your custom or preferred tools have complete control over how CMake configures your project. Чтобы открыть существующий кэш в Visual Studio, выберите Файл > Открыть > CMake. To open an existing cache in Visual Studio, choose File > Open > CMake. Затем перейдите к существующему файлу CMakeCache.txt. Then, navigate to an existing CMakeCache.txt file.

Существующий кэш CMake можно добавить в открытый проект. You can add an existing CMake cache to an open project. Этот процесс аналогичен добавлению новой конфигурации. It’s done the same way you’d add a new configuration. Дополнительные сведения см. в записи блога об открытии существующего кэша в Visual Studio. For more information, see our blog post on opening an existing cache in Visual Studio.

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

Для создания проекта CMake доступны следующие варианты: To build a CMake project, you have these choices:

На панели инструментов «Общие» найдите раскрывающийся список Конфигурация. In the General toolbar, find the Configurations dropdown. По умолчанию, возможно, отображается «x64-Debug». It probably shows «x64-Debug» by default. Выберите предпочтительную конфигурацию и нажмите клавишу F5 или кнопку Выполнить (с зеленым треугольником) на панели инструментов. Select the preferred configuration and press F5, or click the Run (green triangle) button on the toolbar. Сначала автоматически выполняется сборка проекта как решения Visual Studio. The project automatically builds first, just like a Visual Studio solution.

Щелкните CMakeLists.txt правой кнопкой мыши и выберите пункт Сборка. Right click on CMakeLists.txt and select Build from the context menu. Если в структуре папок имеется несколько целевых объектов, можно выбрать сборку их всех или только одного из них. If you have multiple targets in your folder structure, you can choose to build all or only one specific target.

В главном меню выберите Сборка > Собрать все (нажмите клавишу F7 или клавиши CTRL+SHIFT+B). From the main menu, select Build > Build All (F7 or Ctrl+Shift+B). Убедитесь, что целевой объект CMake уже выбран в раскрывающемся списке Автозапускаемый элемент на панели инструментов Общие. Make sure that a CMake target is already selected in the Startup Item dropdown in the General toolbar.

Как и следовало ожидать, результаты сборки отображаются в окне вывода и списке ошибок. As you would expect, build results are shown in the Output Window and Error List.

В папке с несколькими целевыми объектами сборки можно указать целевой объект CMake для сборки: Выберите элемент Сборка в меню CMake или контекстном меню CMakeLists.txt, чтобы указать целевой объект. In a folder with multiple build targets, you can specify which CMake target to build: Choose the Build item on the CMake menu or the CMakeLists.txt context menu to specify the target. Нажмите клавиши CTRL+SHIFT+B в проекте CMake, чтобы выполнить сборку текущего активного документа. If you enter Ctrl+Shift+B in a CMake project, it builds the current active document.

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

Для отладки проекта CMake выберите требуемую конфигурацию и нажмите клавишу F5 или кнопку Выполнить на панели инструментов. To debug a CMake project, choose the preferred configuration and press F5, or press the Run button in the toolbar. Если для кнопки Выполнить отображается сообщение «Выбрать элемент запуска», выберите стрелку раскрывающегося списка. If the Run button says «Select Startup Item», select the dropdown arrow. Выберите нужный целевой объект. Choose the target that you want to run. (В проекте CMake параметр «Текущий документ» допустим только для файлов CPP.) (In a CMake project, the «Current document» option is only valid for .cpp files.)

Команды Выполнить или F5 сначала выполняют сборку проекта, если с момента предыдущей сборки были внесены изменения. The Run or F5 commands first build the project if changes have been made since the previous build. Изменения в CMakeSettings.json вызывают повторное создание кэша CMake. Changes to CMakeSettings.json cause the CMake cache to be regenerated.

Вы можете настроить сеанс отладки CMake, задав свойства в файле launch.vs.json. You can customize a CMake debugging session by setting properties in the launch.vs.json file. Дополнительные сведения см. в разделе Настройка сеансов отладки CMake. For more information, see Configure CMake debugging sessions.

«Только мой код» для проектов CMake Just My Code for CMake projects

При сборке для Windows с помощью компилятора MSVC в проектах CMake поддерживается отладка «Только мой код». When you build for Windows using the MSVC compiler, CMake projects have support for Just My Code debugging. Чтобы изменить параметр «Только мой код», перейдите в раздел Сервис > Параметры > Отладка > Общие. To change the Just My Code setting, go to Tools > Options > Debugging > General.

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

Если вы установили vcpkg, то проекты CMake, открытые в Visual Studio, автоматически интегрируют файл цепочки инструментов vcpkg. If you have installed vcpkg, CMake projects opened in Visual Studio automatically integrate the vcpkg toolchain file. Это означает, что для использования vcpkg с проектами CMake не требуется дополнительная настройка. That means no additional configuration is required to use vcpkg with your CMake projects. Эта поддержка работает как для локальных установок vcpkg, так и для vcpkg в удаленных системах, которые вы намерены использовать. This support works for both local vcpkg installations and vcpkg installations on remote systems that you’re targeting. Это поведение автоматически отключается при указании любых других цепочек инструментов в конфигурации параметров CMake. This behavior is disabled automatically when you specify any other toolchain in your CMake Settings configuration.

Отзывы о настройке конфигурации Customize configuration feedback

По умолчанию большинство сообщений конфигурации подавляются, если нет ошибки. By default, most configuration messages are suppressed unless there’s an error. Чтобы просмотреть все сообщения, включите эту функцию в разделе Средства > Параметры > CMake. You can see all messages by enabling this feature in Tools > Options > CMake.

Изменение файлов CMakeLists.txt Editing CMakeLists.txt files

Чтобы изменить файл CMakeLists.txt, щелкните его правой кнопкой мыши в обозревателе решений и выберите пункт Открыть. To edit a CMakeLists.txt file, right-click on the file in Solution Explorer and choose Open. Если вы вносите изменения в файл, отображается желтая строка состояния, которая сообщает о предстоящем обновлении IntelliSense. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. Это дает возможность отменить операцию обновления. It gives you a chance to cancel the update operation. Сведения о CMakeLists.txt см. в документации по CMake. For information about CMakeLists.txt, see the CMake documentation.

Сразу после сохранения файла автоматически перезапускается этап настройки, отображающий информацию в окне вывода. As soon as you save the file, the configuration step automatically runs again and displays information in the Output window. Ошибки и предупреждения отображаются в списке ошибок или окне вывода. Errors and warnings are shown in the Error List or Output window. Дважды щелкните ошибку в окне Список ошибок, чтобы перейти к строке с ошибкой в CMakeLists.txt. Double-click on an error in the Error List to navigate to the offending line in CMakeLists.txt.

Шаг настройки CMake CMake configure step

При внесении существенных изменений в файл CMakeSettings.json или CMakeLists.txt Visual Studio автоматически перезапускает шаг настройки CMake. When you make significant changes to the CMakeSettings.json or to CMakeLists.txt files, Visual Studio automatically reruns the CMake configure step. Если шаг настройки завершается без ошибок, собранные данные становятся доступны в C++ IntelliSense и языковых службах. If the configure step finishes without errors, the information that’s collected is available in C++ IntelliSense and language services. Они также используются в операциях сборки и отладки. It’s also used in build and debug operations.

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

Если вам нужны дополнительные сведения о состоянии кэша CMake для диагностики проблемы, откройте главное меню Проект или контекстное меню CMakeLists.txt в обозревателе решений, чтобы выполнить одну из следующих команд: If you need more information about the state of the CMake cache to diagnose a problem, open the Project main menu or the CMakeLists.txt context menu in Solution Explorer to run one of these commands:

Просмотреть кэш открывает файл CMakeCache.txt из корневой папки сборки в редакторе. View Cache opens the CMakeCache.txt file from the build root folder in the editor. (Любые внесенные здесь изменения в CMakeCache.txt удаляются при очистке кэша. (Any edits you make here to CMakeCache.txt are wiped out if you clean the cache. Сведения о внесении изменений, сохраняемых после очистки кэша, см. в разделе Настройка параметров CMake.) To make changes that persist after the cache is cleaned, see Customize CMake settings.)

Открыть папку кэша открывает окно проводника с корневой папкой сборки. Open Cache Folder opens an Explorer window to the build root folder.

Очистить кэш удаляет корневую папку сборки, чтобы следующий шаг настройки CMake начинался с очистки кэша. Clean Cache deletes the build root folder so that the next CMake configure step starts from a clean cache.

Создать кэш принудительно создает шаг для выполнения, даже если Visual Studio считает среду актуальной. Generate Cache forces the generate step to run even if Visual Studio considers the environment up to date.

Вы можете отключить автоматическое создание кэша в диалоговом окне Сервис > Параметры > CMake > Общие. Automatic cache generation can be disabled in the Tools > Options > CMake > General dialog.

Запуск CMake из командной строки Run CMake from the command line

Если вы установили CMake из Visual Studio Installer, можете запустить это средство из командной строки, сделав следующее: If you have installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps:

Запустите соответствующий файл vsdevcmd.bat (x86 или x64). Run the appropriate vsdevcmd.bat (x86/x64). Дополнительные сведения см. в статье Сборка из командной строки. For more information, see Building on the Command Line.

Перейдите в папку выходных данных. Switch to your output folder.

Запустите CMake для создания или настройки приложения. Run CMake to build/configure your app.

В Visual Studio 2017 существует широкая поддержка CMake, включая кроссплатформенные проекты CMake. Visual Studio 2017 has rich support for CMake, including cross-platform CMake projects. Компонент Инструменты Visual C++ для CMake использует функцию Открыть папку, чтобы позволить интегрированной среде разработки использовать файлы проекта CMake (например, CMakeLists.txt) для IntelliSense и просмотра. The Visual C++ Tools for CMake component uses the Open Folder feature to enable the IDE to consume CMake project files (such as CMakeLists.txt) directly for the purposes of IntelliSense and browsing. Поддерживаются генераторы Visual Studio и Ninja. Both Ninja and Visual Studio generators are supported. Если вы используете генератор Visual Studio, он создает временный файл проекта и передает его в msbuild.exe. If you use a Visual Studio generator, it generates a temporary project file and passes it to msbuild.exe. Однако проект никогда не загружается для IntelliSense или просмотра. However, the project is never loaded for IntelliSense or browsing purposes. Также можно импортировать существующий кэш CMake. You also can import an existing CMake cache.

Установка Installation

Средства Visual C++ для CMake устанавливаются в рамках рабочих нагрузок Разработка классических приложений на C++ и Разработка приложений для Linux на C++ . Visual C++ Tools for CMake is installed as part of the Desktop development with C++ and Linux Development with C++ workloads.

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

Если выбрать Файл > Открыть > Папка, чтобы открыть папку, содержащую файл CMakeLists.txt, происходит следующее: When you choose File > Open > Folder to open a folder containing a CMakeLists.txt file, the following things happen:

Visual Studio добавляет пункт CMake в главное меню с командами для просмотра и редактирования сценариев CMake. Visual Studio adds a CMake menu item to the main menu, with commands for viewing and editing CMake scripts.

Обозреватель решений отображает структуру папок и файлы. Solution Explorer displays the folder structure and files.

Visual Studio запускает CMake.exe и при необходимости создает кэш CMake для конфигурации по умолчанию, которой является отладка x86. Visual Studio runs CMake.exe and optionally generates the CMake cache for the default configuration, which is x86 Debug. В окне вывода отображается командная строка CMake, а также дополнительные выходные данные CMake. The CMake command line is displayed in the Output Window, along with additional output from CMake.

В фоновом режиме Visual Studio индексирует исходные файлы для поддержки функций IntelliSense, просмотра информации, рефакторинга и т. д. In the background, Visual Studio starts to index the source files to enable IntelliSense, browsing information, refactoring, and so on. По мере работы Visual Studio отслеживает изменения в редакторе, а также на диске, чтобы синхронизировать индекс с источниками. As you work, Visual Studio monitors changes in the editor and also on disk to keep its index in sync with the sources.

Вы можете открыть папки, содержащие любое количество проектов CMake. You can open folders containing any number of CMake projects. Visual Studio обнаруживает и настраивает все «корневые» файлы CMakeLists.txt в рабочей области. Visual Studio detects and configures all the «root» CMakeLists.txt files in your workspace. Операции CMake (настройка, сборка, отладка), C++ IntelliSense и просмотр доступны для всех проектов CMake в вашей рабочей области. CMake operations (configure, build, debug), C++ IntelliSense, and browsing are available to all CMake projects in your workspace.

Вы также можете просмотреть проекты, логически упорядоченные по целевым объектам. You can also view your projects organized logically by targets. Выберите Представление целевых объектов из раскрывающегося списка на панели инструментов в обозревателе решений: Choose Targets view from the dropdown in the Solution Explorer toolbar:

Visual Studio использует файл с именем CMakeSettings.json для хранения переменных среды или параметров командной строки для Cmake.exe. Visual Studio uses a file called CMakeSettings.json to store environment variables or command-line options for Cmake.exe. CMakeSettings.json также позволяет определить и сохранить несколько конфигураций сборки CMake. CMakeSettings.json also enables you to define and store multiple CMake build configurations. Вы можете легко переключаться между ними в интегрированной среде разработки. You can conveniently switch between them in the IDE.

Или используйте CMakeLists.txt так же, как в любом проекте CMake, чтобы указывать исходные файлы, находить библиотеки, устанавливать параметры компилятора и компоновщика и указывать другие сведения о системе сборки. Otherwise, use the CMakeLists.txt just as you would in any CMake project to specify source files, find libraries, set compiler and linker options, and specify other build system-related information.

Чтобы передавать аргументы для исполняемого файла во время отладки, можно использовать другой файл с именем launch.vs.json. If you need to pass arguments to an executable at debug time, you can use another file called launch.vs.json. В некоторых сценариях Visual Studio автоматически создает эти файлы. In some scenarios, Visual Studio automatically generates these files. Вы можете изменить их вручную или даже создать файл самостоятельно. You can edit them manually, or even create the file yourself.

Для других типов проектов «Открыть папку» используются два дополнительных файла JSON: CppProperties.json и tasks.vs.json. For other kinds of Open Folder projects, two additional JSON files are used: CppProperties.json and tasks.vs.json. Ни один из них не связан с проектами CMake. Neither of these are relevant for CMake projects.

Импорт существующего кэша Import an existing cache

Когда вы импортируете существующий файл CMakeCache.txt, Visual Studio автоматически извлекает настраиваемые переменные и создает на их основе предварительно заполненный файл CMakeSettings.json. When you import an existing CMakeCache.txt file, Visual Studio automatically extracts customized variables and creates a pre-populated CMakeSettings.json file based on them. Исходный кэш никак не изменяется. The original cache isn’t modified in any way. Его по-прежнему можно использовать из командной строки или с помощью любого средства или интегрированной среды разработки, которые использовались для его создания. It can still be used from the command line, or with whatever tool or IDE used to generate it. Новый файл CMakeSettings.json помещается рядом с корневым файлом CMakeLists.txt проекта. The new CMakeSettings.json file is placed alongside the project’s root CMakeLists.txt. Visual Studio создает кэш на основе файла параметров. Visual Studio generates a new cache based the settings file. Вы можете переопределить автоматическое создание кэша в диалоговом окне Сервис > Параметры > CMake > Общие. You can override automatic cache generation in the Tools > Options > CMake > General dialog.

Импортируется не все содержимое кэша. Not everything in the cache is imported. Такие свойства, как генератор и расположение компиляторов, заменяются значениями по умолчанию, хорошо совместимыми с данной интегрированной средой разработки. Properties such as the generator and the location of the compilers are replaced with defaults that are known to work well with the IDE.

Импорт существующего кэша To import an existing cache

В главном меню выберите Файл > Открыть > CMake: From the main menu, choose File > Open > CMake:

Эта команда открывает мастер импорта CMake из кэша. This command brings up the Import CMake from Cache wizard.

Перейдите к файлу CMakeCache.txt, который хотите импортировать, и нажмите кнопку ОК. Navigate to the CMakeCache.txt file that you want to import, and then click OK. Отображается мастер импорта CMake из кэша: The Import CMake Project from Cache wizard appears:

По завершении работы мастера вы увидите новый файл CMakeCache.txt в обозревателе решений рядом с корневым файлом CMakeLists.txt в проекте. When the wizard completes, you can see the new CMakeCache.txt file in Solution Explorer next to the root CMakeLists.txt file in your project.

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

Для создания проекта CMake доступны следующие варианты: To build a CMake project, you have these choices:

На панели инструментов «Общие» найдите раскрывающийся список Конфигурация. In the General toolbar, find the Configurations dropdown. По умолчанию, скорее всего, отображается «Linux-Debug» или «x64-Debug». It’s probably showing «Linux-Debug» or «x64-Debug» by default. Выберите предпочтительную конфигурацию и нажмите клавишу F5 или кнопку Выполнить (с зеленым треугольником) на панели инструментов. Select the preferred configuration and press F5, or click the Run (green triangle) button on the toolbar. Сначала автоматически выполняется сборка проекта как решения Visual Studio. The project automatically builds first, just like a Visual Studio solution.

Щелкните CMakeLists.txt правой кнопкой мыши и выберите пункт Сборка. Right click on the CMakeLists.txt and select Build from the context menu. Если в структуре папок имеется несколько целевых объектов, можно выбрать сборку их всех или только одного из них. If you have multiple targets in your folder structure, you can choose to build all or only one specific target.

В главном меню выберите Сборка > Собрать решение (нажмите клавишу F7 или клавиши CTRL+SHIFT+B). From the main menu, select Build > Build Solution (F7 or Ctrl+Shift+B). Убедитесь, что целевой объект CMake уже выбран в раскрывающемся списке Автозапускаемый элемент на панели инструментов Общие. Make sure that a CMake target is already selected in the Startup Item dropdown in the General toolbar.

Вы можете настраивать конфигурации сборки, переменные среды, аргументы командной строки и другие параметры в файле CMakeSettings.json. You can customize build configurations, environment variables, command-line arguments, and other settings in the CMakeSettings.json file. Это позволяет вносить изменения, не изменяя файл CMakeLists.txt. It lets you make changes without modifying the CMakeLists.txt file. Дополнительные сведения см. в статье Настраиваемые параметры CMake. For more information, see Customize CMake settings.

Как и следовало ожидать, результаты сборки отображаются в окне вывода и списке ошибок. As you would expect, build results are shown in the Output Window and Error List.

В папке с несколькими целевыми объектами сборки можно указать целевой объект CMake для сборки: Выберите элемент Сборка в меню CMake или контекстном меню CMakeLists.txt, чтобы указать целевой объект. In a folder with multiple build targets, you can specify which CMake target to build: Choose the Build item on the CMake menu or the CMakeLists.txt context menu to specify the target. Нажмите клавиши CTRL+SHIFT+B в проекте CMake, чтобы выполнить сборку текущего активного документа. If you enter Ctrl+Shift+B in a CMake project, it builds the current active document.

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

Для отладки проекта CMake выберите требуемую конфигурацию и нажмите клавишу F5. To debug a CMake project, choose the preferred configuration and press F5. Или нажмите кнопку Выполнить на панели инструментов. Or, press the Run button in the toolbar. Если для кнопки Выполнить отображается сообщение «Выбрать элемент запуска», выберите стрелку раскрывающегося списка и выберите целевой объект, который требуется запустить. If the Run button says «Select Startup Item», select the dropdown arrow and choose the target that you want to run. (В проекте CMake параметр «Текущий документ» допустим только для файлов CPP.) (In a CMake project, the «Current document» option is only valid for .cpp files.)

Команды Выполнить или F5 сначала выполняют сборку проекта, если с момента предыдущей сборки были внесены изменения. The Run or F5 commands first build the project if changes have been made since the previous build.

Вы можете настроить сеанс отладки CMake, задав свойства в файле launch.vs.json. You can customize a CMake debugging session by setting properties in the launch.vs.json file. Дополнительные сведения см. в разделе Настройка сеансов отладки CMake. For more information, see Configure CMake debugging sessions.

Изменение файлов CMakeLists.txt Editing CMakeLists.txt files

Чтобы изменить файл CMakeLists.txt, щелкните его правой кнопкой мыши в обозревателе решений и выберите пункт Открыть. To edit a CMakeLists.txt file, right-click on the file in Solution Explorer and choose Open. Если вы вносите изменения в файл, отображается желтая строка состояния, которая сообщает о предстоящем обновлении IntelliSense. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. Это дает возможность отменить операцию обновления. It gives you a chance to cancel the update operation. Сведения о CMakeLists.txt см. в документации по CMake. For information about CMakeLists.txt, see the CMake documentation.

Сразу после сохранения файла автоматически перезапускается этап настройки, отображающий информацию в окне вывода. As soon as you save the file, the configuration step automatically runs again and displays information in the Output window. Ошибки и предупреждения отображаются в списке ошибок или окне вывода. Errors and warnings are shown in the Error List or Output window. Дважды щелкните ошибку в окне Список ошибок, чтобы перейти к строке с ошибкой в CMakeLists.txt. Double-click on an error in the Error List to navigate to the offending line in CMakeLists.txt.

Шаг настройки CMake CMake configure step

При внесении существенных изменений в файл CMakeSettings.json или CMakeLists.txt Visual Studio автоматически перезапускает шаг настройки CMake. When significant changes are made to the CMakeSettings.json or to CMakeLists.txt files, Visual Studio automatically reruns the CMake configure step. Если шаг настройки завершается без ошибок, собранные данные становятся доступны в C++ IntelliSense и языковых службах. If the configure step finishes without errors, the information that’s collected is available in C++ IntelliSense and language services. Они также используются в операциях сборки и отладки. It’s also used in build and debug operations.

Несколько проектов CMake могут использовать одно и то же имя конфигурации CMake (например, x86-Debug). Multiple CMake projects may use the same CMake configuration name (for example, x86-Debug). При выборе этой конфигурации все они настраиваются и собираются (в собственной корневой папке сборки). All of them are configured and built (in their own build root folder) when that configuration is selected. Вы можете отлаживать целевые объекты изо всех проектов CMake, участвующих в этой конфигурации CMake. You can debug the targets from all of the CMake projects that participate in that CMake configuration.


Можно ограничить сеансы сборки и отладки подмножеством проектов в рабочей области. You can limit builds and debug sessions to a subset of the projects in the workspace. Создайте новую конфигурацию с уникальным именем в файле CMakeSettings.json. Create a new configuration with a unique name in the CMakeSettings.json file. Затем примените конфигурацию только к этим проектам. Then, apply the configuration to those projects only. При выборе этой конфигурации IntelliSense, а также команды сборки и отладки применяются только для указанных проектов. When that configuration is selected, IntelliSense and the build and debug commands only apply to those specified projects.

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

Если вам нужны дополнительные сведения о состоянии кэша CMake для диагностики проблемы, откройте главное меню CMake или контекстное меню CMakeLists.txt в обозревателе решений, чтобы выполнить одну из следующих команд: If you need more information about the state of the CMake cache to diagnose a problem, open the CMake main menu or the CMakeLists.txt context menu in Solution Explorer to run one of these commands:

Просмотреть кэш открывает файл CMakeCache.txt из корневой папки сборки в редакторе. View Cache opens the CMakeCache.txt file from the build root folder in the editor. (Любые внесенные здесь изменения в CMakeCache.txt удаляются при очистке кэша. (Any edits you make here to CMakeCache.txt are wiped out if you clean the cache. Сведения о внесении изменений, сохраняемых после очистки кэша, см. в разделе Настройка параметров CMake.) To make changes that persist after the cache is cleaned, see Customize CMake settings.)

Открыть папку кэша открывает окно проводника с корневой папкой сборки. Open Cache Folder opens an Explorer window to the build root folder.

Очистить кэш удаляет корневую папку сборки, чтобы следующий шаг настройки CMake начинался с очистки кэша. Clean Cache deletes the build root folder so that the next CMake configure step starts from a clean cache.

Создать кэш принудительно создает шаг для выполнения, даже если Visual Studio считает среду актуальной. Generate Cache forces the generate step to run even if Visual Studio considers the environment up to date.

Вы можете отключить автоматическое создание кэша в диалоговом окне Сервис > Параметры > CMake > Общие. Automatic cache generation can be disabled in the Tools > Options > CMake > General dialog.

Компиляция одного файла Single file compilation

Для сборки отдельного файла в проекте CMake щелкните правой кнопкой мыши файл в обозревателе решений. To build a single file in a CMake project, right-click on the file in Solution Explorer. Выберите Компилировать во всплывающем меню. Choose Compile from the pop-up menu. Вы также можете скомпилировать открытый в редакторе файл через главное меню CMake: You can also build the currently open file in the editor by using the main CMake menu:

Запуск CMake из командной строки Run CMake from the command line

Если вы установили CMake из Visual Studio Installer, можете запустить это средство из командной строки, сделав следующее: If you have installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps:

Запустите соответствующий файл vsdevcmd.bat (x86 или x64). Run the appropriate vsdevcmd.bat (x86/x64). Дополнительные сведения см. в статье Сборка из командной строки. For more information, see Building on the command line .

Перейдите в папку выходных данных. Switch to your output folder.

Запустите CMake для создания или настройки приложения. Run CMake to build/configure your app.

В Visual Studio 2015 пользователи Visual Studio могут использовать генератор CMake для создания файлов проекта MSBuild, которые интегрированная среда разработки использует для IntelliSense, просмотра и компиляции. In Visual Studio 2015, Visual Studio users can use a CMake generator to generate MSBuild project files, which the IDE then consumes for IntelliSense, browsing, and compilation.