7. Debugging

There are several types of problems you'll encounter, and each has a proven solving technique.

7.1 Compilation problems

Solution: learn how to program in C++

No, I mean seriously, learn C++, thoroughly, until you are able to truly and fully understand every single bit of the cryptic message issued by the compiler, and why on earth it may have chosen to insult your intelligence with it. Because that cryptic message always contains the solution.

In particular, you need to really understand the difference between a const thingy and a non-const thingy, because to C++ they are often two totally different beasts (although to a decent human, they may look the same at first inspection).

So make sure you truly understand all the subtle differences between for ex.:
const char* MyObj::mymethod(const char* &foo, const int& bar)
and char* MyObj::mymethod(const char *const foo, int& bar) const

On rare occasions, you might occasionaly stumble upon a compiler bug (as in compiler internal error!!! ), in which case you may try the following: upgrade your dusty compiler to the newest less-buggy version; check on google to see if anybody else had the same problem and if they found a workaround; try to find a workaround yourself (split your call in several pieces, using intermediate variables, add a cout here, reorder the instructions there... and pray!); try posting an SOS on the appropriate newsgroups; write a bug report! Somebody somewhere, is responsible for it and might be interested in fixing the mess, or already has...

7.1.1 Frequently encountered compilation errors

To save you some time, you may look up in the following list if somebody stumbled upon the same problem.

• typical error msg
  explanation and fix.

7.2 Linking problems

Problems reported by the linker can have several causes:

• It doesn't find a function that's supposed to be defined somewhere in your code but isn't. A frequent case is that of instantiating an object of a class derived from a base class with a pure virtual mamber function that you forgot to define in the subclass. Another case is declaring a function in the .h and forgetting to implement it in the .cc, or (more often) implementing it with a slightly different signature (forgot Classname:: ?, forgot to put a const somewhere?)
• It doesn't find symbols because it doesn't find the required libraries. Examine the linking command, are all the necessary libraries there? Are they indeed located where you say they are? There should be no space between the -L and the library path.
• Libraries are specified in an inappropriate order. A library that depends on another library should appear before it in the linking command; the most basic libraries should be last.

7.3 Clean runtime errors

What I mean by clean runtime errors, is that the program displayed a nice error message and exited.

This most likely means that something in your program caused a call to the PLERROR macro, which called the errormsg function, which threw a PLearnException, which got caught in the very external try/catch of your main program, which printed it out (you main program does catch PLearn exceptions and report them, doesn't it???).

Tracing the problem is easy:

• Launch your favorite debugger (gdb) from within your favorite development environment (emacs).

• Put a breakpoint in the errormsg function by typing:
  br 'PLearn::errormsg(TAB
  Pressing the TAB key will complete the signature of the function for you. Note that the single quote at the beginning is important for this to work.

• run your program until it reaches the breakpoint.

• trace up the call stack and figure out what and why it happens.

Hints for using gdb:
gdb is always at quite a lag behind, playing catch-up with the latest compiler. Sot it has problems. Here are a few hints for working with it, or in spite of it...

• printing a std::string doesn't work. Cast it to a char* first, as in p (char *) my_string, or call p my_string.c_str()

• gdb often seems lost when you attempt to examine the insides of a complex object, replying that it can't find info on that class. In this case, unfortunately, you'll have to insert instructions in the code to print the desired debug info (with cerr << ...), recompile and rerun gdb.

• If you want to see an object on which you have a PP smart pointer (or similar type), you can access the raw pointer inside (it's called ptr!), for ex: p my_var.ptr->value.length_

I also suggest you learn using a good integrated development environment (IDE) like Emacs. Emacs has multiple windows, a compilation mode (pressing return on an error will bring you directly to the problematic line of the problematic file), and a gdb mode (with which you can easily follow the step by step execution, as an arrow is always displayed before the next instruction to be executed, and you can rapidly put a breakpoint (Ctrl-X SPACE) anywhere).

With the proper key definitions (learn how to define your own keys for maximum efficiency!), a complete recompile of your code, and reload in gdb is just one key away. You won't have to touch the rat. And yes, it even all works perfectly fine (multiple windows and all) inside a single text terminal over a telnet connexion for ex. (invoke it using emacs -nw).

7.4 Dirty runtime errors

By this, I mean segmentation fault and the like.

• First try running your code in gdb, as above.
• If this doesn't appear too helpful on its own (and probably won't), try running your program with valgrind. It's a great tool for catching memory bugs (like writing or reading from memory areas you never allocated or initialized.). You can run it like that, from a shell:
  valgrind --gdb-attach=yes your_prg_and_its_args