qt_add_qml_module

Define un módulo QML.

Este comando se introdujo en Qt 6.2.

El comando se define en el componente Qml del paquete Qt6, que puede cargarse de este modo:

find_package(Qt6 REQUIRED COMPONENTS Qml)

Sinopsis

qt_add_qml_module(
    target
    URI uri
    [VERSION version]
    [PAST_MAJOR_VERSIONS ...]
    [STATIC | SHARED]
    [PLUGIN_TARGET plugin_target]
    [OUTPUT_DIRECTORY output_dir]
    [RESOURCE_PREFIX resource_prefix]
    [CLASS_NAME class_name]
    [TYPEINFO typeinfo]
    [IMPORTS ...]
    [OPTIONAL_IMPORTS ...]
    [DEFAULT_IMPORTS ...]
    [DEPENDENCIES ...]
    [IMPORT_PATH ...]
    [SOURCES ...]
    [QML_FILES ...]
    [RESOURCES ...]
    [OUTPUT_TARGETS out_targets_var]
    [DESIGNER_SUPPORTED]
    [FOLLOW_FOREIGN_VERSIONING]
    [NAMESPACE namespace]
    [NO_PLUGIN]
    [NO_PLUGIN_OPTIONAL]
    [NO_CREATE_PLUGIN_TARGET]
    [NO_GENERATE_PLUGIN_SOURCE]
    [NO_GENERATE_QMLTYPES]
    [NO_GENERATE_QMLDIR]
    [NO_GENERATE_EXTRA_QMLDIRS]
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_RESOURCE_TARGET_PATH]
    [NO_IMPORT_SCAN]
    [DISCARD_QML_CONTENTS]
    [ENABLE_TYPE_COMPILER]
    [TYPE_COMPILER_NAMESPACE namespace]
    [QMLTC_EXPORT_DIRECTIVE export_macro]
    [QMLTC_EXPORT_FILE_NAME header_defining_export_macro]

)

Si los comandos sin versión están desactivados, utilice qt6_add_qml_module() en su lugar. Admite el mismo conjunto de argumentos que este comando.

Consulte Creación de una aplicación QML y Creación de un módulo QML reutilizable para ver ejemplos que definen módulos QML.

Descripción

Este comando define un módulo QML que puede constar de fuentes C++, archivos .qml o ambos. Garantiza que se proporcionen los detalles esenciales del módulo y que sean coherentes. También configura y coordina cosas como la compilación en caché de los fuentes de .qml, la incrustación de recursos, las comprobaciones de linting y la generación automática de algunos archivos clave del módulo.

Estructura del objetivo

Un módulo QML puede estructurarse de varias maneras. Las siguientes son las disposiciones típicas:

Objetivos de respaldo y de plugin separados

Esta es la disposición recomendada para la mayoría de los módulos QML. Toda la funcionalidad del módulo se implementa en el destino de respaldo, que se proporciona como primer argumento del comando. Los fuentes C++, los archivos .qml y los recursos deben añadirse al objetivo de respaldo. El objetivo de respaldo es una biblioteca que debe instalarse en la misma ubicación que cualquier otra biblioteca definida por el proyecto.

La estructura del directorio fuente en el que se crea el destino secundario debe coincidir con la ruta de destino del módulo QML (la ruta de destino es el URI del módulo con los puntos sustituidos por barras inclinadas). Si la estructura del directorio de origen no coincide con la ruta de destino, qt_add_qml_module() emitirá una advertencia.

El siguiente ejemplo muestra una estructura de directorios de origen adecuada para un módulo QML con un URI de MyThings.Panels. La llamada a qt_add_qml_module() estaría en el archivo CMakeLists.txt que se muestra.

src
 +-- MyThings
      +-- Panels
           +-- CMakeLists.txt

El módulo QML lleva asociado un destino de complemento independiente. Se utiliza en tiempo de ejecución para cargar el módulo dinámicamente cuando la aplicación aún no está vinculada al objetivo de respaldo. El objetivo del complemento también será una biblioteca y normalmente se instala en el mismo directorio que el archivo qmldir del módulo.

Lo ideal es que el plugin no contenga más que una implementación trivial de la clase del plugin. Esto permite designar el plugin como opcional en el archivo qmldir. Otros objetivos pueden entonces enlazar directamente con el objetivo de respaldo y el plugin no será necesario en tiempo de ejecución, lo que puede mejorar el rendimiento en tiempo de carga. Por defecto, se generará automáticamente un archivo fuente C++ que define una clase plugin mínima y se añadirá al objetivo plugin. Para los casos en los que el módulo QML necesite una implementación de clase de complemento personalizada, se necesitarán las opciones NO_GENERATE_PLUGIN_SOURCE y, normalmente, NO_PLUGIN_OPTIONAL.

Los módulos QML STATIC también generan los plugins QML estáticos si no se especifica NO_PLUGIN. Los objetivos que importan dichos módulos QML de STATIC también necesitan enlazar explícitamente a los plugins QML correspondientes.

Objetivo de plugin sin objetivo de respaldo

