mirror of https://github.com/qt/qtdoc.git
Doc: Cleanup of the Deploying QML Applications topic
Change-Id: Ie2fb81c48cab828c2d0706761478b7388ef6f630 Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
This commit is contained in:
Kavindra Palaraja
parent
c52d9c0696
commit
967e916d21
|
|
@ -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{<version>}\c{/}\e{<compiler>}\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{<version>}\c{/}\e{<compiler>}\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 <QGuiApplication>
|
||||
|
|
@ -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
|
||||
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue