[Libreoffice] gdb pretty printers landed in master

Hi all,

as the subject says, I pushed my gdb pretty printers into master.


== What is it? ==

gdb 7 includes support for scripting in Python, which, among other
useful things, allows to write pretty printers for arbitrary data types
(did you ever wish that rtl::OString be shown like a string? Your wish
has come true :)


== What is there? ==

We have pretty printers for, e.g., the following:
* rtl and tools' strings
* some tools' types like Date, Time, BigInt...
* UNO stuff, like Any or Sequence
* some other, probably less useful, stuff, like SvArray


== How do I use it? ==

First thing, you need gdb 7.x with enabled support for python.
Everything should work with gdb 7.0, but I suggest using at least 7.2,
as there are some really nice improvements there. Then it depends on
what do you want to use it for:

1. for devel. installation

The pretty printers are activated automatically on make dev-install,
unless smoketest failed. You can always (re)activate them by running

install-gdb-printers -a "$SOLARVER/$INPATH/installation/opt" -L

in build env. (The install-gdb-printers script is probably going to
change yet, but the arguments should stay the same.)

2. for arbitrary installation

It is possible (or it should be possible :) to use the
install-gdb-printers script to create auto-loaders (see the next
section) in arbitrary installation directory. If you don't want to do
that for any reason, it is still possible to load the pretty printers
unconditionally. Just add the following snippet to your ~/.gdbinit :

python
import os.path
import sys

import gdb

pythondir = '/path/to/build/solenv/gdb'

if pythondir not in sys.path:
    sys.path.insert(0, pythondir)

from libreoffice import cppu, sal, svl, sw, tl

cppu.register_pretty_printers(gdb.current_objfile())
# ... the same for sal, svl, sw and tl

end


== How does it work? ==

To make it as easy to use as possible with devel. installations (i.e.,
without any set up required of the developer), the pretty printers are
split by libraries and auto-loaders are used to load them into gdb. An
auto-loader is just a python file that sits next to the library it loads
pretty printers for, with the same name as the library plus -gdb.py
suffix. The auto-loaders are created (from solenv/gdb/autoload.template)
by install-gdb-printers script, which is run as part of make dev-install.

(There is actually even simpler way to associate a pretty printer file
with a library, through special section .debug_gdb_scripts, but that is
only available from gdb 7.2 up.)

From gdb 7.2 up, it is possible to list active pretty printers and
enable/disable them. For details see gdb help for "info pretty-printer",
"enable pretty-printer" and "disable pretty-printer".


== How can I contribute? ==

If you want to know more, read the sources: all the pretty printers
reside in solenv/gdb/libreoffice, split into files by library name. The
template used for generating auto-loaders is in
solenv/gdb/autoload.template. There are not many comments, but hopefully
the code is clear enough. If you have ideas/patches, send them to me (or
commit them directly--just try to follow the conventions).

I have a "test" suite of a kind, loading pretty printers for a given
library and trying to print various kinds of stuff, that I am going to
push into contrib/dev-tools repo soon. Even if it is not fully
automated, as it relies on the observer's eyes to spot problems, I found
tens of bugs thanks to it. I therefore kindly ask any contributors to
add test examples to this suite for any new pretty printer.


== Questions / praise / bashing? ==

I do hope I have made this clear, but, from experience, I do not really
believe it... So feel free to ask any questions :)

D.