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
|
/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** 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 Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt 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
\ingroup qtappman
\ingroup qtappman-highlights
\title Logging and Debugging
\brief The application manager installs its own message handler to format logging output neatly.
\section1 Logging
The application manager installs its own message handler to format logging output neatly. If the
\l {Qt DLT Logging} {QtDltLogging} module is available, this message handler passes the output
to GENIVI Diagnostic Log and Trace (DLT).
\section2 Categories
The application manager defines the following logging categories:
\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_NO_CUSTOM_LOGGING
\li If set to \c 1, debug output is not redirected to DLT, colorized or nicely formatted.
\row
\li AM_NO_DLT_LOGGING
\li If set to \c 1, debug output is not redirected to DLT.
\row
\li AM_STARTUP_TIMER
\li If set to \c 1, a startup performance analysis is printed to the console. Anything other
than \c 1 is interpreted as the name of a file to use, instead of the console. For more
information, see StartupTimer.
\row
\li AM_FORCE_COLOR_OUTPUT
\li Can be set to \c on to force color output to the console or to \c off to disable it. Any
other value enables the default, auto-detection behavior.
\row
\li AM_TIMEOUT_FACTOR
\li An integer factor that slows down all timed wait statements within the application manager.
Useful if running in slow wrappers, such as Valgrind. The default value is \c 1.
\row
\li QT_MESSAGE_PATTERN
\li Setting this variable has the same effect as described in
\l{Warning and Debugging Messages}{Debugging Techniques} and overwrites the default
application manager message handler. Parallel DLT logging is still supported, if available.
\endtable
\section1 Debugging
\section2 Introduction
When debugging the application manager, the System UI and applications are dependent on the mode in
which the application manager runs:
\list
\li In \b single-process mode, you can start the \c appman binary using any debugging tool
directly, for example, \c{gdb --args appman -c config.yaml}. Since everything runs in a single
process, you can't debug applications separately. Instead, all applications started are loaded
into \b{a single process}, so you can only debug the entire process at once; not each
application independently.
\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 for a single-process setup above. Debugging
is a bit more tricky for applications, as they have to be started by the application manager.
You can accomplish this by running the application through a debug wrapper which describes
how to start an application using your favorite debugging tool.
\endlist
To enable QML Debugging or QML Profiling in the application manager or an application, start it
with the \c --qml-debug argument. For more information, see \l{QML Debugging Infrastructure}.
\note Although the concept is called "debug" wrappers, these wrappers are not limited to debugging
tasks only. They are also useful for various other tasks that involve running the application under
test through a wrapper, like profiling tools.
\section2 Environment Variables
This is a (incomplete) list of environment variables that influence debugging at runtime:
\table
\header
\li Variable
\li Description
\row
\li AM_NO_CRASH_HANDLER
\li If set to \c 1, no crash handler is installed. Use this, if the application manager's
crash handler is interfering with other debugging tools you are using.
\endtable
\target DebugWrappers
\section2 Use Debug Wrappers
There are three ways to 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, use \c debugApplication to start an application, instead of
\c startApplication:
\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 redirect the respective IO streams (\c stdin,
\c stdout, and \c stderr) to the calling terminal.
\endlist
\note To use the D-Bus options, the application manager has to be connected to either a session- or
system-bus; don't 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 \c{%program%} sub-string, it is replaced with the full
path to the application's executable (or the \c appman-launcher-qml binary for QML applications).
The same thing happens for \c{%arguments%}, which is replaced with potential command line arguments
for the application. If you don't specify \c{%program%} or \c{%arguments%}, they are 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 can also specify environment variables for the debug wrapper - just like on the command line.
This command runs 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 set environment variables only, without any actual debug
wrapper, 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
When using complex debug wrappers on the command line often, it's advisable to create aliases or
wrapper scripts.
*/
|
