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