Se puede definir un módulo QML con el objetivo del complemento como su propio objetivo de respaldo. En este caso, el módulo debe cargarse dinámicamente en tiempo de ejecución y no puede enlazarse directamente con otros destinos. Para crear esta disposición, debe utilizarse la palabra clave PLUGIN_TARGET, con target repetido como nombre del destino del complemento. Por ejemplo:

qt_add_qml_module(someTarget
    PLUGIN_TARGET someTarget
    ...
)

Aunque este arreglo puede parecer marginalmente más simple de implementar, se debe preferir un objetivo de respaldo separado cuando sea posible debido al rendimiento potencialmente mejor en tiempo de carga.

Ejecutable como módulo QML

Un objetivo ejecutable puede actuar como objetivo de respaldo para un módulo QML. En este caso, no habrá biblioteca de complementos, ya que el módulo QML siempre se cargará directamente como parte de la aplicación. El comando qt_add_qml_module() detectará cuándo se utiliza un ejecutable como destino de respaldo y desactivará automáticamente la creación de un plugin independiente. No utilice ninguna de las opciones con PLUGIN en su nombre cuando utilice esta disposición.

Cuando se utiliza un ejecutable como destino de respaldo, no se espera que la estructura del directorio fuente coincida con la ruta de destino del módulo QML. Consulte Almacenamiento en caché de fuentes QML compiladas para conocer otras diferencias de rutas de destino para recursos compilados.

Generación automática de archivos qmldir y typeinfo

De forma predeterminada, se generarán automáticamente un archivo qmldir y un archivo typeinfo para el módulo QML que se está definiendo. El contenido de estos archivos viene determinado por los distintos argumentos proporcionados a este comando, así como por los archivos fuente y .qml añadidos al destino de respaldo. El argumento OUTPUT_DIRECTORY determina dónde se escribirán los archivos qmldir y typeinfo. Si el módulo QML tiene un plugin, ese plugin también se creará en el mismo directorio que el archivo qmldir.

Si la política QTP0004 se establece en NEW, por cada directorio adicional que contenga archivos .qml se generará otro archivo qmldir. Estos archivos qmldir adicionales simplemente redirigen al directorio base del módulo a través de una directiva prefer. Esto se hace para que todos los componentes QML de un módulo puedan acceder a los demás, independientemente del directorio en el que estén almacenados.

Si se utiliza un Qt construido estáticamente, los archivos .qml del destino de respaldo serán escaneados durante la ejecución de CMake configure para determinar las importaciones utilizadas por el módulo y para establecer las relaciones de enlace (la palabra clave NO_IMPORT_SCAN se puede dar para desactivar esto). Cuando se añada o elimine un archivo .qml del módulo, CMake se volverá a ejecutar automáticamente y se volverán a escanear los archivos relevantes, ya que se habrá modificado un archivo CMakeLists.txt. Durante el curso del desarrollo, un archivo .qml existente puede añadir o eliminar una importación o un tipo. Por sí solo, esto no haría que CMake se vuelva a ejecutar automáticamente, por lo que debe volver a ejecutar explícitamente CMake para forzar el archivo qmldir para ser regenerado y cualquier relación de vinculación para ser actualizado.

Las fuentes C++ del destino de respaldo se escanean en tiempo de compilación para generar un archivo typeinfo y un archivo C++ para registrar los tipos asociados. El archivo C++ generado se añade automáticamente al objetivo de respaldo como fuente. Esto requiere que AUTOMOC esté habilitado en el objetivo. El proyecto es responsable de asegurar esto, normalmente estableciendo la variable CMAKE_AUTOMOC a TRUE antes de llamar a qt_add_qml_module(), o pasando un objetivo existente con la propiedad AUTOMOC target ya establecida a TRUE. No es un error tener AUTOMOC desactivado en el objetivo, pero el proyecto es entonces responsable de manejar las consecuencias. Esto puede incluir tener que generar manualmente el archivo typeinfo en lugar de permitir que se autogenere con los detalles que faltan, y añadir código C++ para registrar los tipos.

Los proyectos deberían preferir utilizar los archivos typeinfo y qmldir autogenerados siempre que sea posible. Son más fáciles de mantener y no sufren la misma susceptibilidad a los errores que los archivos escritos a mano. Sin embargo, para situaciones en las que el proyecto necesita proporcionar estos archivos por sí mismo, la auto-generación puede ser desactivada. La opción NO_GENERATE_QMLDIR desactiva la auto-generación de qmldir y la opción NO_GENERATE_QMLTYPES desactiva la auto-generación de typeinfo y el registro de tipos C++. Si el archivo typeinfo autogenerado es aceptable, pero el proyecto quiere usar un nombre diferente para ese archivo, puede anular el nombre por defecto con la opción TYPEINFO (pero esto no debería ser necesario normalmente).

Almacenamiento en caché de fuentes QML compiladas

Todos los archivos .qml, .js, y .mjs añadidos al módulo mediante el argumento QML_FILES se compilarán en código de bytes y se almacenarán en caché directamente en el destino de respaldo. Esto mejora el rendimiento del módulo en tiempo de carga. Los archivos originales sin compilar también se almacenan en los recursos del destino de respaldo, ya que el motor QML puede necesitarlos en determinadas situaciones.

