cmake-module-integration.qdoc

Go to the documentation of this file.

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qtqml-modules-cmake-integration.html
\title Tying it all together with CMake
\brief Building QML modules with CMake
 
The \l{qt_add_qml_module} CMake command is the recommended way to define QML
modules. It automates type registration, resource embedding, plugin creation,
and tooling integration. This page explains the concepts behind
\c{qt_add_qml_module} and walks through common usage patterns.
 
For the full reference of all options, see \l{qt_add_qml_module}.
 
\section1 Key Concepts
 
Before looking at examples, it helps to understand what \c{qt_add_qml_module}
actually creates:
 
\list
\li A \e{backing target} — a library (or executable) containing the module's
    C++ code, compiled QML files, and resources. This is the first argument to
    \c{qt_add_qml_module} and is the target you link against. It can either
    be an existing target (created earlier with \c{qt_add_executable} or
    \c{qt_add_library}) or \c{qt_add_qml_module} will create it for you.
\li A \e{plugin target} — a small library that allows the QML engine to load
    the module dynamically at run time. It is created automatically and is
    separate from the backing target. When an executable links directly to the
    backing target, the plugin is not loaded at run time. The plugin can be
    omitted entirely using \l{qt_add_qml_module}{NO_PLUGIN}.
\li A \e{qmldir file} — a module metadata file that tells the QML engine what
    types the module provides and where to find them. It is generated
    automatically.
\li A \e{typeinfo file} (\c{.qmltypes}) — machine-readable type information
    used by QML tooling (\l{qmlcachegen}, \l{qmllint}, \l{\QMLLS}{qmlls},
    Qt Creator). Also generated automatically.
\endlist
 
\section1 Directory Structure
 
The source directory structure should mirror the module's URI. The URI is
converted to a path by replacing dots with forward slashes. For example, a
module with URI \c{MyCompany.Controls} should live in:
 
\badcode
src/MyCompany/Controls/CMakeLists.txt
src/MyCompany/Controls/Button.qml
src/MyCompany/Controls/mywidget.cpp
src/MyCompany/Controls/mywidget.h
\endcode
 
This convention allows the QML engine and tooling to find modules without
additional configuration. If your directory structure doesn't match the URI,
you'll need to set \l{OUTPUT_DIRECTORY} so that the build output lands in a
path matching the URI, and \l{IMPORT_PATH} so that the QML engine and tooling
can locate the module.
 
\section1 Common Patterns
 
\section2 QML-only Application
 
The simplest case: an executable with only QML files and no C++ types.
 
\badcode
cmake_minimum_required(VERSION 3.16)
project(myapp LANGUAGES CXX)
 
find_package(Qt6 REQUIRED COMPONENTS Quick)
qt_standard_project_setup(REQUIRES 6.8)
 
qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES
        Main.qml
        Button.qml
    RESOURCES
        images/logo.png
)
 
target_link_libraries(myapp PRIVATE Qt6::Quick)
\endcode
 
Because the backing target is an executable, no plugin is created. The QML
files are compiled and embedded as resources. The \c{RESOURCES} keyword adds
non-QML files (images, fonts, etc.) to the same resource hierarchy.
 
\section2 Application with C++ Types
 
An application that exposes C++ types to QML:
 
\badcode
qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES
        Main.qml
    SOURCES
        backend.cpp backend.h
)
\endcode
 
The C++ types in \c{backend.h} must be annotated with \l{QML_ELEMENT} (or
similar macros like \l{QML_NAMED_ELEMENT}) and must use the \l{Q_OBJECT}
or \l{Q_GADGET} macro. Type registration happens automatically via
\c{AUTOMOC}. See \l{Registering C++ Types with the QML Type System} for
a full overview of the available registration macros.
 
\section2 Reusable Library Module
 
A QML module packaged as a library that other projects or modules can import:
 
\badcode
# In src/MyCompany/Controls/CMakeLists.txt
qt_add_qml_module(mycontrols
    URI MyCompany.Controls
    QML_FILES
        Button.qml
        Slider.qml
    SOURCES
        theme.cpp theme.h
)
\endcode
 
This creates two targets: \c{mycontrols} (the backing library) and
\c{mycontrolsplugin} (the plugin). Other modules import it with
\c{import MyCompany.Controls} in QML. Applications that link to
\c{mycontrols} directly don't need to load the plugin at run time.
 
\section2 Application Using a Library Module
 
Using the \c{mycontrols} module from the \l{Reusable Library Module} example
above:
 
\badcode
# In the application's CMakeLists.txt
qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES Main.qml
    DEPENDENCIES TARGET mycontrols
)
 
target_link_libraries(myapp PRIVATE mycontrols)
\endcode
 
The \l{qt_add_qml_module}{DEPENDENCIES} line ensures that QML tooling
(\l{qmlcachegen}, \l{qmllint}, \l{\QMLLS}{qmlls}) can find the types provided by
\c{MyCompany.Controls}.
 
\badcode
// In Main.qml
import MyCompany.Controls
 
Button { text: "Click me" }
\endcode
 
\section2 Module with Singletons
 
QML files providing singleton types need a source file property set
\e{before} the \c{qt_add_qml_module} call:
 
\badcode
set_source_files_properties(Theme.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)
 
qt_add_qml_module(mymodule
    URI MyModule
    QML_FILES
        Theme.qml
        Main.qml
)
\endcode
 
The QML file must also contain \c{pragma Singleton}. Both the CMake property
and the QML pragma are required.
 
\section2 Module with Custom Plugin
 
When you need to perform custom initialization (for example, registering an
image provider), you can provide your own \l{QQmlEngineExtensionPlugin}
subclass.
 
\badcode
# In CMakeLists.txt
qt_add_qml_module(mymodule
    URI MyModule
    NO_GENERATE_PLUGIN_SOURCE
    NO_PLUGIN_OPTIONAL
    CLASS_NAME MyModulePlugin
    QML_FILES
        Main.qml
    SOURCES
        myimageprovider.cpp myimageprovider.h
)
 
# Add the custom plugin source to the plugin target
target_sources(mymoduleplugin PRIVATE plugin.cpp)
\endcode
 
\badcode
// In plugin.cpp
#include <QtQml/QQmlEngineExtensionPlugin>
#include "myimageprovider.h"
 
class MyModulePlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
public:
    void initializeEngine(QQmlEngine *engine, const char *uri) override
    {
        engine->addImageProvider("myprovider", new MyImageProvider);
    }
};
 
#include "plugin.moc"
\endcode
 
\l{qt_add_qml_module}{NO_GENERATE_PLUGIN_SOURCE} tells the build system not to
generate the default plugin source. \l{qt_add_qml_module}{CLASS_NAME} must
match the class name in your implementation.
\l{qt_add_qml_module}{NO_PLUGIN_OPTIONAL} ensures the plugin is always loaded,
since it contains initialization logic that would be skipped otherwise.
 
\section1 Adding Further QML Files
 
For QML files added after the initial \c{qt_add_qml_module} call, use
\l{qt_target_qml_sources}:
 
\code
qt_target_qml_sources(my_qml_module
    QML_FILES
        DynamicallyAddedType.qml
)
\endcode
 
This is useful for conditionally including files based on platform or
configuration.
 
\section1 Detailed CMake Reference
 
For complete details on all CMake commands, properties, variables, and policies,
see \l{CMake Integration for QML}.
 
\sa {QML Modules}, {qt_add_qml_module}, {Writing QML Modules}
*/