Appendix E. Debugging

General information

Debugging is a skill which you can learn. There are quite a few good documents that describe how to make a good bug reports. Please read them before you get into action, your bug won't run away and it won't kill you. Rather we want to kill the bug and we want your help :-) So lets go to battle well prepared. Two nice documents are the Bugzilla Bug Reporting HOWTO and Simon Tathams How to Report Bugs Effectively.

Due to the nature of some unofficial patches, we can't support them all. This means (for you) that you should check if Fluxbox crashes without the patches you applied, too. If the patches of your Fluxbox were applied by some distribution maintainer, contact him about the issue.

If you require more help with debugging than this guide provides, you may also see if one of people on #fluxbox at irc.freenode.net is of help. As the main developers and quite a bunch of qualified people are usually there, chances are that we can sort things out.

Specific Fluxbox things

Output from Fluxbox

Like any other application Fluxbox sends all messages to the console it was started from. The problem is that under normal circumstances all output goes to the text console. Change your Fluxbox start line to exec xterm or whatever your favorite terminal emulator may be. Start X11 and start Fluxbox in that xterm, and lo and behold, you can easily see all messages from Fluxbox.

The info we want

We want to know a lot of things. Make sure you know all about them.

What to do with core dumps.

So if you ever get a core dump with Fluxbox do the following: Go to the channel #fluxbox on OPN and tell fluxgen you got a core dump. Give him all the info he asks for. He will probably also ask you to do the following. It's quite a lot of work but anybody with a bit of common sense and some Unix experience can do it. Oh, and you need the GNU debugger, called gdb.

Rebuild Fluxbox

Yes you read it right. To become a real debugger you have to rebuild Fluxbox with debugging symbols.

Build Fluxbox as usual and add the following option when you do the make:

    $ CFLAGS=-Wall -g3 CXXFLAGS=-Wall -g3 make

If you use the source RPMs from the Fluxbox site or your distribution you can do something like this:

    $ su
    # rpm -ivh fluxbox-0.1.11.1mdk.src.rpm
    # cd /usr/src/RPM/SPECS
    # env DEBUG=true rpm -ba fluxbox.spec
    # rpm -Uvh --force /usr/src/RPM/RPMS/i686/fluxbox*
    # exit
    $ mkdir -p ~/src/fluxbox
    $ cp -R /usr/src/RPM/BUILD/fluxbox* ~/src/fluxbox

Go to the Fluxbox directory (So we get the core dump in the right place). The shell has a nifty feature that disables core-files so make sure you really get a core file with:

    $ ulimit -c unlimited

Start X11 and let's debug. Do whatever it takes to make Fluxbox dump core. And now we start debugging:

    $ gdb fluxbox core

And issue this command in gdb (the first part is gdbs prompt, don't type it :)):

    (gdb) where

Now you get a lot of output. Fluxgen wants to know all the output that starts with a #.

Now paste that into an e-mail to fluxgen and also attach the four settings files in ~/.fluxbox/.

Please do not remove the core and the source code directory yet. Fluxgen may want to ask you a few extra question and then you will need them. Please do not send the core file to fluxgen if he does not ask specifically - since it is specific to your system, it most probably is of no use to him and core files tend to be quite big.