/**************************************************************************** ** ** 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. */