summaryrefslogtreecommitdiff
path: root/DeveloperNotes/Debugging.mdwn
diff options
context:
space:
mode:
Diffstat (limited to 'DeveloperNotes/Debugging.mdwn')
-rw-r--r--DeveloperNotes/Debugging.mdwn110
1 files changed, 110 insertions, 0 deletions
diff --git a/DeveloperNotes/Debugging.mdwn b/DeveloperNotes/Debugging.mdwn
new file mode 100644
index 0000000..f50d02e
--- /dev/null
+++ b/DeveloperNotes/Debugging.mdwn
@@ -0,0 +1,110 @@
+## If you are using Empathy...
+
+Empathy has a debug console which shows you the debug output from components of your choice. See [[the Empathy wiki|http://live.gnome.org/Empathy/Debugging]] for more details.
+
+If you're not using Empathy, or you're debugging a crash, or you're just feeling old-school, read on!
+
+
+## Connection managers
+
+Many Telepathy problems are not directly the fault of the user interface (such as Empathy), but of the connection managers (Gabble, Idle, Salut, Haze, Butterfly, Telepathy-SofiaSIP, ...), which are the services responsible for actually connecting to your IM accounts. CMs generally run in the background, with no visible output; in order to get debugging output from them, you'll need to run them manually.
+
+Connection manager executables don't generally live in your `$PATH`, so you'll need to provide the full path in the following commands (rather than just `telepathy-foo`) to invoke them.
+
+* on Fedora-like systems, connection managers live in `/usr/libexec/`
+* on recent Debian-like systems connection managers live in `/usr/lib/telepathy/`
+* if you have installed from source, the default location is `/usr/local/libexec/`
+
+### Obtaining logs
+
+First, quit your IM client (such as Empathy), and wait a few seconds for the connection managers to quit of their own accord. Then, in a terminal, run:
+
+ G_MESSAGES_DEBUG=all FOO_PERSIST=1 FOO_DEBUG=all /path/to/telepathy-foo 2>&1 | tee foo.log
+
+(where `foo` should be `gabble` for Jabber, and the name of the relevant CM for the protocol you're having trouble with, as listed on [[Components|Components]]). Now, start your IM client again, and reproduce the problem; debugging output should appear in your terminal, and be written to `foo.log`. (You can set the `_DEBUG` variable to values other than `all` if you only want the debugging output from a certain part of the CM, but usually this is unnecessary.)
+
+If the connection manager complains about "name already or use" and quits immediately, you should `kill` any existing instances of it and try again.
+
+
+### Gabble
+
+When debugging Gabble, it's usually a good idea to set `WOCKY_DEBUG=xmpp` (Gabble 0.9) or `LM_DEBUG=net` (Gabble 0.8) so that the XML stanzas are also captured in the logfile.
+
+
+### SRV records (Gabble, SIP)
+
+If you're having difficulty connecting to a SIP or Jabber/XMPP server, and you're using Linux, you can check whether SRV DNS lookups are broken on your network using the `host` command-line tool. Collabora's XMPP server has a SRV record, which you can use to try this out, by running: `host -t SRV _xmpp-client._tcp.collabora.co.uk`
+
+If it works correctly, you'll see something like this:
+
+`_xmpp-client._tcp.collabora.co.uk has SRV record 0 0 5222 jalfrezi.collabora.co.uk.`
+
+If SRV lookups don't work on your network you might see an error like this, for instance:
+
+`Host _xmpp-client._tcp.collabora.co.uk not found: 3(NXDOMAIN)`
+
+
+### Mission Control 5
+
+In versions of MC older than 5.3.1 (notably, on Maemo 5), due to [[Bug #22705|https://bugs.freedesktop.org/show_bug.cgi?id=22705]] it is necessary to set `MC_DEBUG=1` to get Mission Control to output debug messages for itself, and something like `MC_TP_DEBUG=all` to output debug messages for telepathy-glib. See the mission-control-5 man page for more details.
+
+
+## Debugging crashes
+
+
+### General
+
+If you are experiencing crashes, it's a good idea to install any Telepathy debug packages provided by your distribution.
+
+On Debian-like systems, debugging packages include:
+
+* libtelepathy-glib0-dbg
+* libtelepathy-dbg
+* telepathy-gabble-dbg
+
+### GDB
+
+You might be able to obtain debug information using gdb (for connection managers, you probably also want to use the X_PERSIST variable for this):
+
+ $ GABBLE_PERSIST=1 gdb telepathy-gabble
+ GNU gdb 6.7.1-debian
+ Copyright (C) 2007 Free Software Foundation, Inc.
+ License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+ This is free software: you are free to change and redistribute it.
+ There is NO WARRANTY, to the extent permitted by law. Type "show copying"
+ and "show warranty" for details.
+ This GDB was configured as "i486-linux-gnu"...
+ Using host libthread_db library "/lib/i686/cmov/libthread_db.so.1".
+ (gdb) r
+ Starting program: /usr/bin/telepathy-gabble
+ ** (telepathy-gabble:17666): DEBUG: started version 0.6.0 (telepathy-glib version 0.7.0)
+
+If the program crashes while running under gdb, use the "bt" command to obtain a backtrace.
+
+If you can't make it crash while running under gdb (this is not an uncommon state of affairs, for reasons I won't go into here):
+
+* make sure core dumps are enabled
+ * `ulimit -c unlimited`
+* launch the telepathy component in question (as above)
+ * `FOO_PERSIST=1 FOO_DEBUG=all /path/to/telepathy-foo 2>&1 | tee foo.log`
+* do whatever it is you do to produce a crash
+* inspect the core file (it's normally called "core")
+ * `gdb /path/to/telepathy-foo core`
+ * at the gdb prompt: `bt full`
+NOTE: If you are running more than one component to debug, either tun them in different directories so their core files don't overwrite one another in the event of a crash, or `sudo sysctl -w kernel.core_uses_pid=1` to make the core file name contain the PID
+
+
+### Valgrind
+
+Valgrind can find many bugs.
+
+* [[Valgrind home page|http://valgrind.org/]]
+* [[suppression file|http://projects.collabora.co.uk/~robtaylor/glib+glibc.supp]] to stop it complaining about glibc and glib oddities.
+
+### Electric Fence
+
+Electric Fence can find some memory allocation bugs.
+
+To use it, run Programs with LD_PRELOAD=/usr/lib/libefence.so.0.0.
+
+* [[Electric Fence home page|http://perens.com/FreeSoftware/]].