diff options
Diffstat (limited to 'src/qml/doc/src/qmldiskcache.qdoc')
| -rw-r--r-- | src/qml/doc/src/qmldiskcache.qdoc | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmldiskcache.qdoc b/src/qml/doc/src/qmldiskcache.qdoc new file mode 100644 index 0000000000..90d9aee723 --- /dev/null +++ b/src/qml/doc/src/qmldiskcache.qdoc @@ -0,0 +1,120 @@ +// Copyright (C) 2019 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmldiskcache.html +\title The QML Disk Cache +\brief QML documents are generally pre-compiled or cached after compilation. + +You should define your QML modules using \l{qt_add_qml_module} that makes sure +that the \l{Qt Quick Compiler} processes your QML and JavaScript files ahead of +time. Also, it guarantees optimum performance at run time. The +\l{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 +\l{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 \l{qmake} you can specify \c{CONFIG += qtquickcompiler} to +give similar treatment to QML and JavaScript files added as resources to your +project. \l{Qt Creator} has a setting that allows passing +\c{CONFIG += qtquickcompiler} to the qmake command line. By default, it is +enabled for release and profile builds. \l{qmake} cannot pass as much +information to the \l{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 \c{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: +\list + \li The Qt version has not changed + \li The source code in the original file has not changed + \li The QML debugger is not running +\endlist + +Only the \c{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 \c{QML_DISK_CACHE}. This +variable takes a comma-separated list of options, for example: + +\badcode +QML_DISK_CACHE=aot,qmlc-read +\endcode + +The available options are as follows: + +\table + \header + \li Option + \li Description + \row + \li aot-native + \li Load the compilation units compiled ahead of time and allow + execution of any native code found in them. + \row + \li aot-bytecode + \li Load the compilation units compiled ahead of time and allow + interpretation and just-in-time compilation of byte code found + in them. + \row + \li aot + \li Shorthand for \c{aot-native,aot-bytecode}. + \row + \li qmlc-read + \li 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. + \row + \li qmlc-write + \li 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. + \row + \li qmlc + \li Shorthand for \c{qmlc-read,qmlc-write}. +\endtable + +Furthermore, you can use the following environment variables: + +\table + \header + \li Environment Variable + \li Description + \row + \li \c{QML_DISABLE_DISK_CACHE} + \li Disables the disk cache and forces re-compilation from source for + all QML and JavaScript files. \c{QML_DISABLE_DISK_CACHE} overrides + \c{QML_DISK_CACHE}. + \row + \li \c{QML_FORCE_DISK_CACHE} + \li 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. \c{QML_FORCE_DISK_CACHE} overrides + \c{QML_DISABLE_DISK_CACHE} and \c{QML_DISK_CACHE}. + \row + \li \c{QML_DISK_CACHE_PATH} + \li Specifies a custom location where the cache files shall be stored + instead of using the default location. +\endtable + +*/ |