1// Copyright (C) 2019 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6\title The QML Disk Cache
7\brief QML documents are generally pre-compiled or cached after compilation.
9You should define your QML modules using \l{qt_add_qml_module} that makes sure
10that the \l{Qt Quick Compiler} processes your QML and JavaScript files ahead of
11time. Also, it guarantees optimum performance at run time. The
12\l{Qt Quick Compiler} generates byte code for
13each function and binding. This byte code can be used by the QML interpreter,
14and the Just-in-time (JIT) compiler in the QML engine. In addition, the
15\l{Qt Quick Compiler} generates native code for suitable functions and
16bindings. The native code can be executed directly, which results in better
17performance than interpreting or just-in-time compiling the byte code. Both,
18byte code and native code are then compiled into your binary.
20When using \l{qmake} you can specify \c{CONFIG += qtquickcompiler} to
21give similar treatment to QML and JavaScript files added as resources to your
22project. \l{Qt Creator} has a setting that allows passing
23\c{CONFIG += qtquickcompiler} to the qmake command line. By default, it is
24enabled for release and profile builds. \l{qmake} cannot pass as much
25information to the \l{Qt Quick Compiler} as CMake. Therefore, the compilation
26will contain less native code.
28You should make sure to load your QML documents from the resource file system
29where possible. Otherwise the QML engine won't be able to find the code compiled
32If no byte code or native code can be found for a QML document at run time, or
33if the code is found but cannot be used, the QML engine compiles the document
34into a byte code representation on the fly. The compiling process can be time
35consuming, and the result will contain only byte code. Subsequent loads of the
36same document will yield the same byte code. The QML engine can optimize this
37step by caching the result of the compilation. It stores the byte code in a
38cache file and later loads the cache file instead of re-compiling when the same
39QML document is requested again. Usually, the cache files are stored in a
40subdirectory \c{qmlcache} of the system's cache directory, as denoted by
41QStandardPaths::CacheLocation.
43Checks are in place to make sure that any cache files and any code compiled
44ahead of time are only loaded if all of the following conditions are met:
46 \li The Qt version has not changed
47 \li The source code in the original file has not changed
48 \li The QML debugger is not running
51Only the \c{QML_FORCE_DISK_CACHE} variable (see below) overrides only the
52condition regarding the QML debugger. The other environment variables do not
53influence these conditions.
55The primary way of fine tuning the behavior regarding ahead of time compiled
56code and caching is via the environment variable \c{QML_DISK_CACHE}. This
57variable takes a comma-separated list of options, for example:
60QML_DISK_CACHE=aot,qmlc-read
63The available options are as follows:
71 \li Load the compilation units compiled ahead of time and allow
72 execution of any native code found in them.
75 \li Load the compilation units compiled ahead of time and allow
76 interpretation and just-in-time compilation of byte code found
80 \li Shorthand for \c{aot-native,aot-bytecode}.
83 \li Load any cached compilation units for QML and JavaScript files from
84 the host file system and allow interpretation and just-in-time
85 compilation of byte code found in them.
88 \li When compiling a QML or JavaScript file on the fly, create a cache
89 file afterward. The cache file can be loaded when the same
90 document is requested again.
93 \li Shorthand for \c{qmlc-read,qmlc-write}.
96Furthermore, you can use the following environment variables:
100 \li Environment Variable
103 \li \c{QML_DISABLE_DISK_CACHE}
104 \li Disables the disk cache and forces re-compilation from source for
105 all QML and JavaScript files. \c{QML_DISABLE_DISK_CACHE} overrides
108 \li \c{QML_FORCE_DISK_CACHE}
109 \li Enables the disk cache even when debugging QML. You cannot use the
110 JavaScript debugger this way. It may fail to stop at breakpoints,
111 for example. You can still use the QML inspector to explore the
112 object hierarchy, though. \c{QML_FORCE_DISK_CACHE} overrides
113 \c{QML_DISABLE_DISK_CACHE} and \c{QML_DISK_CACHE}.
115 \li \c{QML_DISK_CACHE_PATH}
116 \li Specifies a custom location where the cache files shall be stored
117 instead of using the default location.