moin2mdwn: convert page Debugging

1 files changed, 116 insertions, 0 deletions

diff --git a/Debugging.mdwn b/Debugging.mdwn
new file mode 100644
index 0000000..2925d5e
--- /dev/null
+++ b/Debugging.mdwn
@@ -0,0 +1,116 @@
+
+
+## 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: 
+
+
+[[!format txt """
+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): 
+
+
+[[!format txt """
+$ 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/]]. 
\ No newline at end of file