| /**************************************************************************** |
| ** |
| ** Copyright (C) 2017 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page qtquick-deployment.html |
| \title 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. |
| |
| 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. |
| |
| 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. 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. |
| |
| \target Compiling Ahead of Time |
| \section1 Ahead-of-Time Compilation |
| |
| 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. |
| |
| 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 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 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. |
| |
| \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 QML runtime. |
| |
| \section1 Initializing the QML Runtime in Applications |
| |
| 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. |
| \li Creating a QQmlEngine instance and loading QML files with QQmlComponent. |
| \endlist |
| |
| |
| \section2 Initializing with QQuickView |
| |
| 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 |
| |
| Rectangle { width: 100; height: 100; color: "red" } |
| \endqml |
| |
| It can be loaded in a Qt application's \c main.cpp file like this: |
| |
| \code |
| #include <QGuiApplication> |
| #include <QQuickView> |
| |
| int main(int argc, char *argv[]) |
| { |
| QGuiApplication app(argc, argv); |
| |
| QQuickView view; |
| view.setSource(QUrl::fromLocalFile("application.qml")); |
| view.show(); |
| |
| return app.exec(); |
| } |
| \endcode |
| |
| 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: |
| |
| \code |
| TEMPLATE += app |
| QT += quick |
| SOURCES += main.cpp |
| \endcode |
| |
| |
| \section2 Creating a QQmlEngine Directly |
| |
| 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> |
| #include <QQmlEngine> |
| #include <QQmlContext> |
| #include <QQmlComponent> |
| |
| int main(int argc, char *argv[]) |
| { |
| QGuiApplication app(argc, argv); |
| |
| QQmlEngine engine; |
| QQmlContext *objectContext = new QQmlContext(engine.rootContext()); |
| |
| QQmlComponent component(&engine, "application.qml"); |
| QObject *object = component.create(objectContext); |
| |
| // ... delete object and objectContext when necessary |
| |
| return app.exec(); |
| } |
| \endcode |
| |
| 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 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. |
| \li From C++, load the main QML file as a resource using the \c :/ prefix or as a URL with the |
| \c .qrc scheme. |
| \endlist |
| |
| 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's an application packaged using the Qt resource system; its directory structure is as follows: |
| |
| \code |
| project |
| |- example.qrc |
| |- main.qml |
| |- images |
| |- background.png |
| |- main.cpp |
| |- project.pro |
| \endcode |
| |
| 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: |
| |
| \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: |
| |
| \snippet qmlapp/qtbinding/resources/main.cpp 0 |
| |
| 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 |
| |
| \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 |
| |
| */ |