La ruta de recursos de cada archivo viene determinada por su ruta relativa al directorio fuente actual (CMAKE_CURRENT_SOURCE_DIR). Esta ruta de recurso se añade a un prefijo formado por la concatenación de RESOURCE_PREFIX y la ruta de destino (pero véase NO_RESOURCE_TARGET_PATH para una excepción a esto).

Si la política QTP0001 se establece en NEW, el RESOURCE_PREFIX se establece por defecto en /qt/qml/, que es la ruta de importación por defecto del motor QML. Esto asegura que los módulos se colocan en la ruta de importación QML y se pueden encontrar sin necesidad de configuración adicional.

Normalmente, el proyecto debería intentar colocar los archivos .qml en la misma ubicación relativa que tendrían en los recursos. Si el archivo .qml se encuentra en un directorio relativo distinto de la ruta de recursos deseada, deberá especificarse explícitamente su ubicación en los recursos. Esto se hace estableciendo la propiedad de archivo fuente QT_RESOURCE_ALIAS, que debe establecerse antes de añadir el archivo .qml. Por ejemplo:

set_source_files_properties(path/to/somewhere/MyFrame.qml PROPERTIES
    QT_RESOURCE_ALIAS MyFrame.qml
)

qt_add_qml_module(someTarget
    URI MyCo.Frames
    RESOURCE_PREFIX /my.company.com/imports
    QML_FILES
        path/to/somewhere/MyFrame.qml
        AnotherFrame.qml
)

En el ejemplo anterior, la ruta de destino será MyCo/Frames. Tras tener en cuenta las propiedades del archivo de origen, los dos archivos .qml se encontrarán en las siguientes rutas de recursos:

• /my.company.com/imports/MyCo/Frames/MyFrame.qml
• /my.company.com/imports/MyCo/Frames/AnotherFrame.qml

En el raro caso de que quieras anular la selección automática del programa qmlcachegen a utilizar, puedes establecer la propiedad QT_QMLCACHEGEN_EXECUTABLE target en el target del módulo. Por ejemplo:

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_EXECUTABLE qmlcachegen
)

Esto selecciona explícitamente qmlcachegen como el programa a utilizar, incluso si hay mejores alternativas disponibles.

Además, puede pasar argumentos adicionales a qmlcachegen, estableciendo la opción QT_QMLCACHEGEN_ARGUMENTS. En particular, la opción --only-bytecode desactivará la compilación del código de script QML a C++. Por ejemplo:

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--only-bytecode"
)

Otro argumento importante es --direct-calls. Puede utilizarlo para activar el modo directo del compilador de scripts Q ML en caso de que las extensiones del compilador Qt Quick estén instaladas. Si las extensiones no están instaladas, el argumento se ignora. Existe una abreviatura llamada QT_QMLCACHEGEN_DIRECT_CALLS para ello.

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_DIRECT_CALLS ON
)

Por último, el argumento --verbose se puede utilizar para ver la salida de diagnóstico de qmlcachegen:

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--verbose"
)

Con esta opción activada, qmlcachegen mostrará advertencias por cada función que no pueda compilar a C++. Algunas de estas advertencias indicarán problemas en tu código QML y otras te dirán que ciertas características del lenguaje QML no están implementadas en el generador de código C++. En ambos casos, qmlcachegen seguirá generando código byte para dichas funciones. Si desea ver sólo los problemas en su código QML, debe utilizar qmllint y los objetivos generados para él en su lugar.

Análisis de fuentes QML

Si se añade algún archivo .qml al módulo mediante la palabra clave QML_FILES, o mediante una llamada posterior a qt_target_qml_sources(), se creará automáticamente un objetivo de linting independiente. El nombre del objetivo de linting será target seguido de _qmllint. También se proporciona, por comodidad, un objetivo all_qmllint que depende de todos los objetivos *_qmllint individuales.

Se crea automáticamente un objetivo de compilación global dump_qml_context_properties que ejecuta qmlcontextpropertydump cuando no existe ya un archivo de volcado de propiedades de contexto qml. qmlcontextpropertydump crea un archivo de volcado de propiedades de contexto qml que es leído por qmllint para advertir sobre usos de propiedades de contexto en QML.

Un objetivo de compilación global clean_qml_context_properties permite eliminar un archivo de volcado de propiedades de contexto qml ya existente, y puede utilizarse para volver a calcular el archivo de volcado de propiedades de contexto qml en una futura compilación del objetivo de compilación global dump_qml_context_properties.

Los objetivos Linting dependen del objetivo de compilación dump_qml_context_properties cuando la variable QT_QMLLINT_CONTEXT_PROPERTY_DUMP está activada.

Convenciones de nomenclatura para los archivos .js

Los nombres de archivos JavaScript destinados a ser direccionados como componentes deben comenzar con una letra mayúscula.

Como alternativa, puede utilizar nombres de archivo en minúsculas y establecer la propiedad de archivo fuente QT_QML_SOURCE_TYPENAME en el nombre de tipo deseado.

Singletons

