deployment.qdoc

Go to the documentation of this file.

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\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 \c qml 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 \QC
 
\l{\QC Documentation}{\QC} deploys and packages QML applications to various
platforms. For mobile devices, \QC 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.
 
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.
 
This will happen automatically if you use the
\l{qt_add_qml_module}{CMake QML Module API}, for qmake see the section below.
 
\section2 qmake
 
When using qmake, in order 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.
\endlist
 
\section1 Prototyping with QML Scene
 
The Declarative UI package includes a QML Runtime Tool,
\l{qml_runtime_tool}{qml}, 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
 
    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}.
 
\section3 Build files
 
\if defined(onlinedocs)
  \tab {build-qt-app}{tab-cmake}{CMake}{checked}
  \tab {build-qt-app}{tab-qmake}{qmake}{}
  \tabcontent {tab-cmake}
\else
  \section1 Using CMake
\endif
  \include {module-use.qdocinc} {building with cmake} {Quick}
\if defined(onlinedocs)
  \endtabcontent
  \tabcontent {tab-qmake}
\else
  \section1 Using qmake
\endif
  \include {module-use.qdocinc} {building_with_qmake} {quick}
  For more information, see \l{Creating Project Files}.
\if defined(onlinedocs)
  \endtabcontent
\endif
 
\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 Using the Qt Resource System with QML
 
The \l {The Qt Resource System}{Qt resource system} allows resource files to be
stored as binary files in an application executable. The Qt Resource System is
used for QML 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 Usage of the resource system means that the application executable
usually must be re-compiled whenever a QML source file is changed, to update
the resources in the package.
 
The \l{qt_add_qml_module}{CMake QML Module API} automatically places your QML
files in the resource system. To access them, load your main QML file as a
resource or as a URL with the \c{qrc} scheme. The path in the resource system
where your QML files are placed can be found by concatenating:
 
\list
\li the \c RESOURCE_PREFIX you have passed to \l{qt_add_qml_module}.
\li \c{/qt/qml}, if you have \e{not} passed \c RESOURCE_PREFIX to
    \l{qt_add_qml_module} and \l{QTP0001} policy is set to \c NEW.
\li \c{/}, if you have \e{not} passed \c RESOURCE_PREFIX to \l{qt_add_qml_module}
    and \l{QTP0001} policy is \c{not} set to \c NEW.
\li If you have \e{not} passed \c NO_RESOURCE_TARGET_PATH to \l{qt_add_qml_module}:
    the \c URI you have passed to \l{qt_add_qml_module} with dots replaced by slashes.
\endlist
 
For example, a module called \c{My.Own.Module} is placed at:
\list
\li \c{:/qt/qml/My/Own/Module/} if you have specified \c{/qt/qml} as \c RESOURCE_PREFIX, or
    you have \e{not} passed \c RESOURCE_PREFIX and \l{QTP0001} policy is set to \c NEW.
\li \c{:/My/Own/Module/} if you have specified \c{/} as \c RESOURCE_PREFIX, or
    you have \e{not} passed \c RESOURCE_PREFIX and \l{QTP0001} policy is \e{not} set to \c NEW.
}
\li \c{:/Some/Prefix/My/Own/Module/} if you have specified \c{Some/Prefix/} as \c RESOURCE_PREFIX
\li \c{:/} if you have specified \c NO_RESOURCE_TARGET_PATH
\endlist
 
Once this is done, all files specified by relative paths in QML are loaded from
the resource system. 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 to refer to resource files.
 
\note When using qmake, you need to manually place your files in the resource
system. See the \l{qmake Manual} and the \l{The Qt Resource System}{general
documentation} on the resouce system for how to do this. It's advisable to
still follow the path naming convention outlined above.
 
\section1 Related Information
\list
    \li \l{Deploying Qt Applications}
    \li \l{\QC: Run on many platforms}
    \li \l{Data Type Conversion Between QML and C++}{Exposing Attributes of C++ Types to QML}
    \li \l{The Qt Resource System}
\endlist
 
*/