Справочник CMake

CMake — это инструмент, который помогает упростить процесс сборки проектов разработки на различных платформах. CMake автоматизирует генерацию систем сборки, таких как Makefiles и файлы проектов Visual Studio.

CMake — это инструмент сторонних разработчиков со своей собственной документацией. Остальная часть данного руководства подробно описывает особенности использования Qt 5 с CMake. Минимальная необходимая версия для использования Qt5 — CMake 2.8.3, но рекомендуется версия 3.1.0.

Начало работы

Первое требование при использовании CMake — это использование find_package для поиска библиотек и заголовочных файлов, поставляемых с Qt. Эти библиотеки и заголовочные файлы могут затем использоваться для построения библиотек и приложений на основе Qt.

Рекомендуемый способ использования библиотек и заголовочных файлов Qt с CMake 2.8.11 — использование команды target_link_libraries. В CMake 2.8.11 и более поздних версиях эта команда автоматически добавляет соответствующие каталоги включения, определения компиляции, флаг независимого от позиции кода и ссылки на библиотеку qtmain.lib в Windows.

Для построения исполняемого файла графического интерфейса helloworld типичное использование выглядит так:

cmake_minimum_required(VERSION 2.8.11)

project(testproject)

# Find includes in corresponding build directories
set(CMAKE_INCLUDE_CURRENT_DIR ON)
# Instruct CMake to run moc automatically when needed.
set(CMAKE_AUTOMOC ON)

# Find the QtWidgets library
find_package(Qt5Widgets)

# Tell CMake to create the helloworld executable
add_executable(helloworld WIN32 main.cpp)

# Use the Widgets module from Qt 5.
target_link_libraries(helloworld Qt5::Widgets)

Обратите внимание, что установка минимальной необходимой версии CMake в 2.8.11 требуется для автоматической связи с библиотекой qtmain.lib в Windows.

Для успешного использования find_package Qt 5 должен быть найден в каталоге CMAKE_PREFIX_PATH, или переменная Qt5<Модуль>_DIR должна быть установлена в CMake кэше для указания местоположения файла Qt5WidgetsConfig.cmake. Самый простой способ использовать CMake — установить переменную окружения CMAKE_PREFIX_PATH на установленный префикс Qt 5.

Настройка CMAKE_AUTOMOC выполняет автоматическую работу moc при необходимости. Дополнительная информация об этой функции представлена в документации CMake AUTOMOC.

Импортированные цели

Импортированные цели создаются для каждого модуля Qt. Для команд CMake, таких как target_link_libraries, следует отдавать предпочтение именам импортированных целей, вместо использования переменной типа Qt5<Модуль>_LIBRARIES. Фактический путь к библиотеке можно получить, используя свойство LOCATION:

find_package(Qt5Core)

get_target_property(QtCore_location Qt5::Core LOCATION)

Однако, редко требуется полный путь к библиотеке в коде CMake. Большинство CMake API знают об импортированных целях и могут автоматически использовать их вместо полного пути.

Каждый модуль в Qt 5 имеет целевую библиотеку с именем Qt5::<Модуль>, которая может использоваться для этой цели.

Импортированные цели создаются с конфигурациями, с которыми был настроен Qt. То есть, если Qt был настроен с переключателем -debug, будет создана импортированная цель с конфигурацией DEBUG. Если Qt был настроен с переключателем -release, будет создана импортированная цель с конфигурацией RELEASE. Если Qt был настроен с переключателем -debug-and-release (по умолчанию в Windows), то импортированные цели будут созданы с конфигурациями RELEASE и DEBUG.

Если ваш проект имеет пользовательские конфигурации CMake, может потребоваться установить соответствие между вашей пользовательской конфигурацией и конфигурацией Qt (debug или release).

find_package(Qt5Core)

set(CMAKE_CXX_FLAGS_COVERAGE "${CMAKE_CXX_FLAGS_RELEASE} -fprofile-arcs -ftest-coverage")

# set up a mapping so that the Release configuration for the Qt imported target is
# used in the COVERAGE CMake configuration.
set_target_properties(Qt5::Core PROPERTIES MAP_IMPORTED_CONFIG_COVERAGE "RELEASE")

Плагины также доступны как цели IMPORTED в CMake. Модули Qt Network, Qt SQL, Qt GUI и Qt Widgets имеют связанные плагины. Они предоставляют список плагинов в переменной Qt5<Модуль>_PLUGINS.

foreach(plugin ${Qt5Network_PLUGINS})
  get_target_property(_loc ${plugin} LOCATION)
  message("Plugin ${plugin} is at location ${_loc}")
endforeach()

Использование Qt 5 с CMake младше 3.1.0

Qt 5.7 требует поддержки C++11. CMake начиная с версии 3.1.0 неявно добавляет необходимые минимальные флаги компилятора (например, -std=gnu++11) к целевым модулям Qt5. Если вы используете CMake версию старше 3.1.0, вам необходимо самостоятельно добавить необходимые -std=... к целям, связанным с модулями Qt5.