Si un módulo QML tiene archivos .qml que proporcionan tipos singleton, estos archivos deben tener su propiedad source QT_QML_SINGLETON_TYPE establecida en TRUE, para garantizar que el comando singleton se escribe en el archivo qmldir. Esto debe hacerse además del archivo QML que contiene la sentencia pragma Singleton. La propiedad source debe establecerse antes de crear el módulo al que pertenece el singleton.

Consulte qt_target_qml_sources() para ver un ejemplo de cómo establecer la propiedad QT_QML_SINGLETON_TYPE.

Compilación de QML a C++ con el compilador de tipos QML

Si un módulo QML tiene archivos .qml, puede compilarlos a C++ utilizando qmltc. A diferencia de la compilación de código de bytes, debe activar qmltc explícitamente mediante el argumento ENABLE_TYPE_COMPILER. En ese caso, se compilarían los archivos .qml especificados en QML_FILES. Los archivos que terminan en .js y .mjs se ignoran, ya que qmltc no compila código JavaScript. Además, los archivos marcados con la propiedad de archivo fuente QT_QML_SKIP_TYPE_COMPILER también se omiten.

Por defecto, qmltc crea archivos .h y .cpp en minúsculas para un archivo .qml dado. Por ejemplo, Foo.qml acaba siendo compilado en foo.h y foo.cpp.

Los archivos C++ creados se colocan en un subdirectorio dedicado .qmltc/<target>/ del BINARY_DIR del target. A continuación, estos archivos se añaden automáticamente a los fuentes de destino y se compilan como código Qt C++ junto con otros archivos fuente.

Al procesar QML_FILES, se respetan las siguientes propiedades de los archivos fuente:

