diff options
Diffstat (limited to 'src/qml/doc/src/qmldiskcache.qdoc')
| -rw-r--r-- | src/qml/doc/src/qmldiskcache.qdoc | 133 |
1 files changed, 88 insertions, 45 deletions
diff --git a/src/qml/doc/src/qmldiskcache.qdoc b/src/qml/doc/src/qmldiskcache.qdoc index 100334296c..90d9aee723 100644 --- a/src/qml/doc/src/qmldiskcache.qdoc +++ b/src/qml/doc/src/qmldiskcache.qdoc @@ -1,53 +1,99 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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 caches compiled documents on disk to improve load time. +\brief QML documents are generally pre-compiled or cached after compilation. -When your application loads a QML or JavaScript file for the first time, -the QML engine compiles the file into a byte code representation on the -fly and runs it. The compiling process can be time consuming, and subsequent -loads of the same document yield the same result. To optimize this step, the -QML engine can cache the result. It stores the byte code in a cache file and -later loads the cache file instead of re-compiling when the same file is -requested again. Usually the 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 the cache files are only loaded if all -of the following conditions are met: +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 -The disk caching behavior can be fine tuned using the following environment -variables: +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 @@ -56,22 +102,19 @@ variables: \row \li \c{QML_DISABLE_DISK_CACHE} \li Disables the disk cache and forces re-compilation from source for - all QML and JavaScript files. + 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}. + \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 -You can also specify \c{CONFIG += qtquickcompiler} in your \c{.pro} file -to perform the compilation ahead of time and integrate the resulting byte code -directly into your executable. For more information, see \l{Qt Quick Compiler}. - */ |