Если вы используете Qt 5.7 и CMake версию выше 3.1.0, и вам нужна более новая версия стандарта C++, используйте способ CMake для выбора версии стандарта или укажите необходимые функции и позвольте CMake вычислить флаги. Пример:

set(CMAKE_CXX_STANDARD 14)

Также см.: Документация CMake cmake-compile-features

Использование Qt 5 с CMake младше 2.8.12

Также необходимо, при использовании более старой версии CMake, добавить Qt5<Модуль>_EXECUTABLE_COMPILE_FLAGS в CMAKE_CXX_FLAGS, чтобы флаги -fPIC добавлялись к флагам компиляции, если необходимо (как это делается по умолчанию с Qt 5).

Использование Qt 5 с CMake младше 2.8.11

Рекомендуемый способ использования библиотек и заголовочных файлов Qt с CMake до версии 2.8.11 — использование макроса qt5_use_modules.

Обратите внимание, что перед использованием макроса необходимо найти модуль Qt с помощью find_package. Полный список опций для команды CMake find_package представлен в документации.

Макрос qt5_use_modules объединяет все переменные, необходимые для использования модуля Qt. Он автоматически находит модули, указанные в командной строке, если они еще не найдены.

find_package(Qt5Widgets)

add_executable(helloworld WIN32 main.cpp)

qt5_use_modules(helloworld Widgets)

Использование Qt 5 с CMake младше 2.8.9

Если используется CMake младше 2.8.9, макрос qt5_use_modules недоступен. Попытка его использовать приведет к ошибке.

Для использования Qt 5 с версиями CMake младше 2.8.9 необходимо использовать команды target_link_libraries, include_directories, и add_definitions, а также вручную указывать требования к moc с помощью qt5_generate_moc или qt5_wrap_cpp:

cmake_minimum_required(VERSION 2.8.3)

project(testproject)

# Find includes in corresponding build directories
set(CMAKE_INCLUDE_CURRENT_DIR ON)

# Find the QtWidgets library
find_package(Qt5Widgets)

# Add the include directories for the Qt 5 Widgets module to
# the compile lines.
include_directories(${Qt5Widgets_INCLUDE_DIRS})

# Use the compile definitions defined in the Qt 5 Widgets module
add_definitions(${Qt5Widgets_DEFINITIONS})

# Add compiler flags for building executables (-fPIE)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${Qt5Widgets_EXECUTABLE_COMPILE_FLAGS}")

qt5_generate_moc(main.cpp main.moc)

# Tell CMake to create the helloworld executable
add_executable(helloworld main.cpp main.moc)

#Link the helloworld executable to the Qt 5 widgets library.
target_link_libraries(helloworld Qt5::Widgets)

Справочник по переменным

Переменные модулей

Результат вызова find_package — это создание импортированных целей для использования с target_link_libraries, заполнение некоторых переменных информацией, необходимой для настройки сборки, и предоставление доступных макросов. Имя импортированной цели для каждого модуля соответствует имени модуля с префиксом 'Qt5::', например Qt5::Widgets. Все переменные, специфичные для пакета, имеют согласованное имя с префиксом имени пакета. Например, вызов find_package(Qt5Widgets) сделает доступными следующие переменные, если модуль успешно найден:

• Qt5Widgets_VERSION Строка, описывающая версию модуля.
• Qt5Widgets_VERSION_STRING То же, что и Qt5Widgets_VERSION. Устаревшее, используйте Qt5Widgets_VERSION.
• Qt5Widgets_LIBRARIES Список библиотек для использования с командой target_link_libraries.
• Qt5Widgets_INCLUDE_DIRS Список каталогов для использования с командой include_directories.
• Qt5Widgets_DEFINITIONS Список определений для использования с add_definitions.
• Qt5Widgets_COMPILE_DEFINITIONS Список определений для использования со свойством COMPILE_DEFINITIONS целевой библиотеки.
• Qt5Widgets_FOUND Булево значение, описывающее, был ли модуль успешно найден.
• Qt5Widgets_EXECUTABLE_COMPILE_FLAGS Строка флагов для использования при построении исполняемых файлов.

Эквивалентные переменные будут доступны для всех пакетов, найденных с помощью вызова find_package. Обратите внимание, что переменные чувствительны к регистру.

Переменные установки

Дополнительно доступны несколько других переменных, которые не относятся к конкретному пакету, а к самой установке Qt.

• QT_VISIBILITY_AVAILABLE Булево значение, описывающее, была ли построена Qt с скрытой видимостью.
• QT_LIBINFIX Строка, содержащая инфикс, используемый в именах библиотек.

Справочник по макросам

Макросы Qt5Core

Макросы, доступные при поиске Qt5Core.

Макросы Qt5Widgets

Макросы, доступные при поиске Qt5Widgets.

Макросы Qt5DBus

Макросы, доступные при поиске Qt5DBus.

Макросы Qt5LinguistTools

Макросы, доступные при обнаружении Qt5LinguistTools.