diff options
Diffstat (limited to 'src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc')
| -rw-r--r-- | src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc new file mode 100644 index 0000000000..302c71882a --- /dev/null +++ b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc @@ -0,0 +1,120 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-qml-script-compiler.html +\title QML script compiler +\brief A tool to compile functions and expressions in QML. +\keyword qmlsc +\ingroup qtqml-tooling + +The QML script compiler compiles functions and expressions in QML and JavaScript +files to a byte code that can be interpreted or Just-in-time compiled by the +QML engine. + +In addition, it compiles some functions and expressions in QML files into C++ +code, within limitations set by the nature of JavaScript. It generates C++ code +for functions that can be exhaustively analyzed. The following flow chart +explains the compilation workflow. + +\image qmlsc-compilation-scheme.png + +QML script compiler is available in two versions. One is \e qmlcachegen, which +is a part of the \l{Qt Quick Compiler}. Another one is \e qmlsc, which is a part +of the commercial-only add-on \e{Qt Quick Compiler Extensions}. + +\section1 qmlcachegen +\e qmlcachegen uses the meta-object system and generates lookups and stores them in a +central place, a compilation unit. The compilation unit contains a representation of +document structure, compact byte code representation for each function and expression, +and native code for functions and bindings that compiler fully understands. +The byte code in a compilation unit can be used by the QML engine to avoid re-compilation +and to speed up execution. + +\section1 qmlsc +\e qmlsc, on the flip side, extends the base functionality of qmlcachegen by providing +two extra modes. + +\list +\li \l {static mode} +\li \l {direct mode} +\endlist + +\section2 static mode +In static mode, qmlsc assumes that no properties of any types exposed to C++ can be +shadowed by derived types. It eliminates the shadow checking mechanism and allows more +JavaScript code to be compiled to C++ and eventually generates faster code. + +To enable static mode in qmlsc, you should pass \c{--static} via \c{QT_QMLCACHEGEN_ARGUMENTS} to \l{qt_add_qml_module}. +\badcode + qt_add_qml_module(someTarget + ... + ) + + set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--static" + ) +\endcode + +\warning qmlsc static-mode generates invalid code if any properties are shadowed in +the QML document. + +\section2 direct mode +In direct mode, qmlsc assumes that all C++ types used in your QML code are available +and can be included as C++ headers to the generated code. Then the generated code +accesses or modifies properties by directly calling getters, setters and invokable +functions in those headers which makes the execution even faster. This means you have to +link to private Qt APIs in CMake. + +\warning Private Qt APIs change often. You will need to recompile Qt for each new version. + +\warning If a type is only defined in a plugin or has no header, you can’t use it in direct mode. + +To enable direct mode, you should consider the followings: + +\list + \li you should pass \c{--direct-calls} via \c{QT_QMLCACHEGEN_ARGUMENTS} to \l{qt_add_qml_module}. + +\badcode + qt_add_qml_module(someTarget + ... + ) + + set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--direct-calls" + ) +\endcode + + \li Link all the relavant private Qt modules instead of their public counterparts. +\badcode + qt_add_qml_module(someTarget + ... + ) + + target_link_libraries(someTarget PRIVATE + Qt::QmlPrivate + Qt::QuickPrivate + ... + ) +\endcode + + \li Do not set the \c{PLUGIN_TARGET} to be the same as the backing library target. +\badcode + # direct mode will not function in this setup. + qt_add_qml_module(someTarget + PLUGIN_TARGET someTarget + ... + ) +\endcode +\endlist + +\section1 Limitations when compiling JavaScript to C++ + +Many JavaScript constructs cannot be efficiently represented in C++. The QML +script compiler skips the C++ code generation for functions that contain such +constructs and only generates byte code to be interpreted or run through the +Just-in-time compiler. Most common QML expressions are rather simple: value +lookups on QObjects, arithmetics, simple if/else or loop constructs. Those can +easily be expressed in C++, and doing so makes your application run faster. + +*/ |