diff options
author | Ulf Hermann <ulf.hermann@qt.io> | 2023-03-15 08:41:14 +0100 |
---|---|---|
committer | Ulf Hermann <ulf.hermann@qt.io> | 2023-03-28 20:54:27 +0200 |
commit | a6f5a3886d84d316da54c04a937efb13d246b7b0 (patch) | |
tree | 05f2e365546be418fb980e6f8cd8ef2cb0c48ec7 | |
parent | 2a6151097e0dffc3722023b206c35d6535354096 (diff) |
Doc: Rename and rephrase pages for QML {script|type} compiler
They describe the user facing concepts, not the actual tools. In the
case of QML script compiler there are two tools that implement it.
Clarify what qmlsc and qmlcachegen actually do and highlight the
differences.
Also, lower case all references to type compiler and script compiler.
They are not product names and therefore should not be upper cased.
Pick-to: 6.5
Change-Id: If800d368c904bd829d88b7376b107b1c5351a1ed
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
-rw-r--r-- | src/qml/Qt6QmlMacros.cmake | 2 | ||||
-rw-r--r-- | src/qml/doc/src/cmake/qt_add_qml_module.qdoc | 14 | ||||
-rw-r--r-- | src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc | 10 | ||||
-rw-r--r-- | src/qml/doc/src/qtqml-qml-script-compiler.qdoc | 51 | ||||
-rw-r--r-- | src/qml/doc/src/qtqml-qml-type-compiler.qdoc (renamed from src/qml/doc/src/qtqml-tool-qmltc.qdoc) | 6 | ||||
-rw-r--r-- | src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc | 12 | ||||
-rw-r--r-- | src/qml/doc/src/qtqml-tool-qmlsc.qdoc | 30 | ||||
-rw-r--r-- | src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc | 4 | ||||
-rw-r--r-- | tests/auto/qml/CMakeLists.txt | 2 | ||||
-rw-r--r-- | tools/qmltc/CMakeLists.txt | 2 |
10 files changed, 77 insertions, 56 deletions
diff --git a/src/qml/Qt6QmlMacros.cmake b/src/qml/Qt6QmlMacros.cmake index 9c9286ed5c..4caaa888c1 100644 --- a/src/qml/Qt6QmlMacros.cmake +++ b/src/qml/Qt6QmlMacros.cmake @@ -1270,7 +1270,7 @@ function(_qt_internal_qml_add_qmltc_file_mapping_resource qrc_file target qml_fi set(${qrc_file} ${generated_qrc_file} PARENT_SCOPE) endfunction() -# Compile Qml files (.qml) to C++ source files with Qml Type Compiler (qmltc). +# Compile Qml files (.qml) to C++ source files with QML type compiler (qmltc). function(_qt_internal_target_enable_qmltc target) set(args_option "") set(args_single NAMESPACE EXPORT_MACRO_NAME EXPORT_FILE_NAME) diff --git a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc index 3fac1ead65..c235539d98 100644 --- a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc +++ b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc @@ -271,7 +271,7 @@ set_target_properties(someTarget PROPERTIES \endcode Another important argument is \c{--direct-calls}. You can use it to enable the -direct mode of \l{The QML Script Compiler} in case the QtQuick Compiler +direct mode of \l{The QML script compiler} in case the Qt Quick Compiler Extensions are installed. If the extensions are not installed, the argument is ignored. There is a shorthand called \c {QT_QMLCACHEGEN_DIRECT_CALLS} for it. @@ -315,10 +315,10 @@ See \l{qt_target_qml_sources_example}{qt_target_qml_sources()} for an example on how to set the \c QT_QML_SINGLETON_TYPE property. \target qmltc-cmake -\section2 Compiling QML to C++ with QML Type Compiler +\section2 Compiling QML to C++ with QML type compiler If a QML module has \c{.qml} files, you can compile them to C++ using \l{QML -Type Compiler}{qmltc}. Unlike \l{qmlcachegen-auto}{bytecode compilation}, you +type compiler}{qmltc}. Unlike \l{qmlcachegen-auto}{bytecode compilation}, you have to explicitly enable qmltc via \l{ENABLE_TYPE_COMPILER} argument. In which case, \c{.qml} files specified under \c{QML_FILES} would be compiled. Files ending with \c{.js} and \c{.mjs} are ignored as qmltc does not compile @@ -514,7 +514,7 @@ class MyItem: public QQuickItem { ... }; then one has to make sure that the module containing \c QQuickItem, called \c Quick, is declared as a dependency via the \c DEPENDENCIES option. Not doing so might result in errors during type compilation with -\l{QML Type Compiler}{qmltc} or during binding and function compilation to C++ +\l{QML type compiler}{qmltc} or during binding and function compilation to C++ with \l{qmlcachegen-auto}{qmlcachegen}. \note Adding the module to \c DEPENDENCIES is not necessary if the module @@ -689,11 +689,11 @@ work out and deploy all QML modules used by an executable target. \target ENABLE_TYPE_COMPILER \c ENABLE_TYPE_COMPILER can be used to compile \c{.qml} files to C++ source code -with \l{QML Type Compiler}{qmltc}. Files with the source property +with \l{QML type compiler}{qmltc}. Files with the source property \c{QT_QML_SKIP_TYPE_COMPILER} are not compiled to C++. \c TYPE_COMPILER_NAMESPACE argument allows to override the namespace in which -\l{QML Type Compiler}{qmltc} generates code. +\l{QML type compiler}{qmltc} generates code. By default, the namespace of the generated code follows the module hierarchy as depicted in the URI, e.g., \c MyModule for a module with URI \c MyModule or @@ -705,7 +705,7 @@ is inside the MyNamespace. Apart from the "::", C++ namespace naming rules apply. \c QMLTC_QMLTC_EXPORT_DIRECTIVE should be used with \c QMLTC_EXPORT_FILE_NAME when -the classes generated by \l{QML Type Compiler}{qmltc} should be exported from +the classes generated by \l{QML type compiler}{qmltc} should be exported from the qml library. By default, classes generated by qmltc are not exported from their library. The header defining the export macro for the current library diff --git a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc index a1bd1452d0..8b6cd895e8 100644 --- a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc @@ -319,13 +319,13 @@ the file, no matter how deeply nested. With this pragma you can change the way type annotations on functions are handled. By default the interpreter and JIT ignore type annotations, but -the \l{QML Script Compiler} enforces them when compiling to C++. +the \l{QML script compiler} enforces them when compiling to C++. Specifying \c{Enforce} as value makes sure the type annotations are always enforced. The resulting type coercions increase the overhead of calling typed JavaScript functions. -Specifying \c{Ignore} as value makes the \l{QML Script Compiler} ignore +Specifying \c{Ignore} as value makes the \l{QML script compiler} ignore any JavaScript functions when compiling the document to C++. This means less code is compiled to C++ ahead of time, and more code has to be interpreted or JIT-compiled. @@ -336,7 +336,7 @@ JIT-compiled. The behavior of \l{QML Value Types} and list types differs slightly depending on whether a QML document is compiled to C++ using the -\l{QML Script Compiler} or interpreted at run time. +\l{QML script compiler} or interpreted at run time. With this pragma you can change the way value types and sequences are handled when retrieved as locals from properties. By default, the interpreter and JIT @@ -344,7 +344,7 @@ treat all value types and sequences as references. This means, if you change the local value, the original property is also changed. Furthermore, if you write the original property explicitly, the local value is also updated. -When compiled to C++ using the \l{QML Script Compiler}, the local value is not +When compiled to C++ using the \l{QML script compiler}, the local value is not updated when the property is written, and the property is only updated when written directly, without retrieving it as local value before. @@ -379,7 +379,7 @@ confusing. Specifying \c{Copy} as value to the pragma makes the interpreter and JIT behave like the generated C++ code. This is the recommended way to handle the problem. -Specifying \c{Reference} makes the \l{QML Script Compiler} skip any functions +Specifying \c{Reference} makes the \l{QML script compiler} skip any functions that use value types or sequences when generating C++ code. Those functions are then left to be interpreted or JIT-compiled with the default behavior of the interpreter and JIT. diff --git a/src/qml/doc/src/qtqml-qml-script-compiler.qdoc b/src/qml/doc/src/qtqml-qml-script-compiler.qdoc new file mode 100644 index 0000000000..61b71732d6 --- /dev/null +++ b/src/qml/doc/src/qtqml-qml-script-compiler.qdoc @@ -0,0 +1,51 @@ +// 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. + +*/ diff --git a/src/qml/doc/src/qtqml-tool-qmltc.qdoc b/src/qml/doc/src/qtqml-qml-type-compiler.qdoc index 1e44472414..dfad5f36a6 100644 --- a/src/qml/doc/src/qtqml-tool-qmltc.qdoc +++ b/src/qml/doc/src/qtqml-qml-type-compiler.qdoc @@ -2,12 +2,12 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qtqml-tool-qmltc.html -\title QML Type Compiler +\page qtqml-qml-type-compiler.html +\title QML type compiler \brief A tool to compile QML types to C++ ahead of time. \keyword qmltc -The QML Type Compiler, \c qmltc, is a tool shipped with Qt to translate QML +The QML type compiler, \c qmltc, is a tool shipped with Qt to translate QML types into C++ types that are \e{ahead-of-time} compiled as part of the user code. Using qmltc can lead to better run-time performance due to more optimization opportunities available to the compiler compared to a diff --git a/src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc b/src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc index 293546255f..48fa9151b8 100644 --- a/src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc +++ b/src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc @@ -17,17 +17,17 @@ time, rather than at run time. This allows for: The Qt Quick Compiler consist of two components: \list - \li \l {QML Type Compiler} - \li \l {QML Script Compiler} + \li \l {QML type compiler} + \li \l {QML script compiler} \endlist \note \e qmltc, \e qmlsc and \l qmlcachegen are internal build tools. If you need to care about their invocation, you are either writing a build system, or you are doing something wrong. -\subtitle The QML Type Compiler +\subtitle The QML type compiler -The \l{QML Type Compiler}, \e(qmltc) compiles QML types to C++ classes. These C++ +The \l{QML type compiler}, \e(qmltc) compiles QML types to C++ classes. These C++ classes are then added to your application and can be instantiated from other C++ code. This way you can avoid much of the overhead of using \l{QQmlComponent} to create instances of your QML types. In order to benefit from \l qmltc, you @@ -38,9 +38,9 @@ structure. It will fail if an unsupported language feature is encountered. It does not have to understand the JavaScript code in bindings and functions, though. -\subtitle The QML Script Compiler +\subtitle The QML script compiler -The \l{QML Script Compiler}, (\e qmlsc and \e qmlcachegen) compiles bindings and +The \l{QML script compiler}, (\e qmlsc and \e qmlcachegen) compiles bindings and functions to both, an efficient byte code and C++ functions. This process automatically happens behind the scenes if you are using \l{qt_add_qml_module} to specify your QML modules. At compile time, for each QML or JavaScript diff --git a/src/qml/doc/src/qtqml-tool-qmlsc.qdoc b/src/qml/doc/src/qtqml-tool-qmlsc.qdoc deleted file mode 100644 index b1276449fc..0000000000 --- a/src/qml/doc/src/qtqml-tool-qmlsc.qdoc +++ /dev/null @@ -1,30 +0,0 @@ -// Copyright (C) 2022 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\page qtqml-tool-qmlsc.html -\title QML Script Compiler -\brief A tool to compile functions and expressions in QML. -\keyword qmlsc - -The QML Script Compiler, \c qmlsc will compile functions and expressions in QML -files of an application into C++ code within limitations set by the nature of -JavaScript. It replaces \e qmlcachegen, and simply generates C++ code in addition -to byte code for functions that can be exhaustively analyzed. The following flow -chart explains the compilation of \e qmlsc. - -\image qmlsc-compilation-scheme.png - -\section1 Limitations when compiling JavaScript - -Many JavaScript constructs cannot be efficiently represented in C++. \e qmlsc -skips the C++ code generation for functions that contain such constructs and -only generates byte code to be interpreted. Although, 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. - -\e qmlsc is available for commercial customers and some of its features are -merged into \e qmlcachegen, which continues to be available with all versions of -Qt. -*/ diff --git a/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc b/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc index 50b929e0ed..010126a1e1 100644 --- a/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc +++ b/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc @@ -98,7 +98,7 @@ all the available options. The Qt Quick Compiler consist of two components: \list - \li \l {QML Type Compiler} - \li \l {QML Script Compiler} + \li \l {QML type compiler} + \li \l {QML script compiler} \endlist */ diff --git a/tests/auto/qml/CMakeLists.txt b/tests/auto/qml/CMakeLists.txt index e5b6de7b8c..950a95abd7 100644 --- a/tests/auto/qml/CMakeLists.txt +++ b/tests/auto/qml/CMakeLists.txt @@ -55,7 +55,7 @@ endif() add_subdirectory(qqmlmetatype) if(TARGET Qt::Quick) add_subdirectory(qmltc_manual) - # QML Type Compiler tests cannot be run on webOS due to missing support for multiple + # QML type compiler tests cannot be run on webOS due to missing support for multiple # consecutive window creation from a single QtWayland client if(NOT WEBOS) add_subdirectory(qmltc) diff --git a/tools/qmltc/CMakeLists.txt b/tools/qmltc/CMakeLists.txt index 8e7ce0a586..42e47e24da 100644 --- a/tools/qmltc/CMakeLists.txt +++ b/tools/qmltc/CMakeLists.txt @@ -3,7 +3,7 @@ qt_get_tool_target_name(target_name qmltc) qt_internal_add_tool(${target_name} - TARGET_DESCRIPTION "QML Type Compiler" + TARGET_DESCRIPTION "QML type compiler" TOOLS_TARGET Qml SOURCES main.cpp |