• QT_QMLTC_FILE_BASENAMEQT_QMLTC_FILE : utilice esta propiedad de archivo fuente para especificar un nombre de archivo .h y .cpp no predeterminado, que podría ser útil para, por ejemplo, resolver nombres de archivo conflictivos (imagine que tiene main.qml que se está compilando, pero main.h ya existe, por lo que #include "main.h" podría no hacer lo que espera que haga). Se espera que QT_QMLTC_FILE_BASENAME sea un nombre de archivo (sin extensión), por lo que cualquier directorio precedente es ignorado. A diferencia del comportamiento por defecto, QT_QMLTC_FILE_BASENAME no se escribe en minúsculas.
• QT_QML_SKIP_TYPE_COMPILER: utilice esta propiedad de archivo fuente para especificar que un archivo QML debe ser ignorado por qmltc.

Argumentos

Argumentos requeridos

target especifica el nombre del destino de respaldo para el módulo QML. Por defecto, se crea como una biblioteca compartida si Qt fue construido como bibliotecas compartidas, o como una biblioteca estática en caso contrario. Esta elección se puede anular explícitamente con las opciones STATIC o SHARED.

Cada módulo QML debe definir un URI. Debe especificarse en notación URI con puntos, como QtQuick.Layouts. Cada segmento debe ser un nombre de identificador ECMAScript bien formado. Esto significa, por ejemplo, que los segmentos no deben empezar por un número y no deben contener caracteres - (menos). Dado que URI se traducirá a nombres de directorio, debe limitarse a caracteres alfanuméricos del alfabeto latino, guiones bajos y puntos. Otros módulos QML pueden utilizar este nombre en las sentencias import para importar el módulo. El URI se utilizará en la línea module del archivo qmldir generado. El URI también se utiliza para formar la ruta de destino sustituyendo los puntos por barras diagonales.

Consulte Módulos identificados para obtener más información sobre el URI del módulo.

Versiones

Un módulo QML también puede definir un VERSION de la forma Major.Minor, donde Major y Minor deben ser números enteros. Se puede añadir un componente .Patch adicional, pero se ignorará. Una lista de versiones principales anteriores para las que el módulo proporciona tipos también puede darse opcionalmente después de la palabra clave PAST_MAJOR_VERSIONS (véase más abajo). Consulte Módulos identificados para obtener más información sobre la numeración de versiones, Registro de versiones principales anteriores para registrar versiones principales anteriores y Mantener sincronizadas las versiones de los módulos para mantener sincronizadas las versiones de los módulos.

Si no necesita versiones, debería omitir el argumento VERSION. El valor predeterminado es la versión más alta posible. El versionado interno de los módulos QML tiene algunos defectos fundamentales. Debería utilizar un mecanismo externo de gestión de paquetes para gestionar las diferentes versiones de sus módulos QML.

Añadir fuentes y recursos al módulo

SOURCES especifica una lista de fuentes no QML que se añadirán al destino de respaldo. Se proporciona como una conveniencia y es equivalente a la adición de las fuentes a la copia de seguridad de destino con el built-in target_sources() CMake comando.

QML_FILES enumera los archivos .qml, .js y .mjs para el módulo. Éstos se compilarán automáticamente en bytecode y se incrustarán en el objetivo de respaldo a menos que se indique la opción NO_CACHEGEN. El archivo no compilado siempre se almacena en los recursos incrustados del objetivo de respaldo, incluso si se especifica NO_CACHEGEN. A menos que se indique la opción NO_LINT, los archivos descompilados también serán procesados por qmllint a través de un objetivo de compilación personalizado independiente. Los archivos también se utilizarán para rellenar la información de tipo en el archivo qmldir generado de forma predeterminada. NO_GENERATE_QMLDIR se puede dar para desactivar la generación automática del archivo qmldir. Esto debería evitarse normalmente, pero para casos en los que el proyecto necesite proporcionar su propio archivo qmldir, puede utilizarse esta opción. Desde Qt 6.8, cuando QTP0004 está activado, qt_add_qml_module creará archivos qmldir adicionales para cada subdirectorio en el módulo QML, lo que asegura que cada archivo QML importará su propio módulo a través de la importación implícita. Este comportamiento puede desactivarse para un módulo QML pasándole la bandera NO_GENERATE_EXTRA_QMLDIRS. NO_GENERATE_QMLDIR implica NO_GENERATE_EXTRA_QMLDIRS.

RESOURCES enumera cualquier otro archivo que necesite el módulo, como imágenes referenciadas desde el código QML. Estos archivos se añadirán como recursos compilados (consulte RESOURCE_PREFIX para obtener una explicación del punto base en el que se ubicarán). Si es necesario, su ubicación relativa puede ser controlada estableciendo la propiedad QT_RESOURCE_ALIAS source, al igual que para los archivos .qml (ver Caching compiled QML sources).

RESOURCE_PREFIX tiene por objeto encapsular un espacio de nombres para el proyecto y a menudo será el mismo para todos los módulos QML que defina el proyecto.

Sin embargo, es mejor establecer la política CMake QTP0001 en su lugar. Define un prefijo de recurso predeterminado que garantiza que el módulo QML termine en una de las rutas de importación predeterminadas del motor QML.

Si establece una RESOURCE_PREFIX, también debe añadirla a las rutas de importación para que el motor QML encuentre el módulo QML.

Si QTP0001 está activado (por ejemplo, a través de qt_standard_project_setup(REQUIRES 6.5)), el valor por defecto es "/qt/qml/", de lo contrario es "/".

Cuando se añaden varios archivos a los recursos compilados, se colocan bajo una ruta formada por la concatenación de RESOURCE_PREFIX y la ruta de destino. Para el caso especial en el que el objetivo de respaldo es un ejecutable, puede ser deseable colocar los archivos .qml del módulo y otros recursos directamente bajo RESOURCE_PREFIX en su lugar. Esto puede lograrse especificando la opción NO_RESOURCE_TARGET_PATH, que sólo puede utilizarse si el objetivo de respaldo es un ejecutable.

Registro de versiones anteriores

PAST_MAJOR_VERSIONS contiene una lista de versiones principales adicionales que proporciona el módulo. Para cada una de esas versiones y cada archivo QML sin una configuración QT_QML_SOURCE_VERSIONS se generará una entrada adicional en el archivo qmldir para especificar la versión adicional. Además, el código de registro del módulo generado registrará las versiones principales anteriores utilizando qmlRegisterModule() en el lado C++. El código de registro del módulo se genera automáticamente para su módulo QML, a menos que especifique NO_GENERATE_QMLTYPES (pero se desaconseja encarecidamente el uso de esta opción). El uso de PAST_MAJOR_VERSIONS añade cierta sobrecarga cuando se importa el módulo. Debería incrementar la versión principal de su módulo lo menos posible. Una vez que pueda confiar en que todos los archivos QML que importen este módulo omitirán la versión en sus importaciones, puede omitir PAST_MAJOR_VERSIONS. Todos los archivos QML importarán entonces la última versión de su módulo. Si tiene que admitir importaciones versionadas, considere la posibilidad de admitir sólo un número limitado de versiones principales anteriores.

Declarar las dependencias de los módulos

IMPORTS proporciona una lista de otros módulos QML que este módulo importa. Cada módulo enumerado aquí se añadirá como una entrada import en el archivo qmldir generado. Si un archivo QML importa este módulo, también importará todos los módulos enumerados en IMPORTS. Opcionalmente, se puede especificar una versión añadiéndola después de una barra, como QtQuick/2.0. Si se omite la versión, se importará la versión mayor disponible. Puede especificar sólo la versión mayor, como en QtQuick/2. En ese caso se importará la versión menor más grande disponible con la versión mayor dada. Por último, auto puede indicarse como versión (QtQuick/auto). Si se da auto, la versión con la que se está importando el módulo actual se propaga al módulo que se va a importar. Dada una entrada QtQuick/auto en un módulo YourModule, si un archivo QML especifica import YourModule 3.14, se importará la versión 3.14 de QtQuick. Para módulos relacionados que siguen un esquema de versiones común, se debe utilizar auto.

Las entradas de IMPORTS también pueden hacer referencia a objetivos CMake anteponiendo al nombre del objetivo la palabra clave TARGET. En este caso, el URI del módulo QML se determina automáticamente a partir del objetivo. Esto requiere optar por la política QTP0005 de CMake.

Por ejemplo, un módulo QML puede importar otro módulo haciendo referencia al objetivo CMake que lo proporciona:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    IMPORTS
        TARGET OtherQmlModule
)

