qtqml-qml-script-compiler.qdoc

Go to the documentation of this file.

// 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
 
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
 
\section1 qmlsc and qmlcachegen
 
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}.
 
The base functionality of the QML script compiler is available in both the
\e qmlsc tool and the \e qmlcachegen tool. \e qmlsc can generate more efficient
C++ code when run in \e direct mode. It is enabled by passing \c{--direct-calls}
via \c QT_QMLCACHEGEN_ARGUMENTS to \l{qt_add_qml_module}. In direct mode
\e qmlsc expects that all C++ types used in your QML code can be made available
to the generated code by simple C++ include statements. This means you have to
link to private Qt APIs by passing Qt::QuickPrivate, Qt::QmlPrivate, etc to
link_libraries() in CMake. \e qmlcachegen does not implement direct mode and
ignores the \e{--direct-calls} option. Furthermore, \e qmlsc accepts
a \e {--static} option that you can also pass via \e QT_QMLCACHEGEN_ARGUMENTS
in \l qt_add_qml_module. In \e static mode, \e qmlsc ignores shadowing of
properties. This is dangerous if your code actually shadows properties, but
allows for more JavaScript code to be compiled to C++. \e qmlcachegen ignores
the \e {--static} option.
 
\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.
 
*/