1 files changed, 89 insertions, 0 deletions
diff --git a/kioslave/DEBUG.howto b/kioslave/DEBUG.howto
new file mode 100644
index 000000000..5275a26eb
--- /dev/null
+++ b/kioslave/DEBUG.howto
@@ -0,0 +1,89 @@
+This document describes how you can debug an io-slave with gdb.
+
+How does an io-slave get started?
+=================================
+
+Your application request 'klauncher' via DCOP for a slave. If 'klauncher' does 
+not have an idle slave ready, it will ask kdeinit to start a new one.
+kdeinit forks and dlopens the library that contains the io-slave.
+Then it calls kdemain() or, if that is not present, main() in the library.
+
+
+Attaching gdb to a io-slave
+===========================
+
+Due to the above sequence it is rather hard to get an io-slave in your
+debugger. But wait there is hope. You can start klauncher in such a way
+that slaves for a certain protocol are started in debug mode.
+
+E.g. to start all 'http' slaves in debug mode, you type:
+
+	KDE_SLAVE_DEBUG_WAIT=http kdeinit
+
+This will restart 'kdeinit' and 'klauncher'.
+
+When your application now requests a http slave, the slave will be started
+by kdeinit, but before it calls kdemain() (cq. main()) it will suspend the
+slave by sending it a SIGSTOP signal.
+
+In the terminal from which you started kdeinit you will get the following
+message:
+
+kdeinit: Suspending process
+kdeinit: 'gdb kdeinit 16779' to debug
+kdeinit: 'kill -SIGCONT 16779' to continue
+
+You can now debug your slave by typing (or pasting) 'gdb kdeinit 16779' in
+a terminal. If you don't want to debug a slave you can let it continue by
+sending it a SIGCONT by typing 'kill -SIGCONT 16779'.
+
+Be aware that slaves will not be killed while they are suspended.
+
+Once you have started gdb, you can set e.g. breakpoints and then resume the 
+slave by typing 'continue'. The debugger will return immediate with a message 
+that a SIGSTOP has been received so you will have to type 'continue' a second 
+time.
+
+
+Debugging io-slaves with valgrind
+=================================
+
+KLauncher can be told to run certain io-slaves through valgrind. The following
+command can be used to let klauncher run all https io-slaves via valgrind:
+
+	KDE_SLAVE_VALGRIND=https kdeinit
+
+The valgrind output will appear as the stderr output of the kdeinit process.
+The $VALGRIND_OPTS environment variable can be used to pass options to valgrind.
+If you want to use a different skin:
+
+	KDE_SLAVE_VALGRIND_SKIN=calltree      ( for example )
+
+
+How to get debug output
+=======================
+
+It is useful to redirect the debug output of your particular slave to a file 
+instead of stderr. E.g. I myself use the following lines in
+$KDEDIR/share/config/kdebugrc.
+
+       [7113]
+       InfoOutput=0
+       InfoFilename=/tmp/http
+       [7103]
+       InfoOutput=0
+       InfoFilename=/tmp/http 
+
+This redirects all debug info for areas 7103 and 7113 (as used by kio_http) 
+to the file /tmp/http.
+
+To get debug information from the SMB slave you can add the following to
+kioslaverc:
+
+[SMB]
+DebugLevel=100
+
+This will print additional debug info to the stderr of your kdeinit process,
+which typically ends up in ~/.X.err or ~/.xsession-errors
+
+Happy debugging.