OPTIONAL_IMPORTS proporciona una lista de otros módulos QML que este módulo puede importar en tiempo de ejecución. Éstos no son importados automáticamente por el motor QML al importar el módulo actual, sino que sirven como pistas para herramientas como qmllint. Las versiones pueden especificarse del mismo modo que en IMPORTS. Cada módulo enumerado aquí se añadirá como una entrada optional import en el archivo qmldir generado.

Las entradas de OPTIONAL_IMPORTS también pueden hacer referencia a objetivos CMake anteponiendo al nombre del objetivo la palabra clave TARGET. En este caso, el URI del módulo QML se determina automáticamente a partir del objetivo. Esto requiere optar por la política QTP0005 de CMake.

Por ejemplo:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    OPTIONAL_IMPORTS
        TARGET OptionalQmlModule
)

DEFAULT_IMPORTS especifica cuales de las importaciones opcionales son las entradas por defecto que deben ser cargadas por tooling. Debe especificarse una entrada por cada grupo de OPTIONAL_IMPORTS en el módulo. Como las importaciones opcionales sólo se resuelven en tiempo de ejecución, las herramientas como qmllint no pueden saber en general cuál de las importaciones opcionales debe resolverse. Para remediar esto, puede especificar una de las importaciones opcionales como la importación predeterminada; las herramientas la elegirán. Si usted tiene una importación opcional que se utiliza en tiempo de ejecución sin ninguna configuración adicional, que es un candidato ideal para la importación por defecto.

Las entradas en DEFAULT_IMPORTS también pueden referirse a objetivos CMake anteponiendo al nombre del objetivo la palabra clave TARGET. En este caso, el URI del módulo QML se determina automáticamente a partir del objetivo. Esto requiere optar por la política QTP0005 de CMake.

Por ejemplo:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    OPTIONAL_IMPORTS
        TARGET BackendA
        TARGET BackendB
    DEFAULT_IMPORTS
        TARGET BackendA
)

DEPENDENCIES proporciona una lista de otros módulos QML de los que depende este módulo, pero que no necesariamente importa. Normalmente se utilizaría para dependencias que sólo existen a nivel de C++, como un módulo que registra una clase en QML que utiliza o hereda tipos definidos en C++ definidos en otro módulo.

Por ejemplo, si uno quisiera subclasificar QQuickItem como sigue:

class MyItem: public QQuickItem { ... };

entonces hay que asegurarse de que el módulo que contiene QQuickItem, llamado QtQuick, se declara como dependencia mediante la opción DEPENDENCIES:

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQuick
)

No hacerlo podría dar lugar a errores de linting, errores durante la compilación de tipos con qmltc o durante la vinculación y compilación de funciones a C++ con qmlcachegen.

Otro ejemplo podría ser:

class MyComponent : public QObject {
    Q_OBJECT
    QML_ELEMENT

    // ...

signals:
    void sigZoomAtMousePosition(const QPointF& aMousePos, double aZoomScaleFactor);
};

donde DEPENDENCIES QtQml es necesario para que las herramientas QML encuentren y utilicen QPointF:

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQml
)

Las entradas en DEPENDENCIES también pueden referirse a objetivos CMake anteponiendo al nombre del objetivo la palabra clave TARGET. En este caso, el URI del módulo QML y la ruta de importación se determinan automáticamente a partir del objetivo. Esto requiere optar por la política QTP0005 de CMake.

Por ejemplo, un módulo QML puede declarar una dependencia de otro módulo haciendo referencia al objetivo CMake que lo proporciona:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    DEPENDENCIES
        TARGET OtherQmlModule
)

La versión del módulo de las dependencias debe especificarse junto con el nombre del módulo, de la misma forma que se utiliza para IMPORTS y OPTIONAL_IMPORTS. Cada módulo enumerado aquí se añadirá como una entrada depends en el archivo qmldir generado.

IMPORT_PATH se puede utilizar para añadir a las rutas de búsqueda dónde se pueden encontrar otros módulos QML de los que éste dependa. Los otros módulos deben tener su archivo qmldir en su propia ruta de destino debajo de una de las rutas de búsqueda.

Si el objetivo de respaldo es una biblioteca estática y esa biblioteca estática va a ser instalada, se debe dar a OUTPUT_TARGETS para proporcionar una variable en la que almacenar una lista de objetivos adicionales que también necesitarán ser instalados. Estos objetivos adicionales son generados internamente por qt_add_qml_module() y son referenciados por los requisitos de enlace del objetivo de respaldo como parte de la garantía de que los recursos están configurados y cargados correctamente.

Objetivos y complementos de objetivos

PLUGIN_TARGET especifica el objetivo de complemento asociado al módulo QML. El PLUGIN_TARGET puede ser el mismo que el target de respaldo, en cuyo caso no habrá un objetivo de respaldo independiente. Si no se indica PLUGIN_TARGET, por defecto será target con plugin añadido. Por ejemplo, un objetivo de respaldo llamado mymodule tendría un nombre de complemento predeterminado de mymoduleplugin. El nombre del objetivo del complemento se utilizará para rellenar una línea plugin en el archivo qmldir generado. Por lo tanto, no debe intentar cambiar el nombre de salida del plugin estableciendo propiedades de objetivo como OUTPUT_NAME o cualquiera de sus propiedades relacionadas.

