Skip to main content
Перейти к содержимому
Редактировать эту страницу See source code Создать задачу по документации Formatting guidelines Style guidelines

Понимание CMakeLists

Знакомство с принципами работы файлов CMakeLists.txt

CMake

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

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

Корневой файл CMakeLists.txt

Возможно, этот файл CMakeLists.txt уже встречался в первом руководстве:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
    Core
    Quick
    Test
    Gui
    QuickControls2
    Widgets
)

find_package(KF6 REQUIRED COMPONENTS
    Kirigami
    I18n
    CoreAddons
    QQC2DesktopStyle
    IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

Первая строка, cmake_minimum_required(), задаёт версию CMake, которая будет использоваться.

После этого project(kirigami-tutorial) задаёт имя проекта.

Затем идёт раздел, в котором с помощью extra-cmake-modules подключается ряд необходимых параметров CMake и KDE. Они предоставляют набор полезных утилит:

  • KDEInstallDirs предоставляет удобные переменные, такие как ${KDE_INSTALL_TARGETS_DEFAULT_ARGS}, ${KDE_INSTALL_QMLDIR}, ${KDE_INSTALL_BINDIR} и ${KDE_INSTALL_LIBDIR}.
  • KDECMakeSettings предоставляет такие возможности, как CMAKE_AUTORCC ON, цель uninstall, которую можно использовать с cmake --build build/ --target uninstall, и ENABLE_CLAZY.
  • KDECompilerSettings задаёт минимальный стандарт C++, флаги компилятора, такие как -pedantic, и макросы рекомендуемых практик, например -DQT_NO_CAST_FROM_ASCII, требующие явных преобразований, таких как QStringLiteral().
  • ECMFindQmlModule позволяет убедиться, что зависимость QML времени выполнения будет найдена во время сборки.
  • ECMQmlModule предоставляет команды CMake, такие как ecm_add_qml_module() и ecm_target_qml_sources().

Следующий раздел важен, так как в нём указывается, какие зависимости будут подключены во время сборки. Рассмотрим первую:

13
14
15
16
17
18
19
20
21
22
23
24
25
26

find_package(Qt6 REQUIRED COMPONENTS
    Core
    Quick
    Test
    Gui
    QuickControls2
    Widgets
)

find_package(KF6 REQUIRED COMPONENTS
    Kirigami
    I18n
    CoreAddons
    QQC2DesktopStyle
  • find_package() находит и загружает внешнюю библиотеку и её компоненты.
  • REQUIRED предписывает CMake завершить работу с ошибкой, если пакет не найден.
  • COMPONENTS — параметр, предшествующий конкретным компонентам подключаемого фреймворка.
  • Каждое слово после COMPONENTS обозначает конкретный компонент библиотеки.

Строка install указывает CMake установить файл .desktop в ${KDE_INSTALL_APPDIR}, что в Linux соответствует $XDG_DATA_DIRS/applications, обычно /usr/share/applications, а в Windows — C:/Program Files/${PROJECT_NAME}/bin/data/applications:

34

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

Последняя строка позволяет CMake вывести, какие пакеты найдены, а при возникновении ошибки сборка немедленно прерывается:

36

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

А выше этого add_subdirectory(src) указывает CMake на папку src/, где обнаруживается ещё один файл CMakeLists.txt.

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
    URI
    org.kde.tutorial
)

target_sources(kirigami-hello
    PRIVATE
    main.cpp
)

ecm_target_qml_sources(kirigami-hello
    SOURCES
    Main.qml
)

target_link_libraries(kirigami-hello
    PRIVATE
    Qt6::Quick
    Qt6::Qml
    Qt6::Gui
    Qt6::QuickControls2
    Qt6::Widgets
    KF6::I18n
    KF6::CoreAddons
    KF6::IconThemes
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Первый файл отвечал за метаданные и поиск библиотек, а этот — за обработку зависимостей и установку приложения. В нём используются следующие вызовы CMake:

  • add_executable() создаёт исполняемую цель, которая будет использоваться для запуска проекта.
  • ecm_add_qml_module() создаёт цель модуля QML, доступную через импорт «org.kde.tutorial».
  • target_sources() добавляет исходные файлы C++ в исполняемую цель.
  • ecm_target_qml_sources() добавляет файлы QML в модуль.
  • target_link_libraries() связывает используемые в коде библиотеки C++ с исполняемым файлом. Kirigami здесь не включён, поскольку используется только его модуль QML.
  • install() устанавливает исполняемый файл в систему.

Документация по двум командам ECM приведена в API extra-cmake-modules для ECMQmlModule.

Здесь вызов ecm_add_qml_module() использован для изменения традиционной исполняемой цели с исходным кодом C++ и превращения её в нечто, способное принимать файлы QML и исходный код C++, доступный из QML, — это называется использованием исполняемого файла в качестве опорной цели модуля QML. Это означает, что файлы QML выполняются непосредственно как часть приложения, что для приложений обычное дело.

Можно также создать с помощью ecm_add_qml_module() отдельный модуль QML, который не использует исполняемый файл в качестве опорной цели. В этом случае создаётся цель библиотеки с помощью add_library(), она связывается с существующей исполняемой целью с помощью target_link_libraries(), а помимо установки библиотеки с помощью install() потребуется завершить модуль QML с помощью ecm_finalize_qml_module(), чтобы создать два файла: qmldir и qmltypes. Эти файлы используются приложениями QtQuick для поиска отдельных модулей QML.

Способ создания отдельного модуля QML нагляднее показан в руководстве Использование отдельных файлов.

Это дополнения, предоставляемые extra-cmake-modules для упрощения использования декларативной регистрации Qt (замены файлов ресурсов Qt).

Документацию по всем трём командам можно найти в API extra-cmake-modules для ECMQmlModule.

src/components/CMakeLists.txt

В руководстве о том, как разделить свой код на отдельные файлы, был представлен новый файл CMake, позволяющий использовать отдельные модули QML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
    URI "org.kde.tutorial.components"
    GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
    SOURCES
    AddDialog.qml
    KountdownDelegate.qml
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Чтобы CMake прочитал этот файл, в src/CMakeLists.txt нужно добавить вызов add_subdirectory(), указывающий на него.

Создаётся новая цель с именем kirigami-hello-components, которая затем преобразуется в модуль QML с помощью ecm_add_qml_module() под именем импорта org.kde.tutorial.components, и добавляются соответствующие файлы QML.

Вызов add_library() создаёт новую цель с именем kirigami-hello-components. У этой цели будет собственный набор файлов исходного кода и файлов QML, собственные библиотеки для компоновки и так далее, но после компиляции её нужно скомпоновать с исполняемым файлом, созданным в src/CMakeLists.txt. Для этого имя цели добавляется в список библиотек, которые будут скомпонованы с исполняемым файлом в target_link_libraries().

Вызов ecm_add_qml_module() изменяет библиотеку так, чтобы она, как и прежде, принимала файлы QML, но на этот раз требуется использовать GENERATE_PLUGIN_SOURCE. Когда исполняемый файл используется в качестве опорной цели (как в kirigami-hello), создавать код подключаемого модуля не требуется, поскольку он встроен в исполняемый файл; при отдельных модулях QML, таких как kirigami-hello-components, код подключаемого модуля необходим.

В вышестоящем Qt qt_add_qml_module() по умолчанию создаёт подключаемый модуль вместе с модулем QML, но ecm_add_qml_module() из KDE по умолчанию этого не делает для обратной совместимости.

Для отдельных модулей QML также необходимо завершить цель. В основном это означает, что CMake создаёт два файла, qmldir и qmltypes, которые описывают имеющиеся модули QML и экспортируют их символы для использования в библиотеке. Они важны при установке приложения, чтобы запускаемый исполняемый файл мог найти, где находятся файлы QML для каждого модуля, поэтому они автоматически добавляются к цели.

Затем достаточно установить цель, как и раньше.

Когда в следующий раз потребуется добавить дополнительные файлы QML, не забудьте включить их в этот файл. Файлы C++, в которых используется ключевое слово QML_ELEMENT, которое будет рассмотрено значительно позже в руководстве, также можно добавить здесь с помощью target_sources(). Код можно логически разделить, создав дополнительные модули QML с другими импортами по мере необходимости.

Эта настройка пригодится при разработке большинства приложений Kirigami.

Previous
Представления списков
Next
Разбор main.cpp