From a8e9fa8d30c3298ac90e1c539d8f62bcc99c7107 Mon Sep 17 00:00:00 2001 From: Bernd Weimer Date: Thu, 19 Sep 2019 14:06:24 +0200 Subject: Explain how Qt Resources is used with Qt Application Manager Fixes: AUTOSUITE-1259 Change-Id: Ie6100a8ce87c4d9c5bb86e10dbd9cb26a6c5b3b7 Reviewed-by: Grigorii Zimin --- doc/index.qdoc | 1 + doc/resources.qdoc | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 141 insertions(+) create mode 100644 doc/resources.qdoc diff --git a/doc/index.qdoc b/doc/index.qdoc index 47e33165..d66b10ee 100644 --- a/doc/index.qdoc +++ b/doc/index.qdoc @@ -52,6 +52,7 @@ For a high-level overview, see \l{The Qt Application Manager}{Introduction to th \li \l{Application Installer} \li \l{Logging and Debugging} \li \l{Containers} + \li \l{Use Qt Resources} \li \l{Single-Process vs. Multi-Process Mode} \li \l{Migrating code from 5.11 to 5.12} \endlist diff --git a/doc/resources.qdoc b/doc/resources.qdoc new file mode 100644 index 00000000..7735914d --- /dev/null +++ b/doc/resources.qdoc @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** Copyright (C) 2019 Luxoft Sweden AB +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Application Manager. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite 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 use-qt-resources.html +\title Use Qt Resources + +\l{The Qt Resource System} lets you store files in your program's executable. In some ways, +this feature resembles a dedicated file system, which we call \e{resource file system}. Usually, +this file system contains QML code and other assets like images. If you use the QML compiler, the +compiled code is always placed in the resource file system. There are a few application manager +specific considerations, especially when your application needs to support both single-process and +multi-process modes. + +\section1 Compile Resources + +You can add resources as \l{External Binary Resources}{external binary resources} or as +\l{Compiled-In Resources}{compiled-in resources}; both are generated from a \c .qrc file. +Typically, external binary resources are stored in a file with the \c .rcc extension, whereas +compiled-in resources are stored in libraries in the Application Manager context. + +It's important to understand that each process has its own resource file system. Consequently, to +support multi-process mode, resources must be generated separately for the System UI and for each +application. Conversely, in single-process mode there is only one resource file system and you must +ensure that file paths don't clash. To prevent clashes, we recommend to prefix each application +file path with the unique application ID. + +Consider the following application file structure: + +\badcode +apps +|---- app1 +| |---- main.qml +| |---- app1.qrc +| ... +|---- app2 +| |---- main.qml +| |---- app2.qrc +| ... +\endcode + +Without a prefix, in single-process mode, the \c main.qml files would clash. To avoid this, the +\c .qrc file for app1 should read like this: + +\badcode + + + main.qml + + +\endcode + +For \c app2 the prefix should be "app2", respectively. Generally, all files contained in any +\c .qrc file should be unique; this also includes files that the System UI uses. + + +\section1 Load Resources + +In addition to the approaches described in \l{The Qt Resource System}, the Application Manager +provides configuration options to load resources, both -- external binary resources and +compiled-in resources in the form of a library. + +Suppose you have a \c my.rcc binary file and a \c myplugin.so library file. These can be loaded +into the System UI by adding the following lines to the \c am-config.yaml file: + +\badcode +ui: + resources: [ "${CONFIG_PWD}/my.rcc", + "${CONFIG_PWD}/myplugin.so" ] +\endcode + +You can also load these two files into an application by adding the following snippet to the +\c info.yaml file: + +\badcode +runtimeParameters: + resources: [ "my.rcc", + "myplugin.so" ] +\endcode + +The resources are loaded when the System UI starts, before the QML engine is instantiated. In +multi-process mode the application resources are also loaded into the application process at +startup. In single-process mode, resources are loaded when the application first starts and then +reused on subsequent invocations; they are never unloaded. + +\section1 Access Resources + +The application manager allows for file access in the resource file system, either with the URL +scheme (\c{qrc}) or the file name prefix (\c{:}). Both these options require an absolute file path +in the resource file system, such as: + +\list + \li \c{qrc:/app1/main.qml} or \c{qrc:///app1/main.qml} + \li \c{:/app1/main.qml} +\endlist + +While the Qt Application Manager accepts this relaxed naming structure, the QML engine +distinguishes between URLs and file names. For instance, an \l{Image::source} +{Image source} property only accepts the \c{qrc} scheme. + +If you want to specify a relative path, don't use the scheme or file path prefix. + +If your files aren't found in the resource file system, you can list the contents of the entire +resource file system with the following code snippet: + +\code +QDirIterator it(qSL(":"), QDirIterator::Subdirectories); +while (it.hasNext()) { + const QString fn = it.next(); + if (!fn.startsWith(qSL(":/qt-project.org"))) // exclude Qt internal files + qDebug() << fn; +} +\endcode + +*/ -- cgit v1.2.3