El respaldo target y el objetivo del plugin (si es diferente) serán creados por el comando, a menos que ya existan. Por lo general, los proyectos deben permitir que el comando los cree para que se creen como el tipo de destino apropiado. Si la base target es una biblioteca estática, el complemento también se creará como biblioteca estática. Si target es una biblioteca compartida, el complemento se creará como una biblioteca modular. Si se pasa un target existente y es un objetivo ejecutable, no habrá complemento. Si desea enlazar siempre directamente con el destino de respaldo y no necesita un complemento, puede desactivarlo añadiendo la opción NO_PLUGIN. Especificar tanto NO_PLUGIN como PLUGIN_TARGET es un error.

En ciertas situaciones, el proyecto puede querer retrasar la creación del objetivo plugin hasta después de la llamada. La opción NO_CREATE_PLUGIN_TARGET se puede dar en esa situación. Entonces se espera que el proyecto llame a qt_add_qml_plugin() en el plugin objetivo una vez que ha sido creado. Cuando se proporciona NO_CREATE_PLUGIN_TARGET, también se debe proporcionar PLUGIN_TARGET para nombrar explícitamente el objetivo del complemento.

Por defecto, qt_add_qml_module() generará automáticamente un archivo .cpp que implementa la clase de complemento nombrada por el argumento CLASS_NAME. El archivo .cpp generado se añadirá automáticamente al destino del complemento como un archivo fuente que debe compilarse. Si el proyecto desea proporcionar su propia implementación de la clase del complemento, debe indicarse la opción NO_GENERATE_PLUGIN_SOURCE. Si no se proporciona CLASS_NAME, se utilizará por defecto URI con los puntos sustituidos por guiones bajos y, a continuación, se añadirá Plugin. A menos que el módulo QML no tenga plugin, el nombre de la clase se registrará como una línea classname en el archivo qmldir generado. Debe añadir cualquier archivo C++ con código de plugin personalizado al destino del plugin. Dado que es probable que el complemento contenga funciones que vayan más allá de la simple carga de la biblioteca de respaldo, probablemente también querrá añadir NO_PLUGIN_OPTIONAL. De lo contrario, el motor QML puede omitir la carga del complemento si detecta que la biblioteca de respaldo ya está vinculada.

Si se indica la palabra clave NO_PLUGIN, no se creará ningún complemento. Por tanto, esta palabra clave es incompatible con todas las opciones que personalizan el destino del complemento, en particular NO_GENERATE_PLUGIN_SOURCE, NO_PLUGIN_OPTIONAL, PLUGIN_TARGET, NO_CREATE_PLUGIN_TARGET y CLASS_NAME. Si no proporcionas un plugin para tu módulo, sólo será totalmente utilizable si su biblioteca de respaldo ha sido enlazada en el ejecutable. Por lo general, es difícil garantizar que un enlazador conserve el enlace a una biblioteca que considera no utilizada.

Si se indica la palabra clave NO_PLUGIN_OPTIONAL, el complemento se registra en el archivo qmldir generado como no opcional. Si toda la funcionalidad de un módulo QML se implementa en su destino de respaldo y el destino del complemento está separado, entonces el complemento puede ser opcional, que es la disposición predeterminada y recomendada. El archivo fuente del complemento generado automáticamente cumple este requisito. Cuando un proyecto proporciona su propia implementación de .cpp para el complemento, esto significa normalmente que la palabra clave NO_PLUGIN_OPTIONAL también es necesaria porque el complemento contendrá casi con toda seguridad la funcionalidad que requiere el módulo QML.

Registro automático de tipos

El registro de tipos se realiza automáticamente para las fuentes C++ del objetivo de respaldo que son procesadas por AUTOMOC. Esto generará un archivo typeinfo en el directorio de salida, el nombre del archivo será el nombre target con .qmltypes añadido. Este nombre de archivo puede ser cambiado usando la opción TYPEINFO si se desea, pero esto normalmente no debería ser necesario. El nombre del archivo también se registra como una entrada typeinfo en el archivo qmldir generado. El registro automático de tipos puede desactivarse utilizando la opción NO_GENERATE_QMLTYPES, en cuyo caso no se generará ningún archivo typeinfo, pero se espera que el proyecto genere un archivo typeinfo y lo coloque en el mismo directorio que el archivo qmldir generado.

OUTPUT_DIRECTORY especifica dónde se generan la biblioteca de plugins, qmldir y los archivos typeinfo. Cuando no se especifica esta palabra clave, el valor por defecto será la ruta de destino (formada a partir de URI) añadida al valor de la variable QT_QML_OUTPUT_DIRECTORY. Si esa variable no está definida, el valor por defecto dependerá del tipo de destino de respaldo. Para los ejecutables, el valor será la ruta de destino añadida a ${CMAKE_CURRENT_BINARY_DIR}, mientras que para otros destinos será simplemente ${CMAKE_CURRENT_BINARY_DIR}. Cuando la estructura del árbol de fuentes coincide con la estructura de las rutas de destino de los módulos QML (lo cual es muy recomendable), QT_QML_OUTPUT_DIRECTORY no suele ser necesario. Para que coincida con la estructura de las rutas de destino, tiene que llamar a sus directorios exactamente igual que los segmentos de la URI de su módulo. Por ejemplo, si el URI de tu módulo es MyUpperCaseThing.mylowercasething, necesitas ponerlo en un directorio llamado MyUpperCaseThing/mylowercasething/.

