qmldiskcache.qdoc

Go to the documentation of this file.

// 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{\QC Documentation}{\QC} 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
    \li The \l{Validation of ahead of time generated native code}{validation of AOT code} succeeds
\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
 
\section1 Validation of ahead of time generated native code
 
The native code generated by the \l{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
\c{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
\c{QV4_FAIL_ON_INVALID_AOT} environment variable that will terminate the program
in case of a failed validation. Finally, passing \c{NO_GENERATE_AOT_VALIDATION}
to \l{qt_add_qml_module} disables the feature completely and prevents the
\l{Qt Quick Compiler} from generating the metadata and validation logic.
 
*/