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
|
/****************************************************************************
**
** 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 debugging.html
\title Logging and Debugging
\section1 Logging
The application-manager installs its own message handler that neatly formats logging output.
It will also pass the output to GENIVI DLT (Diagnostic Log and Trace), if the QtGeniviExtras module
is available.
\section2 Categories
The following logging categories are defined by the application manager:
\include logging.cpp am-logging-categories
\section2 Environment Variables
This is a (incomplete) list of environment variables that influence the logging output at runtime:
\table
\header
\li Variable
\li Description
\row
\li AM_STARTUP_TIMER
\li If set to 1, a startup performance analysis will be printed on the console. Anything other
than 1 will be interpreted as the name of a file that is used instead of the console. For
more in-depth information see StartupTimer.
\row
\li AM_FORCE_COLOR_OUTPUT
\li Can be set to \c on to force color output to the console and to \c off to disable it. Any
other value will result in the default, auto-detection behavior.
\row
\li AM_TIMEOUT_FACTOR
\li All timed wait statements within the application-manager will be slowed down by this
(integer) factor. Useful if executing in slow wrappers, like e.g. valgrind. Defaults to \c 1.
\row
\li QT_MESSAGE_PATTERN
\li Setting this variable has the same effect as described on the
\l{Warning and Debugging Messages}{Debugging Techniques} page and will overwrite the
default application-manager message handler. Parallel DLT logging will still be supported,
if available.
\endtable
\section1 Debugging
\section2 Introduction
Debugging the application-manager, the System-UI and applications is dependent on the mode the
application-manager is running in:
\list
\li In \b single-process mode, you can just start the \c appman binary using your debugging tool of
choice directly (e.g. \c{gdb --args appman -c config.yaml}). Since everything is running in a
single process, you cannot debug applications independently though.
\li In \b multi-process mode, you have to distinguish between debugging the application-manager itself
or the System-UI and debugging individual applications: The application-manager and System-UI
can be debugged in the same way as described for a single-process setup above. Debugging
applications is a bit more tricky though, since they have to be started by the application-manager:
this is accomplished by running the app through a debug wrapper which describe how to start an
application using your favorite debugging tool.
\endlist
To enable QML Debugging/Profiling in the application-manager or an application it needs to be started
with the \c --qml-debug argument. See \l{QML Debugging Infrastructure} for more information.
Please note that although the concept is called "debug" wrappers, these wrappers are not limited to
actual debugging tasks. They are also useful for various other tasks that involve running the
program under test through a wrapper, e.g. profiling tools.
\target DebugWrappers
\section2 Using Debug Wrappers
There are three ways to do start applications using debug wrappers - all of them rely on a common
way to specify which debug wrapper to use:
\list
\li Within your System-UI, do not use \c startApplication to start an app, but debugApplication:
\badcode
ApplicationManager.debugApplication("io.qt.app", "/usr/bin/strace -f")
\endcode
\li Via D-Bus, you can call the debugApplication method:
\badcode
qdbus io.qt.ApplicationManager /ApplicationManager debugApplication "gdbserver :5555" io.qt.app
\endcode
\li Using the \c appman-controller which uses D-Bus internally, but is able to find the correct
bus automatically and supports standard-IO redirection:
\badcode
appman-controller debug-application -ioe "valgrind --tool=helgrind" io.qt.app
\endcode
The optional \c -i, \c -o and \c -e parameters will redirect the respective IO streams (\c stdin,
\c stdout and \c stderr) to the calling terminal.
\endlist
\note In order to use the D-Bus options, the application-manager has to be connected to either
a session- or system-bus - make sure to not run it with \c{--dbus none}.
The debug wrapper specification has to be a single argument string, that is interpreted as a command
line. If this string contains the sub-string \c{%program%}, it will be replaced with the full path
to the executable of the application (or the \c appman-launcher-qml binary for QML applications).
The same thing happens for \c{%arguments%}, which will be replaced with potential command line
arguments for the application. If you don't specify \c{%program%} or \c{%arguments%}, they will
simply be appended to the resulting command line.
This means that all of these debug wrappers are essentially the same:
\badcode
appman-controller debug-application "gdbserver :5555 %program% %arguments%" io.qt.music
appman-controller debug-application "gdbserver :5555 %program%" io.qt.music
appman-controller debug-application "gdbserver :5555" io.qt.music
\endcode
The explicit \c{%program%} argument is important, if the "wrapper" works differently. An example
for this would be to start the application with the JavaScript debugger on port 1234 in blocking
mode:
\badcode
appman-controller debug-application "%program% -qmljsdebugger=port:1234,block %arguments%" io.qt.browser
\endcode
You also have the possibility to specify environment variables for the debug wrapper - just like on
the command line. This command will run your application through \c strace while also setting the
\c WAYLAND_DEBUG environment variable to \c 1.
\badcode
appman-controller debug-application "WAYLAND_DEBUG=1 strace -f" io.qt.browser
\endcode
For added convenience, you can even just only set environment variables without any actual debug
wrapper, e.g. to debug imports and plugin loading in a QML application:
\badcode
appman-controller debug-application "QT_DEBUG_PLUGINS=1 QML_IMPORT_TRACE=1" io.qt.browser
\endcode
It is advisable to create aliases or wrapper scripts when using complex debug wrappers on the
command line often.
*/
|