La necesidad de especificar la palabra clave OUTPUT_DIRECTORY debería ser poco frecuente, pero si se utiliza, es probable que el autor de la llamada también necesite añadir al IMPORT_PATH para garantizar que el linting, la compilación en caché de fuentes qml, la importación automática de plugins en compilaciones estáticas y el despliegue de módulos QML importados para compilaciones no estáticas funcionen correctamente.

Qt Quick Compatibilidad con el diseñador

DESIGNER_SUPPORTED debe indicarse si el módulo QML es compatible con Qt Quick Designer. Si está presente, el archivo qmldir generado contendrá una línea designersupported. Consulte Archivos qmldir de definición de módulo para saber cómo afecta esto a la forma en que Qt Quick Designer gestiona el complemento.

Mantener sincronizadas las versiones de los módulos

La palabra clave FOLLOW_FOREIGN_VERSIONING se refiere a los tipos base de sus propios tipos QML definidos en C++ que viven en diferentes módulos QML. Normalmente, el esquema de versiones de tu módulo no coincide con el del módulo que proporciona los tipos base. Por lo tanto, por defecto todas las revisiones de los tipos base están disponibles en cualquier importación de su módulo. Si se proporciona FOLLOW_FOREIGN_VERSIONING, se respeta la información de versión adjunta a los tipos base y sus propiedades. Así, un import MyModule 2.8 sólo hará disponibles las propiedades versionadas hasta la versión 2.8 de cualquier tipo base fuera de MyModule. Esto es útil sobre todo si quieres mantener la versión de tu módulo sincronizada con la de otros módulos en los que estés basando tipos. En ese caso, puede que quieras que tus tipos personalizados no expongan propiedades de una versión de tipo base de un módulo superior a la que se está importando.

Espacios de nombres C++ del código generado

Si un espacio de nombres es dado con la palabra clave NAMESPACE, el plugin y el código de registración serán generados en un espacio de nombres C++ con este nombre.

qmlimportscanner y NO_IMPORT_SCAN

Para construcciones estáticas de Qt, qmlimportscanner se ejecuta en tiempo de configuración para escanear los archivos .qml de un módulo QML e identificar las importaciones QML que utiliza (ver qt_import_qml_plugins()). Para las compilaciones no estáticas de Qt, si el objetivo es un ejecutable, se realiza un análisis similar en tiempo de compilación para proporcionar la información que necesitan los scripts de implementación (consulte qt_deploy_qml_imports()). Ambos análisis pueden desactivarse mediante la opción NO_IMPORT_SCAN. Al hacerlo, el proyecto asume la responsabilidad de garantizar que todos los plugins necesarios se instancian y enlazan para las compilaciones estáticas. Para las compilaciones no estáticas, el proyecto debe elaborar y desplegar manualmente todos los módulos QML utilizados por un objetivo ejecutable.

DESCARTAR_CONTENIDOS_QML

Por defecto, el contenido de los archivos fuente QML y JS se incluye en el sistema de recursos del destino. Utilice DISCARD_QML_CONTENTS para eliminar estos contenidos y reducir el tamaño del binario.

Argumentos para qmltc

ENABLE_TYPE_COMPILER pueden usarse para compilar archivos .qml a código fuente C++ con qmltc. Los archivos con la propiedad source QT_QML_SKIP_TYPE_COMPILER no se compilan a C++.

TYPE_COMPILER_NAMESPACE permite anular el espacio de nombres en el que qmltc genera el código. Por defecto, el espacio de nombres del código generado sigue la jerarquía de módulos tal y como se representa en el URI, por ejemplo, MyModule para un módulo con URI MyModule o com::example::Module para URI com.example.MyModule. Especificando la opción TYPE_COMPILER_NAMESPACE, el código generado puede colocarse en un espacio de nombres personalizado, donde los diferentes subespacios de nombres deben separarse con "::", por ejemplo, "MiEspacioDeNombres::MiSubespacioDeNombres" para el espacio de nombres MiSubespacioDeNombres que está dentro de MiEspacioDeNombres. Aparte del "::", se aplican las reglas de nomenclatura de espacios de nombres de C++.

QMLTC_QMLTC_EXPORT_DIRECTIVE debe utilizarse con QMLTC_EXPORT_FILE_NAME cuando las clases generadas por qmltc deban exportarse desde la biblioteca qml. Por defecto, las clases generadas por qmltc no se exportan desde su biblioteca. La cabecera que define la macro de exportación para la biblioteca actual se puede especificar como argumento opcional en QMLTC_EXPORT_FILE_NAME, mientras que el nombre de la macro de exportación se debe especificar como argumento en QMLTC_QMLTC_EXPORT_DIRECTIVE. Si no se requiere o no se desea una inclusión adicional, por ejemplo, cuando la cabecera de la macro de exportación ya está incluida indirectamente por una clase base, se puede omitir la opción QMLTC_EXPORT_FILE_NAME.