En esta página

La caché de disco de QML

Para lograr un rendimiento óptimo, los documentos QML se precompilan con antelación durante el proceso de compilación o se almacenan en caché tras la compilación en tiempo de ejecución. En esta página se describen ambas estrategias y cómo configurar el comportamiento del almacenamiento en caché.

Compilación anticipada

Debes definir tus módulos QML utilizando `qt_add_qml_module`, lo que garantiza que el compilador «Qt Quick » procese tus archivos QML y JavaScript con antelación. Esto garantiza un rendimiento óptimo en tiempo de ejecución.

El compilador «Qt Quick » genera código byte para cada función y enlace. Este código byte puede ser utilizado por el intérprete de QML y el compilador «Just-in-Time» (JIT) del motor QML. Además, el compilador «Qt Quick » genera código nativo para las funciones y enlaces adecuados. El código nativo se ejecuta directamente, lo que se traduce en un mejor rendimiento que la interpretación o la compilación «just-in-time» del código byte. A continuación, tanto el código byte como el código nativo se compilan en el binario de la aplicación.

Una de las ventajas de la compilación anticipada es que los errores de sintaxis en los documentos QML se detectan en el momento de la compilación de la aplicación, en lugar de en tiempo de ejecución, cuando se carga el archivo.

Con CMake

Al utilizar CMake con qt_add_qml_module, los archivos QML se compilan automáticamente por adelantado. Se recomienda cargar los documentos QML desde el sistema de archivos de recursos siempre que sea posible. Esto garantiza que el motor QML pueda encontrar el código compilado por adelantado.

Con qmake

Al utilizar qmake, puedes habilitar la compilación anticipada especificando ` CONFIG += qtquickcompiler ` en tu archivo de proyecto. Qt Creator tiene una configuración que permite pasar esta directiva a la línea de comandos de qmake. De forma predeterminada, está habilitada para las compilaciones de lanzamiento y de perfil.

Al utilizar qmake, debes organizar tu proyecto de una forma específica:

  • Todos los documentos Qml (incluidos los archivos JavaScript) deben incluirse como recursos a través del sistema de recursos de Qt.
  • Tu aplicación debe cargar los documentos QML mediante el esquema de URL qrc:///.

Ten en cuenta que qmake no puede pasar tanta información al compiladorQt Quick como CMake. Por lo tanto, la compilación contendrá menos código nativo.

Almacenamiento en caché en disco en tiempo de ejecución

Si no se encuentra código precompilado en tiempo de ejecución, o si el código no se puede utilizar, el motor QML compila los documentos QML en una representación de código byte sobre la marcha. En lugar de recompilar el mismo documento cada vez que se carga, el motor QML almacena en caché el código byte compilado. El proceso de almacenamiento en caché es automático: cada vez que se carga un documento QML modificado, la caché se recrea automáticamente.

Formato y ubicación de los archivos de caché

Los archivos de caché utilizan las siguientes extensiones:

  • .qmlc para documentos QML compilados
  • .jsc para archivos JavaScript importados
  • .mjsc para módulos ECMAScript

Los archivos de caché se encuentran en un subdirectorio denominado « qmlcache » dentro del directorio de caché del sistema, tal y como se indica en QStandardPaths::CacheLocation.

Eficiencia de memoria

Los archivos de caché se cargan mediante la llamada al sistema ` mmap() ` en sistemas operativos compatibles con POSIX o mediante ` CreateFileMapping() ` en Windows. Este enfoque de mapeo de memoria supone un ahorro significativo de memoria. Además, cuando varias aplicaciones utilizan el mismo documento QML, la memoria necesaria para el código se comparte entre los procesos de las aplicaciones, lo que reduce aún más la sobrecarga de memoria.

Validación de la caché

Los archivos de caché y el código compilado por adelantado solo se cargan si se cumplen todas las condiciones siguientes:

  • La versión de Qt no ha cambiado
  • El código fuente del archivo original no ha cambiado
  • El depurador de QML no se está ejecutando
  • La validación del código AOT se ha realizado correctamente

