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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
// Copyright (C) 2021 The Qt Company Ltd.
// Copyright (C) 2019 Luxoft Sweden AB
// Copyright (C) 2018 Pelagicore AG
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page installation.html
\title Installation
\brief Discusses Qt Application Manager installation considerations, such as; support, prerequisites, code coverage data and system setup.
\ingroup qtappman
\ingroup qtappman-highlights
\section1 Supported Platforms
The application manager is tested regularly on multiple platforms.
The following platforms are only supported for \b{development and testing} purposes. In addition these
platforms only allow the application manager to work in
\l{Single-Process vs. Multi-Process Mode}{single-process mode}:
\list
\li Windows
\li macOS
\li Android (the application manager cannot be deployed directly, but only as part of an Android
APK package containing the System UI)
\endlist
These platforms can be used for \b{development and production} and will allow you to use the full
feature set of the application manager:
\list
\li Linux desktop and embedded in \l{Single-Process vs. Multi-Process Mode}
{single-process and multi-process mode}
\note In multi-process mode, only the \b Intel, \b AMD (open source), and \b VMWare graphics
drivers are supported due to the varying stability levels in Wayland drivers. While other
drivers may work, they require either special QtWayland versions or specific firmware
blobs for the GPU driver.
\endlist
\section1 Prerequisites
To build the application manager with all its features, the following components are required:
\list
\li \b Qt 6.5.0 or higher.
\li \b libyaml 2.2 or higher.
\li \b libarchive 3.5 or higher \e{- if you need the installer functionality}.
\endlist
On Debian-based systems, this command installs the three required packages:
\badcode
apt-get install libyaml-dev libarchive-dev libssl-dev
\endcode
\note On platforms without \c pkg-config (for example, Windows or macOS) as well as on platforms
that lack one of the prerequisites, the bundled versions of these libraries from the \c src/3rdparty
folder are automatically used instead. Make sure you are aware of the licensing implications,
since these bundled 3rdparty libs will be linked in as static libraries.
This option is not meant for production, but for development and testing environments only.
\section1 Runtime Requirements
Some libraries used by the application manager are not directly linked in, but instead loaded
dynamically at runtime:
\list
\li \b openssl \e{- Linux only and only if you need the installer functionality}.
Qt needs to be built with openssl support. The required minimum version is defined by Qt.
\li \b libdbus 1.12 or higher \e{- if you need multi-process mode or appman-controller support}.
As libdbus is not readily available for Windows and macOS, the application manager provides
its own copy to support the \c appman-controller tool (which is also used by the Qt-Creator
integration).
\endlist
\section1 Multi-process vs. Single-process
By default, the application manager always tries to build in multi-process mode, but falls back
to single-process mode, if certain multi-process mode dependencies are not available, such as:
\list
\li You are building for \b Linux.
\li The \c QtWayland module is available.
\li The \c QtDBus module is available.
\endlist
You can force the build mode via the respective \c --force-multi-process and
\c --force-single-process command line options, as described below.
\target build
\section1 Build
The application manager uses \c CMake for its build system. The basic installation steps are:
\code
mkdir <builddir>
&& cd <builddir>
&& cmake <srcdir> <options>
&& cmake --build .
&& cmake --install .
\endcode
or
\code
mkdir <builddir>
&& cd <builddir>
&& <qtbase>/bin/qt-configure-module <srcdir> <options>
&& cmake --build .
&& cmake --install .
\endcode
All executables, including the unit tests, can be found in the build folder's \c bin directory, after
compiling.
There are various options that can be given to \c CMake to tailor the build to suit your needs.
With Qt's new CMake based build system, there are three ways to set configure options for Qt
modules:
\list 1
\li You can call \c cmake from a shell and specify the options as \c -DINPUT_<option>=<value>
directly on the CMake command line
\li You can also use the \c cmake-gui or Qt Creator's built-in configuration UI to change options
after the first CMake run
\li Again on the command line, there is Qt's convenience CMake wrapper \c qt-configure-module,
which lets you specify the options as normal command line options: \c --<option>=<value>
\endlist
\table
\header
\li Option
\li Description
\row
\li \c{libarchive}
\li Set to \c system to force a build against the system libarchive, or \c qt to not build against
the system libarchive, even if one was detected.
\row
\li \c{libyaml}
\li Set to \c system to force a build against the system libyaml, or \c qt to not build against the
system libyaml, even if one was detected.
\row
\li \c{force-single-process}
\li Force a single-process build, even if Qt's Wayland \c compositor module is available.
\br The corresponding cmake input is \c{-DINPUT_force_mode=single}.
\row
\li \c{force-multi-process}
\li Force a multi-process build - this will break if Qt's Wayland \c compositor module is not
available.
\br The corresponding cmake input is \c{-DINPUT_force_mode=multi}.
\row
\li \c{installer}
\target config disable installer
\li Set to \c no to disable the installer part.
\row
\li \c{external-dbus-interfaces}
\li Set to \c no to completely disable the external D-Bus interfaces. The internal communication
channel between the applications and the application manager will still be based on a
peer-to-peer D-Bus.
\row
\li \c{tools-only}
\li Set to \c yes to create a build that only compiles the tools (as in \e{Qt build tools}, that
are only built for the host Qt when cross compiling): \l{Packager}{appman-packager}.
\row
\li \c{package-server}
\li Set to \c no to disable building the \l{Package-Server}{appman-package-server} tool, and \c
yes to force building it. The default depends on the availability of the \c QtHttpServer
module.
\row
\li \c{widgets-support}
\li Set to \c yes to enable support for Qt widgets. This option can be useful to enable the use
of some development tools using Qt widgets.
\row
\li \c{hardware-id=<id>}
\li If set, compiles in \c id as a hard-coded hardware-id; see \l{The Hardware ID} for more
information.
\row
\li \c{libbacktrace}
\li If set to \c yes, enables building and linking against \c libbacktrace in the 3rdparty folder.
This gives you readable backtraces for crashes on Linux, but also increases the binary size
slightly. For debug builds, this option is enabled by default.
Setting this to \c no disables building and linking against \c libbacktrace.
\row
\li \c{stackwalker}
\li If set to \c yes, enables building and linking against \c stackwalker in the 3rdparty folder.
This gives you readable backtraces for crashes on Windows, but also increases the binary size
slightly. For debug builds, this option is enabled by default.
Settings this to \c no disables building and linking against \c stackwalker.
\row
\li \c{libdbus}
\li Windows and macOS only: If set to \c no, enables building \c libdbus-1 from the 3rdparty
folder.
This will allow you to use the \c appman-controller tool (which is also used by the Qt-Creator
integration) on Windows and macOS. This option is enabled by default.
Settings this to \c no disables building \c libdbus-1.
\endtable
\section2 The Hardware ID
The installer part of the application manager needs a unique device ID, if you want to deliver
application packages that are bound to a specific device unit from your app-store. The use case here
is to prevent customers from buying apps once and then sharing them with others for free.
Since the application manager doesn't know, at build time, how a potential app-store will be
configured, the application manager tries to create a unique ID based on the MAC address of the
first configured ethernet device. If the ethernet device is not configured at all, or configured
after the application manager starts, this scenario will not work.
There are three different ways to specify a hardware ID:
\list 1
\li No configure option: use the MAC address of the first ethernet device. Typically, this option
works out of the box.
\li \c{hardware-id=yourID} hardcodes the ID to \c yourID. This option is ideal, if
you do not use any application manager features that require this ID to be unique and if you
cannot (or do not want to) guarantee that an ethernet device is up when the application manager
starts.
\li \c{hardware-id=@yourFile} makes the application manager read the
contents of \c yourFile at startup and uses its content as the ID; instead of the ethernet MAC
address. This option is useful if your device has a unique device ID available via \c /proc or
\c /sys and you want to use features that require such an ID.
\endlist
\section1 Generate Code-Coverage Data
Instead of doing a normal build, you can also create a coverage build by running
\c{cmake -DAM_COVERAGE=ON}. Since every compile step needs to be instrumented with special compiler
flags, make sure to create a new build directory, or at least clean an existing one.
Using a build like this enables you to generate HTML coverage reports with the following command
in the build directory:
\badcode
cmake --build . --target check_coverage
\endcode
The command line output provides you the URL to the generated report.
\section1 System Setup
The runtime configuration of the application manager is done through command line switches and
one or more configuration files.
Ideally, in a production setup, the basic configuration is done via two separate config files:
one for target system specific setup and one for System UI specific settings. The target system
specific one would for example have the path to installation directories and the required
logging settings; the System UI specific one would for example have the QML import path and
the paths to built-in apps.
If you have the target settings in \c /etc/target-am-config.yaml and the System UI with its
\c am-config.yaml and \c main.qml files at \c /path/to/system-ui, you can then the
application manager like so:
\badcode
cd /path/to/system-ui
appman -c /etc/target-am-config.yaml -c am-config.yaml --verbose main.qml
\endcode
\c{--verbose} gives you verbose output, which is quite helpful when first setting up the environment
and also for debugging purposes.
*/
|
