En esta página

Integrarlo todo con CMake

El comando de CMake ` qt_add_qml_module ` es la forma recomendada de definir módulos QML. Automatiza el registro de tipos, la incorporación de recursos, la creación de complementos y la integración de herramientas. Esta página explica los conceptos que hay detrás de ` qt_add_qml_module ` y describe los patrones de uso más habituales.

Para consultar la referencia completa de todas las opciones, véase qt_add_qml_module.

Conceptos clave

Antes de ver los ejemplos, conviene entender qué es lo que crea realmente qt_add_qml_module:

  • Un objetivo de soporte: una biblioteca (o ejecutable) que contiene el código C++ del módulo, los archivos QML compilados y los recursos. Este es el primer argumento de ` qt_add_qml_module ` y es el objetivo con el que se realiza el enlace. Puede ser un objetivo ya existente (creado previamente con ` qt_add_executable ` o ` qt_add_library`) o bien ` qt_add_qml_module ` lo creará por ti.
  • Un objetivo «plugin »: una pequeña biblioteca que permite al motor QML cargar el módulo de forma dinámica en tiempo de ejecución. Se crea automáticamente y es independiente del objetivo «backing». Cuando un ejecutable se vincula directamente al objetivo «backing», el plugin no se carga en tiempo de ejecución. El plugin puede omitirse por completo utilizando NO_PLUGIN.
  • Un archivo qmldir: un archivo de metadatos del módulo que indica al motor QML qué tipos proporciona el módulo y dónde encontrarlos. Se genera automáticamente.
  • Un archivo typeinfo (.qmltypes): información sobre tipos legible por máquina que utilizan las herramientas de QML (qmlcachegen, qmllint, qmlls, Qt Creator). También se genera automáticamente.

Estructura de directorios

La estructura del directorio de código fuente debe reflejar el URI del módulo. El URI se convierte en una ruta sustituyendo los puntos por barras. Por ejemplo, un módulo con el URI MyCompany.Controls debería encontrarse en:

src/MyCompany/Controls/CMakeLists.txt
src/MyCompany/Controls/Button.qml
src/MyCompany/Controls/mywidget.cpp
src/MyCompany/Controls/mywidget.h

Esta convención permite que el motor QML y las herramientas encuentren los módulos sin necesidad de configuración adicional. Si tu estructura de directorios no coincide con la URI, tendrás que configurar OUTPUT_DIRECTORY para que el resultado de la compilación se guarde en una ruta que coincida con la URI, y IMPORT_PATH para que el motor QML y las herramientas puedan localizar el módulo.

Patrones comunes

Aplicación solo en QML

El caso más sencillo: un ejecutable que solo contiene archivos QML y ningún tipo de C++.

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)

Dado que el destino subyacente es un ejecutable, no se crea ningún complemento. Los archivos QML se compilan y se incrustan como recursos. La palabra clave ` RESOURCES ` añade archivos que no son QML (imágenes, fuentes, etc.) a la misma jerarquía de recursos.

Aplicación con tipos C++

Una aplicación que expone tipos de C++ a QML:

qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES
        Main.qml
    SOURCES
        backend.cpp backend.h
)

Los tipos C++ en backend.h deben estar anotados con QML_ELEMENT (o macros similares como QML_NAMED_ELEMENT) y deben utilizar la macro Q_OBJECT o Q_GADGET. El registro de tipos se realiza automáticamente mediante AUTOMOC. Consulta «Registro de tipos C++ con el sistema de tipos QML» para obtener una descripción completa de las macros de registro disponibles.

Módulo de biblioteca reutilizable

Un módulo QML empaquetado como una biblioteca que otros proyectos o módulos pueden importar:

# 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
)

Esto crea dos objetivos: mycontrols (la biblioteca de soporte) y mycontrolsplugin (el complemento). Otros módulos lo importan mediante import MyCompany.Controls en QML. Las aplicaciones que se vinculan directamente a mycontrols no necesitan cargar el complemento en tiempo de ejecución.

Aplicación que utiliza un módulo de biblioteca

Utilizando el módulo mycontrols del ejemplo anterior sobre el módulo de biblioteca reutilizable:

# 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)

La línea DEPENDENCIES garantiza que las herramientas de QML (qmlcachegen, qmllint, qmlls) puedan encontrar los tipos proporcionados por MyCompany.Controls.

// In Main.qml
import MyCompany.Controls

Button { text: "Click me" }

Módulo con singletons

Los archivos QML que proporcionan tipos singleton necesitan una propiedad de archivo fuente definida antes de la llamada a ` qt_add_qml_module `:

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
)

El archivo QML también debe contener pragma Singleton. Son obligatorias tanto la propiedad de CMake como el pragma de QML.

Módulo con complemento personalizado

Cuando necesites realizar una inicialización personalizada (por ejemplo, registrar un proveedor de imágenes), puedes proporcionar tu propia subclase de ` QQmlEngineExtensionPlugin `.

# 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)
// 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"

NO_GENERATE_PLUGIN_SOURCE indica al sistema de compilación que no genere el código fuente predeterminado del complemento. CLASS_NAME debe coincidir con el nombre de la clase en su implementación. NO_PLUGIN_OPTIONAL garantiza que el complemento se cargue siempre, ya que contiene lógica de inicialización que, de lo contrario, se omitiría.

Añadir más archivos QML

Para los archivos QML añadidos tras la llamada inicial a ` qt_add_qml_module `, utilice ` qt_target_qml_sources`:

qt_target_qml_sources(my_qml_module
    QML_FILES
        DynamicallyAddedType.qml
)

Esto resulta útil para incluir archivos de forma condicional en función de la plataforma o la configuración.

Referencia detallada de CMake

Para obtener información completa sobre todos los comandos, propiedades, variables y políticas de CMake, consulta Integración de CMake para QML.

Véase también Módulos QML, qt_add_qml_module y Creación de módulos QML.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.