Ten en cuenta que la variable de entorno ` QML_FORCE_DISK_CACHE ` (véase más abajo) puede anular la condición del depurador de QML. Las demás variables de entorno no influyen en estas condiciones de validación.

Validación del código nativo generado por adelantado

El código nativo generado por el compiladorQt Quick incorpora algunas suposiciones. Si las condiciones en las que se ejecuta el código difieren de aquellas en las que se compiló, su uso podría no ser seguro. Por lo tanto, el código nativo se valida en tiempo de ejecución utilizando los metadatos almacenados junto con él. Si esta validación se supera, el código se ejecuta con normalidad. Si falla, la ejecución recurre de forma silenciosa a la interpretación del bytecode. Esta validación se realiza una vez por archivo, la primera vez que se carga el código, y aprueba o rechaza todas las funciones y enlaces de ese archivo QML en su conjunto.

Puedes personalizar la validación del código AOT:

  • Para desactivar la validación en tiempo de ejecución, configura la variable de entorno ` QV4_SKIP_AOT_VALIDATION `. Esto te permite evitar la pequeña sobrecarga que supone realizar la validación.
    QV4_SKIP_AOT_VALIDATION=1 ./myQmlApp
  • Para garantizar que la validación se realice correctamente en tiempo de ejecución, establece la variable de entorno ` QV4_FAIL_ON_INVALID_AOT `. Si la validación falla, el programa se cierra. Esto te permite asegurarte de que las funciones compiladas se ejecutan efectivamente como código nativo, por ejemplo.
    QV4_FAIL_ON_INVALID_AOT=1 ./myQmlApp
  • Para desactivar la función por completo e impedir que el compilador «Qt Quick » genere los metadatos y la lógica de validación, pasa « NO_GENERATE_AOT_VALIDATION » a «qt_add_qml_module».
    qt_add_qml_module(... NO_GENERATE_AOT_VALIDATION)

Configuración

Puede ajustar el comportamiento del almacenamiento en caché mediante la variable de entorno ` QML_DISK_CACHE`, que admite una lista de opciones separadas por comas. Por ejemplo:

QML_DISK_CACHE=aot,qmlc-read

Las opciones disponibles son las siguientes:

OpciónDescripción
aot-nativeCarga las unidades de compilación compiladas previamente y permite la ejecución de cualquier código nativo que se encuentre en ellas.
aot-bytecodeCarga las unidades de compilación compiladas previamente y permite la interpretación y la compilación «just-in-time» del código byte que contengan.
aotAbreviatura de « aot-native,aot-bytecode ».
qmlc-readCarga cualquier unidad de compilación almacenada en caché para archivos QML y JavaScript desde el sistema de archivos del host y permite la interpretación y la compilación «just-in-time» del código de bytes que contienen.
qmlc-writeAl compilar un archivo QML o JavaScript sobre la marcha, crea un archivo de caché a continuación. El archivo de caché se puede cargar cuando se vuelva a solicitar el mismo documento.
qmlcAbreviatura de « qmlc-read,qmlc-write ».

Además, puedes utilizar las siguientes variables de entorno:

Variable de entornoDescripción
QML_DISABLE_DISK_CACHEDesactiva la caché de disco y obliga a recompilar desde el código fuente todos los archivos QML y JavaScript. QML_DISABLE_DISK_CACHE anula QML_DISK_CACHE.
QML_FORCE_DISK_CACHEHabilita la caché de disco incluso durante la depuración de QML. De esta forma, no se puede utilizar el depurador de JavaScript. Por ejemplo, es posible que no se detenga en los puntos de interrupción. No obstante, se puede seguir utilizando el inspector de QML para explorar la jerarquía de objetos. ` QML_FORCE_DISK_CACHE ` anula ` QML_DISABLE_DISK_CACHE ` y ` QML_DISK_CACHE`.
QML_DISK_CACHE_PATHEspecifica una ubicación personalizada donde se almacenarán los archivos de caché, en lugar de utilizar la ubicación predeterminada.

© 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.