The QML Disk Cache¶

QML documents are generally pre-compiled or cached after compilation.

You should define your QML modules using qt_add_qml_module that makes sure that the Qt Quick Compiler processes your QML and JavaScript files ahead of time. Also, it guarantees optimum performance at run time. The Qt Quick Compiler generates byte code for each function and binding. This byte code can be used by the QML interpreter, and the Just-in-time (JIT) compiler in the QML engine. In addition, the Qt Quick Compiler generates native code for suitable functions and bindings. The native code can be executed directly, which results in better performance than interpreting or just-in-time compiling the byte code. Both, byte code and native code are then compiled into your binary.

When using qmake you can specify CONFIG += qtquickcompiler to give similar treatment to QML and JavaScript files added as resources to your project. Qt Creator has a setting that allows passing CONFIG += qtquickcompiler to the qmake command line. By default, it is enabled for release and profile builds. qmake cannot pass as much information to the Qt Quick Compiler as CMake. Therefore, the compilation will contain less native code.

You should make sure to load your QML documents from the resource file system where possible. Otherwise the QML engine won’t be able to find the code compiled ahead of time.

If no byte code or native code can be found for a QML document at run time, or if the code is found but cannot be used, the QML engine compiles the document into a byte code representation on the fly. The compiling process can be time consuming, and the result will contain only byte code. Subsequent loads of the same document will yield the same byte code. The QML engine can optimize this step by caching the result of the compilation. It stores the byte code in a cache file and later loads the cache file instead of re-compiling when the same QML document is requested again. Usually, the cache files are stored in a subdirectory qmlcache of the system’s cache directory, as denoted by QStandardPaths::CacheLocation.

Checks are in place to make sure that any cache files and any code compiled ahead of time are only loaded if all of the following conditions are met:

The Qt version has not changed

The source code in the original file has not changed

The QML debugger is not running

Only the QML_FORCE_DISK_CACHE variable (see below) overrides only the condition regarding the QML debugger. The other environment variables do not influence these conditions.

The primary way of fine tuning the behavior regarding ahead of time compiled code and caching is via the environment variable QML_DISK_CACHE. This variable takes a comma-separated list of options, for example:

QML_DISK_CACHE=aot,qmlc-read

The available options are as follows:

Option

Description

aot-native

Load the compilation units compiled ahead of time and allow execution of any native code found in them.

aot-bytecode

Load the compilation units compiled ahead of time and allow interpretation and just-in-time compilation of byte code found in them.

aot

Shorthand for aot-native,aot-bytecode.

qmlc-read

Load any cached compilation units for QML and JavaScript files from the host file system and allow interpretation and just-in-time compilation of byte code found in them.

qmlc-write

When compiling a QML or JavaScript file on the fly, create a cache file afterward. The cache file can be loaded when the same document is requested again.

qmlc

Shorthand for qmlc-read,qmlc-write.

Option	Description
aot-native	Load the compilation units compiled ahead of time and allow execution of any native code found in them.
aot-bytecode	Load the compilation units compiled ahead of time and allow interpretation and just-in-time compilation of byte code found in them.
aot	Shorthand for `aot-native,aot-bytecode`.
qmlc-read	Load any cached compilation units for QML and JavaScript files from the host file system and allow interpretation and just-in-time compilation of byte code found in them.
qmlc-write	When compiling a QML or JavaScript file on the fly, create a cache file afterward. The cache file can be loaded when the same document is requested again.
qmlc	Shorthand for `qmlc-read,qmlc-write`.

Furthermore, you can use the following environment variables:

Environment Variable

Description

QML_DISABLE_DISK_CACHE

Disables the disk cache and forces re-compilation from source for all QML and JavaScript files. QML_DISABLE_DISK_CACHE overrides QML_DISK_CACHE.

QML_FORCE_DISK_CACHE

Enables the disk cache even when debugging QML. You cannot use the JavaScript debugger this way. It may fail to stop at breakpoints, for example. You can still use the QML inspector to explore the object hierarchy, though. QML_FORCE_DISK_CACHE overrides QML_DISABLE_DISK_CACHE and QML_DISK_CACHE.

QML_DISK_CACHE_PATH

Specifies a custom location where the cache files shall be stored instead of using the default location.

Environment Variable	Description
`QML_DISABLE_DISK_CACHE`	Disables the disk cache and forces re-compilation from source for all QML and JavaScript files. `QML_DISABLE_DISK_CACHE` overrides `QML_DISK_CACHE`.
`QML_FORCE_DISK_CACHE`	Enables the disk cache even when debugging QML. You cannot use the JavaScript debugger this way. It may fail to stop at breakpoints, for example. You can still use the QML inspector to explore the object hierarchy, though. `QML_FORCE_DISK_CACHE` overrides `QML_DISABLE_DISK_CACHE` and `QML_DISK_CACHE`.
`QML_DISK_CACHE_PATH`	Specifies a custom location where the cache files shall be stored instead of using the default location.