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
|
/****************************************************************************
**
** 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 Writing Applications
Writing an application that can be run as a client within the application-manager is not that
much different from writing a stand-alone QML application. It basically boils down to three
additional tasks:
\list 1
\li If you write a QML application, make the root element of your QML scene 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 expect similar behavior in single- and
multi-process mode. If a QtObject is used, 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-porcess mode \l Window root elements will get a decoration (unless
QT_WAYLAND_DISABLE_WINDOWDECORATION is set) and will be invisible by default. QQuick
\l{Item}{Items} will be wrapped inside a \l Window representing a Wayland client window.
\li In single-process mode \l Window root elements will appear parallel to instead of inside
the System-UI.
\endlist
\section2 The Manifest and Updating the Database
The \l{Manifest Definition} documentation has all the information to produce a minimal \c info.yaml
file that should get you going.
Recursively finding and parsing \c info.yaml files for potentially hundreds of applications can
be a very time consuming task and would severely slow down application-manager's
startup. Therefore, all manifest files are cached in a binary database. In order to make changes
to an \c info.yaml file known to the application-manager, you have to force a rebuild of this
database by calling \c{appman --recreate-database}.
\note Dynamically adding/updating/removing single 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 first needs to be packaged. 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 by the application-manager.
The integration will add an additional \c{package} target to the Makefile. By calling \c{make package}
on the command line or adding it as an additional build step in QtCreator a new application package
gets created.
\section3 Simple QML Apps
For simple QML only apps, just 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 will just be
used as a temporary path during package creation.
\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 actual qmake integration.
\code
AM_PACKAGE_DIR = $$app.path
load(am-app)
\endcode
\section3 Complex Apps
For more complex apps, where you need to deploy a C++ based QML plugin in addition to your QML
content, you need to split your app into multiple folders and project files. One folder for the QML
part, another one for the C++ plugin and a SUBDIRS project to glue them together.
The packaging integration will be done in the SUBDIRS project and expects that the other project
files provide install targets to a shared install location. E.g the QML part installs it's files to
'/apps/com.example.application', while the C++ plugin will install to
'/apps/com.example.application/imports/com/example/application'.
In the SUBDIRS project you need to define the AM_MANIFEST variable and set it to the location of
your info.yaml file as well as define the shared install location as AM_PACKAGE_DIR:
\code
AM_MANIFEST = $$PWD/app/info.yaml
AM_PACKAGE_DIR = /apps/com.example.application
load(am-app)
\endcode
\section3 Packaging multiple apps
If your repository provides multiple apps, like the
\l{http://code.qt.io/cgit/qt-apps/qt-auto-extra-apps.git/}{Qt Auto Extra Apps Repository}, you can
use the am-package qmake feature to provide a repository wide \c{package} step.
Just add a ".qmake.conf" file with the following content to your repository, which gets
automatically loaded by qmake:
\code
CONFIG += am-package
\endcode
*/
|
