Warning, /plasma/drkonqi/src/doc/debug_package_installer.txt is written in an unsupported language. File is not indexed.

0001 This version of DrKonqi supports automatic installation of debug symbols packages
0002 when it finds that debug symbols are missing. This document is to explain what is
0003 needed from packagers to do in order to enable this functionality for their distribution.
0004 
0005 If your distribution does not ship packages with debug symbols you can safely ignore
0006 the rest of this document. In this case, DrKonqi will not offer the ability to install
0007 debug symbol packages.
0008 
0009 If your distribution does ship packages with debug symbols, then in order for DrKonqi
0010 to offer the ability to install them automatically, you need to provide a script that
0011 will do the work. This is because the packaging systems vary a lot among different
0012 distributions and DrKonqi cannot implement distro-specific functionality in its main
0013 code for all distributions.
0014 
0015 Please note that I chose to use the word "script" here having in mind a shell script,
0016 but you may as well provide a python script, a perl script, or whatever else, even a
0017 compiled binary written in any language you want. DrKonqi will use KProcess for
0018 launching it, so as long as it is executable, it will work.
0019 
0020 
0021 Name of the script
0022 ==================
0023 By default DrKonqi looks for a shell script called "installdbgsymbols.sh". It expects
0024 it to be in PATH, or somewhere that it is possible to be located by KStandardDirs::findExe().
0025 For example, the path where DrKonqi itself is installed (`kde4-config --path libexec`),
0026 is a valid path to install this script, although it is not in PATH.
0027 
0028 If you wish to provide a script with a different name, you can change the name by setting
0029 the cmake variable DEBUG_PACKAGE_INSTALLER_NAME to the name that you want. For example,
0030 configuring kdebase-runtime with:
0031 
0032     cmake -DDEBUG_PACKAGE_INSTALLER_NAME="installdbgsymbols.py" <other arguments>
0033 
0034 will use "installdbgsymbols.py" as the script for installing debug packages.
0035 
0036 
0037 Interface of the script
0038 =======================
0039 
0040 1. Arguments
0041 ------------
0042 The script is called with arguments all the filenames of the binaries that are clearly
0043 missing symbols. The first argument (argv[1]) is always supplied and is the path to
0044 the executable that crashed itself. The rest of the arguments are optional and are filenames
0045 of libraries that are missing symbols (for example, "/usr/lib/libkio.so.5"). All the
0046 paths are absolute, but they will probably point to symlinks (at least for libraries).
0047 The paths are taken from gdb. For each stack frame that is missing details, if gdb can
0048 tell where is this symbol from, the path to the library that gdb specifies is passed
0049 as is to the script. Note that for applications that were launched via kdeinit, argv[1]
0050 is the path to kdeinit4, not the path to the executable that would be launched if there
0051 was no kdeinit involved.
0052 
0053 2. Return values
0054 ----------------
0055 0 - Debug packages installed successfully
0056 1 - Some kind of error was encountered
0057 2 - Debug symbols not found
0058 3 - User canceled the operation
0059 
0060 
0061 Testing
0062 =======
0063 In order to test your script you can try the following:
0064 1) Find a kde application and remove its debug symbols package. I will use konqueror
0065    in this example.
0066 2) Run the application and then kill it with a signal that drkonqi can catch.
0067    For example, "killall -6 konqueror".
0068 3) In drkonqi's main dialog, switch to the "Backtrace" tab and wait for it to
0069    generate a backtrace.
0070 4) After the backtrace has been generated, if drkonqi can find your script, a button
0071    saying "Install debug symbols" will appear in the bottom left side of the backtrace tab.
0072 5) Click on it and your script will be launched.
0073 
0074 
0075 Examples
0076 ========
0077 I have written example scripts for Debian, OpenSuSE and Fedora, which are available
0078 in the examples/ subdirectory of the drkonqi source code directory. These were
0079 developed as a proof of concept, to test that this script model and interface will
0080 work for most distributions. You may use them as is, or you may use them as references
0081 to write your own scripts. Just note that I am not going to maintain those scripts
0082 or fix bugs in them.
0083 
0084 --
0085 George Kiagiadakis <kiagiadakis.george@gmail.com>
0086 Last updated: 25 Semptember 2009