- Qt 6.12
- Qt Qml
- Advanced QML Topics
- The QML Disk Cache
- Qt 6.12.0 Reference Documentation

Advanced QML Topics ◦ Configuring the JavaScript Engine

# The QML Disk Cache

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.

## QML Caching

The QML runtime loads QML documents by parsing them and generating byte code. Most of the time, the document hasn't changed since the last time it was loaded. To speed up this loading process, the QML runtime maintains a cache file for each QML document. This cache file contains the compiled byte code and a binary representation of the QML document structure. In addition, when multiple applications use the same QML document, the memory needed for the code is shared between application processes. The cache files are loaded via the `mmap()` system call on POSIX-compliant operating systems or `CreateFileMapping()` on Windows, resulting in significant memory savings.

Each time you load a changed QML document, the cache is automatically re-created. Cache files are located in a sub-directory of QStandardPaths::CacheLocation with the name "qmlcache". The file extension is `.qmlc` for QML documents and `.jsc` for imported JavaScript modules.

## Ahead-of-Time compilation

The automatic caching of compiled QML documents into cache files results in significantly faster application load time. However, the initial creation of cache files can still take time, especially when the application starts for the very first time. To avoid that initial step and provide faster startup times from the very beginning, Qt's build system allows you to perform the compilation step for QML files ahead of time, when compiling the C++ parts of your application.

One benefit of compiling ahead of time is that, in the event of syntax errors in your QML documents, you are notified at application compile-time instead of at run-time, when the file is loaded.

This will happen automatically if you use the CMake QML Module API, for qmake see the section below.

### qmake

When using qmake, in order to deploy your application with QML files compiled ahead of time, you must organize the files and the build system in a specific way:

- All QML documents (including JavaScript files) must be included as resources via Qt's Resource system.
- Your application must load the QML documents via the `qrc:///` URL scheme.
- You can enable Ahead-of-Time compilation using the `CONFIG+=qtquickcompiler` directive.

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
- The validation of AOT code succeeds

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

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.

## Validation of ahead of time generated native code

The native code generated by the Qt Quick Compiler has some assumptions built in. If the conditions in which the code is executed differ from those in which it was compiled, the code may be unsafe to use. Therefore, the native code is validated at runtime using metadata stored alongside it. If this validation passes, the code is executed as normal. If it fails, the execution silently falls back to interpreting the bytecode instead. This validation happens once per file, the first time the code is loaded, and either approves or rejects all functions and bindings in that QML file as a whole.

The validation of AOT code can be customized. By default, the validation is enabled but it can be skipped at runtime by setting the `QV4_SKIP_AOT_VALIDATION` environment variable to avoid paying the small overhead of performing the validation. By contrast, if you wish to ensure that validation succeeds at runtime (in order to make sure compiled functions are indeed executed as native code, for example), you can set the `QV4_FAIL_ON_INVALID_AOT` environment variable that will terminate the program in case of a failed validation. Finally, passing `NO_GENERATE_AOT_VALIDATION` to qt_add_qml_module disables the feature completely and prevents the Qt Quick Compiler from generating the metadata and validation logic.

Advanced QML Topics ◦ Configuring the JavaScript Engine