1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
/****************************************************************************
**
** Copyright (C) 2019 Luxoft Sweden AB
** Copyright (C) 2018 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Luxoft 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 howto-apps.html
\title Write Applications
Writing an application to run as a client within the application manager is similar to writing a
stand-alone QML application, except for these three additional tasks:
\list 1
\li If you write a QML application, make your QML scene's root element an
ApplicationManagerWindow; or derive your own custom root item from it.
\li Provide a valid \l{Manifest definition}{info.yaml} file.
\li Make the application manager aware of your application by running
\c{appman --recreate-database}.
\endlist
\section2 The Root Element
It is recommended to use either an ApplicationManagerWindow or a QtObject as the root of your QML
application. This is especially important if you require similar behavior in single-process and
multi-process mode. If you use a QtObject, any visible base elements should still be
\l{ApplicationManagerWindow}{ApplicationManagerWindows}. Nevertheless, other root elements are
supported for convenience, as well.
Here are a few things to consider:
\list
\li Only \l{ApplicationManagerWindow}{ApplicationManagerWindows} support window properties
that are shared between the System UI and the client applications.
\li In multi-process mode, \l Window root elements always get a decoration (unless you set
QT_WAYLAND_DISABLE_WINDOWDECORATION) and are invisible by default. QQuick
\l{Item}{Items} are wrapped inside a \l Window representing a Wayland client window.
\li In single-process mode \l Window root elements appear parallel to instead of inside the
System UI.
\endlist
\section2 The Manifest and Updating the Database
The \l{Manifest Definition} has all the information you need to produce a minimal \c info.yaml
file.
Finding and and parsing \c info.yaml files recursively, for potentially hundreds of applications
can be a very time consuming task and would severely slow down the application manager's startup.
Therefore, all manifest files are cached in a binary database. To notify the application manager
about changes to an \c info.yaml file, you have to force a rebuild of this database by calling
\c{appman --recreate-database}.
\note Dynamically adding, updating, or removing individual applications is supported via the
ApplicationInstaller interface.
\section2 qmake Integration
To install applications into a System UI using the \l{Installer}{Installer Sub-System}, the
application needs to be packaged first. This can be done using the \l{Packager} utility. To better
integrate the packaging into your usual developer workflow you can also use the qmake integration
provided.
The integration adds an additional \c{package} target to the Makefile. You can create a new
application in one of two ways:
\list
\li call \c{make package} on the command line
\li add \c{make package} as an additional build step in QtCreator
\endlist
\section3 Simple QML Applications
For simple QML-only applications, create a qmake project file which defines an install step for all
the needed files. The actual install location doesn't matter in this case, because it is used as a
temporary path when the package is being created.
\code
TEMPLATE = aux
FILES += info.yaml \
icon.png \
Main.qml
app.files = $$FILES
app.path = /apps/com.example.application
INSTALLS += app
\endcode
In addition add the following two lines to provide the install location to the packaging step and
to load the qmake integration.
\code
AM_PACKAGE_DIR = $$app.path
load(am-app)
\endcode
\section3 Complex Applications
For complex applications, where you need to deploy a C++ based QML plugin in addition to your QML
content, you must split your app into multiple folders and project files. One folder for the QML
part, another one for the C++ plugin, and a \c SUBDIRS project to glue them together.
The packaging integration is done in the \c SUBDIRS project and this process expects that the other
project files provide install targets to a shared install location. In this case, the QML part
installs its files in \c{/apps/com.example.application}, while the C++ plugin installs in
\c{/apps/com.example.application/imports/com/example/application}.
In the \c SUBDIRS project you need to define the \c AM_MANIFEST variable and set it to the location
of your \c info.yaml file. Then, define the shared install location as \c AM_PACKAGE_DIR:
\code
AM_MANIFEST = $$PWD/app/info.yaml
AM_PACKAGE_DIR = /apps/com.example.application
load(am-app)
\endcode
\section3 Package Multiple Applications
If your repository provides multiple applications, like the
\l{http://code.qt.io/cgit/qt-apps/qt-auto-extra-apps.git/}{Qt Auto Extra Apps Repository}, you can
use qmake's am-package feature to provide a repository-wide \c{package} step.
Add a \c{.qmake.conf} file with the following content to your repository, which is loaded
automatically by qmake:
\code
CONFIG += am-package
\endcode
*/
|
