From 967e916d210e2bcacafbf8d685b2328c5f888d0c Mon Sep 17 00:00:00 2001 From: Kavindra Palaraja Date: Wed, 3 Jul 2019 14:21:26 +0200 Subject: [PATCH] Doc: Cleanup of the Deploying QML Applications topic Change-Id: Ie2fb81c48cab828c2d0706761478b7388ef6f630 Reviewed-by: Ulf Hermann --- doc/src/qmlapp/deployment.qdoc | 240 +++++++++++++++------------------ 1 file changed, 110 insertions(+), 130 deletions(-) diff --git a/doc/src/qmlapp/deployment.qdoc b/doc/src/qmlapp/deployment.qdoc index 30adcc44e..844cea9a8 100644 --- a/doc/src/qmlapp/deployment.qdoc +++ b/doc/src/qmlapp/deployment.qdoc @@ -28,138 +28,117 @@ /*! \page qtquick-deployment.html \title Deploying QML Applications -\brief Deploying QML applications +\brief Provides information on how to use deploy QML applications. +QML documents are loaded and run by the QML runtime. This includes the Declarative UI engine +along with the built-in QML types and plugin modules. The QML runtime also provides access +to third-party QML types and modules. -QML documents are loaded and executed by the QML runtime. This includes the -Declarative UI engine along with the built-in QML types and plugin modules, -and it also provides access to third-party QML types and modules. - -Applications that use QML need to invoke the QML runtime in order to -execute QML documents. This can be done by creating a QQuickView -or a QQmlEngine, as described below. In addition, the Declarative UI -package includes the qmlscene tool, which loads \c .qml files. This tool is -useful for developing and testing QML code without the need to write -a C++ application to load the QML runtime. +Applications that use QML must invoke the QML runtime to run QML documents. You can do this by +creating a QQuickView or a QQmlEngine, as described below. In addition, the Declarative UI +package includes the qmlscene tool, which loads \c .qml files. This tool is useful for developing +and testing QML code without having to write a C++ application to load the QML runtime. \section1 Deploying Applications with Qt Creator -\l{Qt Creator Manual}{Qt Creator} deploys and packages QML applications to -various platforms. For mobile devices, Qt Creator can directly bundle -applications to the respective platform package formats such as APK. +\l{Qt Creator Manual}{Qt Creator} deploys and packages QML applications to various platforms. +For mobile devices, Qt Creator can directly bundle applications to the respective platform +package formats, such as APK. -For more information, visit: -\list -\li \l{Deploying Qt Applications} -\li \l{Qt Creator: Running on Multiple Platforms}{Running on Multiple Platforms} -\li \l{Qt Creator: Deploying to Devices}{Deploying to Devices} -\endlist - -When running applications on the target platform, the application needs to -access the location of the QML libraries. When using \l{qmake Manual}{qmake}, -the \c QT_INSTALL_QML environment points to the location of the libraries. -The \l{Downloads}{Qt Installers} install the QML libraries in -\e{}\c{/}\e{}\c{/qml} directory. +When you run your applications on the target platform, your application needs to access +the location of the QML libraries. If you use \l{qmake Manual}{qmake}, the +\c QT_INSTALL_QML environment variable points to the location of the libraries. The +\l{Downloads}{Qt Installers} install the QML libraries in: +\c{}\c{/}\e{}\c{/qml} directory. \section1 QML Caching -The QML runtime loads QML documents by parsing them and generating byte code. -Most of the time the document hasn't changed since the last time it was loaded. -In order to speed up this loading process, the QML runtime maintains a cache -file for each qml document. This cache file contains the compiled byte code and a -binary representation of the QML document structure. In addition, when multiple -applications use the same QML document, the memory needed for the code is -shared between application processes. The cache files are loaded via the \c -mmap() system call on POSIX compliant operating systems or \c -CreateFileMapping() on Windows, resulting in significant memory savings. +The QML runtime loads QML documents by parsing them and generating byte code. Most of the time, +the document hasn't changed since the last time it was loaded. To speed up this loading process, +the QML runtime maintains a cache file for each QML document. This cache file contains the +compiled byte code and a binary representation of the QML document structure. In addition, when +multiple applications use the same QML document, the memory needed for the code is shared between +application processes. The cache files are loaded via the \c mmap() system call on POSIX-compliant +operating systems or \c CreateFileMapping() on Windows, resulting in significant memory savings. -Each time you load a changed QML document, the cache is automatically -re-created. Cache files are located in a sub-directory of -QStandardPaths::CacheLocation with the name "qmlcache". The file extension is \c -.qmlc for QML documents and \c .jsc for imported JavaScript modules. +Each time you load a changed QML document, the cache is automatically re-created. Cache files are +located in a sub-directory of QStandardPaths::CacheLocation with the name "qmlcache". The file +extension is \c .qmlc for QML documents and \c .jsc for imported JavaScript modules. -\section1 Compiling QML Ahead of Time +\target Compiling Ahead of Time +\section1 Ahead-of-Time Compilation -The automatic caching of compiled QML documents into cache files results in -significantly faster load times of applications. However, the initial creation -of cache files can still take time, especially when the application starts for -the very first time. To avoid that initial step and provide faster start-up -times from the very beginning, Qt's build system allows you to perform the -compilation step for QML files at the same time as the rest of your -application. +The automatic caching of compiled QML documents into cache files results in significantly faster +application load time. However, the initial creation of cache files can still take time, especially +when the application starts for the very first time. To avoid that initial step and provide faster +startup times from the very beginning, Qt's build system allows you to perform the compilation step +for QML files ahead of time, when compiling the C++ parts of your application. -If you would like to deploy your application with QML files compiled ahead of -time, then you must organize the files and the build system in a specific way: +To deploy your application with QML files compiled ahead of time, you must organize the files and +the build system in a specific way: \list -\li All QML documents (including JavaScript files) must be included as resources -through \l{The Qt Resource System}{Qt's Resource system}. -\li Your application must load the QML documents via the \c qrc:/// URL scheme. -\li You can enable Ahead-of-Time compilation using the \c CONFIG+=qtquickcompiler directive. -\li If you are using the CMake build system, then you can achieve this inserting a -\c find_package(Qt5QuickCompiler) call into your \c CMakeLists.txt and replace the use of -of \c qt5_add_resources with \c qtquick_compiler_add_resources . + \li All QML documents (including JavaScript files) must be included as resources via + \l{The Qt Resource System}{Qt's Resource system}. + \li Your application must load the QML documents via the \c qrc:/// URL scheme. + \li You can enable Ahead-of-Time compilation using the \c CONFIG+=qtquickcompiler directive. + \li If you're using the CMake build system, then you can achieve this by inserting a + \c find_package(Qt5QuickCompiler) call into your \c CMakeLists.txt and replacing the use + of \c qt5_add_resources with \c qtquick_compiler_add_resources. \endlist -One added benefit of this way of developing and deploying the application is -that you will be notified of syntax errors in your QML documents at application -compile time, instead of run-time when loading the file. +One benefit of compiling ahead of time is that, in the event of syntax errors in your QML +documents, you are notified at application compile-time instead of at run-time, when the file is +loaded. -If you have \c .qml or \c .js files which should not be compiled but just -bundled by the resource system (for example, \c .js files used with \l{Qt -WebEngine}), then you can omit them from the compilation by specifying the -resources files that contain them in the \c QTQUICK_COMPILER_SKIPPED_RESOURCES -variable in your project file, like below: +If you have \c .qml or \c .js files which should not be compiled but just bundled by the resource +system, such as \c .js files used with \l{Qt WebEngine}, you can omit them from the compilation +via the \c QTQUICK_COMPILER_SKIPPED_RESOURCES variable. In your project file, specify the resource +files to omit, as follows: \code QTQUICK_COMPILER_SKIPPED_RESOURCES += bundle_only.qrc \endcode -By default this feature will tie your application to the Qt version you are -compiling against, because it will replace the QML document source code in the -resources with the compiled binary version. The source files are not present -anymore. That means that when using the same application against a different -version of Qt without recompiling it, loading the QML documents will fail with -an error message. +By default, this feature ties your application to the Qt version you are compiling against, because +it replaces the QML document source code in the resources with the compiled binary version. The +source files are not present anymore. Consequently, when you use the same application against a +different version of Qt without recompiling it, loading the QML documents will fail with an error +message. -The Ahead-of-Time compilation is implemented this way because the feature -originates from an add-on for use in commercial application environments, where -the deployment of source code is not desirable and requiring a recompilation -when changing Qt is usually acceptable. +Ahead-of-Time compilation is implemented this way because the feature originates from an add-on for +use in commercial application environments, where deploying source code is not desirable but it's +usually acceptable to require a recompilation when changing Qt. -You can retain the QML and JavaScript documents in the resources by passing a -list of resource (*.qrc) files in the \c QTQUICK_COMPILER_RETAINED_RESOURCES -qmake variable. These resource files will then not be filtered, and any QML and -JavaScript files specified in them will be readable in full source by your -application. If you then run the application with a different version of Qt, -the QML and JavaScript files will be recompiled at runtime, slowing down the +You can retain the QML and JavaScript documents in the resources by passing a list of resource +\c{(*.qrc)} files in the \c QTQUICK_COMPILER_RETAINED_RESOURCES qmake variable. These resource +files will then not be filtered, and any QML and JavaScript files specified in them will be +readable in full source by your application. Then, if you run the application with a different +Qt version, the QML and JavaScript files will be recompiled at runtime, slowing down the initial start of the application. \section1 Prototyping with QML Scene -The Declarative UI package includes a QML runtime tool, -\l{qtquick-qmlscene.html}{qmlscene}, which loads and displays QML documents. -This is useful during the application development phase for prototyping -QML-based applications without writing your own C++ applications to invoke +The Declarative UI package includes a QML runtime tool, \l{qtquick-qmlscene.html}{qmlscene}, +which loads and displays QML documents. This is useful during the application development phase +for prototyping QML-based applications without writing your own C++ applications to invoke the QML runtime. \section1 Initializing the QML Runtime in Applications -To run an application that uses QML, the QML runtime must be invoked by -the application. This is done by writing a Qt C++ application that loads the -QQmlEngine by either: +To run an application that uses QML, your application must invoke the QML runtime. This is done +by writing a Qt C++ application that loads the QQmlEngine by either: \list -\li Loading the QML file through a QQuickView instance, or -\li Creating a QQmlEngine instance and loading QML files with QQmlComponent + \li Loading the QML file through a QQuickView instance. + \li Creating a QQmlEngine instance and loading QML files with QQmlComponent. \endlist \section2 Initializing with QQuickView -QQuickView is a QWindow-based class that is able to load QML files. -For example, if there is a QML file, \c application.qml, it will -look like this: +QQuickView is a QWindow-based class that can load QML files. For example, if there is a QML file, +\c application.qml, it will look like this: \qml import QtQuick 2.3 @@ -185,8 +164,7 @@ It can be loaded in a Qt application's \c main.cpp file like this: } \endcode -This creates a QWindow-based view that displays the contents of -\c application.qml. +This creates a QWindow-based view that displays the contents of \c application.qml. The application's \c .pro \l{Creating Project Files}{project file} must specify the \c declarative module for the \c QT variable. For example: @@ -198,12 +176,12 @@ the \c declarative module for the \c QT variable. For example: \endcode -\section2 Creating a QQmlEngine directly +\section2 Creating a QQmlEngine Directly -If \c application.qml does not have any graphical components, or if it is -preferred to avoid QQuickView for other reasons, the QQmlEngine -can be constructed directly instead. In this case, \c application.qml is -loaded as a QQmlComponent instance rather than placed into a view: +If \c application.qml doesn't have any graphical components, or if it's preferred to +avoid QQuickView for other reasons, the QQmlEngine can be constructed directly instead. +In this case, \c application.qml is loaded as a QQmlComponent instance rather than placed into +a view: \code #include @@ -227,41 +205,36 @@ loaded as a QQmlComponent instance rather than placed into a view: } \endcode -QGuiApplication can be replaced by a QCoreApplication in the code above in case you are not -using any graphical items from Qt Quick. This allows using QML as a language without any -dependencies to the \l {Qt GUI} module. - -See \l{qtqml-cppintegration-data.html}{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Types to QML} -for more information about using QQmlEngine, QQmlContext and QQmlComponent, as well -as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}. +If you're not using any graphical items from Qt Quick, you can replace QGuiApplication with a +QCoreApplication in the code above. This way, you can use QML as a language without any +dependencies to the \l{Qt GUI} module. \section1 Managing Resource Files with the Qt Resource System -The \l {The Qt Resource System}{Qt resource system} allows resource files to be stored as -binary files in an application executable. This can be useful when building a mixed -QML/C++ application as it enables QML files (as well as other resources such as images -and sound files) to be referred to through the resource system URI scheme rather than -relative or absolute paths to filesystem resources. Note, however, that if you use the resource -system, the application executable must be re-compiled whenever a QML source file is changed -in order to update the resources in the package. +The \l {The Qt Resource System}{Qt resource system} allows resource files to be stored as binary +files in an application executable. This can be useful when building a mixed QML/C++ application +as it enables QML files and other resources -- such as images and sound files -- to be referred +to through the resource system URI scheme rather than relative or absolute paths to filesystem +resources. + +\note If you use the resource system, the application executable must be re-compiled whenever a +QML source file is changed, to update the resources in the package. To use the resource system in a mixed QML/C++ application: \list \li Create a \c .qrc \l {The Qt Resource System}{resource collection file} that lists resource - files in XML format + files in XML format. \li From C++, load the main QML file as a resource using the \c :/ prefix or as a URL with the - \c qrc scheme + \c .qrc scheme. \endlist -Once this is done, all files specified by relative paths in QML will be loaded from -the resource system instead. Use of the resource system is completely transparent to -the QML layer; this means all QML code should refer to resource files using relative -paths and should \e not use the \c qrc scheme. This scheme should only be used from -C++ code for referring to resource files. +Once this is done, all files specified by relative paths in QML are loaded from the resource +system instead. Use of the resource system is completely transparent to the QML layer; this means +all QML code should refer to resource files using relative paths and should \b not use the \c .qrc +scheme. This scheme should only be used from C++ code to refer to resource files. -Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}. -The directory structure looks like this: +Here's an application packaged using the Qt resource system; its directory structure is as follows: \code project @@ -273,26 +246,33 @@ project |- project.pro \endcode -The \c main.qml and \c background.png files will be packaged as resource files. This is -done in the \c example.qrc resource collection file: +The \c main.qml and \c background.png files are packaged as resource files. This is done in the +\c example.qrc resource collection file: \quotefile qmlapp/qtbinding/resources/example.qrc -Since \c background.png is a resource file, \c main.qml can refer to it using the relative -path specified in \c example.qrc: +Since \c background.png is a resource file, \c main.qml can refer to it using the relative path +specified in \c example.qrc: \snippet qmlapp/qtbinding/resources/main.qml 0 -To allow QML to locate resource files correctly, the \c main.cpp loads the main QML -file, \c main.qml, as a resource file using the \c qrc scheme: +To allow QML to locate resource files correctly, the \c main.cpp loads the main QML file, +\c main.qml, as a resource file using the \c .qrc scheme: \snippet qmlapp/qtbinding/resources/main.cpp 0 -Finally, \c project.pro uses the RESOURCES variable to indicate that \c example.qrc should +Finally, \c project.pro uses the \c RESOURCES variable to indicate that \c example.qrc should be used to build the application resources: \quotefile qmlapp/qtbinding/resources/resources.pro -See \l {The Qt Resource System} for more information. +\section1 Related Information +\list + \li \l{Deploying Qt Applications} + \li \l{Qt Creator: Running on Multiple Platforms}{Running on Multiple Platforms} + \li \l{Qt Creator: Deploying to Devices}{Deploying to Devices} + \li \l{qtqml-cppintegration-data.html}{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Types to QML} + \li \l{The Qt Resource System} +\endlist */