1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qtqml-qml-script-compiler.html
6\title QML script compiler
7\brief A tool to compile functions and expressions in QML.
11The QML script compiler compiles functions and expressions in QML and JavaScript
12files to a byte code that can be interpreted or Just-in-time compiled by the
15In addition, it compiles some functions and expressions in QML files into C++
16code, within limitations set by the nature of JavaScript. It generates C++ code
17for functions that can be exhaustively analyzed. The following flow chart
18explains the compilation workflow.
20\image qmlsc-compilation-scheme.png
22QML script compiler is available in two versions. One is \e qmlcachegen, which
23is a part of the \l{Qt Quick Compiler}. Another one is \e qmlsc, which is a part
24of the commercial-only add-on \e{Qt Quick Compiler Extensions}.
27\e qmlcachegen uses the meta-object system and generates lookups and stores them in a
28central place, a compilation unit. The compilation unit contains a representation of
29document structure, compact byte code representation for each function and expression,
30and native code for functions and bindings that compiler fully understands.
31The byte code in a compilation unit can be used by the QML engine to avoid re-compilation
32and to speed up execution.
35\e qmlsc, on the flip side, extends the base functionality of qmlcachegen by providing
44In static mode, qmlsc assumes that no properties of any types exposed to C++ can be
45shadowed by derived types. It eliminates the shadow checking mechanism and allows more
46JavaScript code to be compiled to C++ and eventually generates faster code.
48To enable static mode in qmlsc, you should pass \c{--static} via \c{QT_QMLCACHEGEN_ARGUMENTS} to \l{qt_add_qml_module}.
50 qt_add_qml_module(someTarget
54 set_target_properties(someTarget PROPERTIES
55 QT_QMLCACHEGEN_ARGUMENTS "--static"
59\warning qmlsc static-mode generates invalid code if any properties are shadowed in
63In direct mode, qmlsc assumes that all C++ types used in your QML code are available
64and can be included as C++ headers to the generated code. Then the generated code
65accesses or modifies properties by directly calling getters, setters and invokable
66functions in those headers which makes the execution even faster. This means you have to
67link to private Qt APIs in CMake.
69\warning Private Qt APIs change often. You will need to recompile Qt for each new version.
71\warning If a type is only defined in a plugin or has no header, you can’t use it in direct mode.
73To enable direct mode, you should consider the followings:
76 \li you should pass \c{--direct-calls} via \c{QT_QMLCACHEGEN_ARGUMENTS} to \l{qt_add_qml_module}.
79 qt_add_qml_module(someTarget
83 set_target_properties(someTarget PROPERTIES
84 QT_QMLCACHEGEN_ARGUMENTS "--direct-calls"
88 \li Link all the relavant private Qt modules instead of their public counterparts.
90 qt_add_qml_module(someTarget
94 target_link_libraries(someTarget PRIVATE
101 \li Do not set the \c{PLUGIN_TARGET} to be the same as the backing library target.
103 # direct mode will not function in this setup.
104 qt_add_qml_module(someTarget
105 PLUGIN_TARGET someTarget
111\section1 Limitations when compiling JavaScript to C++
113Many JavaScript constructs cannot be efficiently represented in C++. The QML
114script compiler skips the C++ code generation for functions that contain such
115constructs and only generates byte code to be interpreted or run through the
116Just-in-time compiler. Most common QML expressions are rather simple: value
117lookups on QObjects, arithmetics, simple if/else or loop constructs. Those can
118easily be expressed in C++, and doing so makes your application run faster.