Exceptions
We have recently added exception handling. If an exception is thrown, a detailed error message is provided, containing information about: the general kind of error, details of the particular error, the exact location in the source code where the exception was thrown. For example
BAD QUERY FORMAT: invalid separator found ("%", in CompleterBase.cpp, line 935, function void CompleterBase<MODE>::processQueryRecursively(...) [with unsigned char MODE = 7])In many cases, this will provide enough information to trace down the (cause of) the error.
Debugging with gdb
Despite of this, low-level debugging will be needed at times. Here is a short HowTo:
1. Compile everything with the -g option, do not define NDEBUG, and do not use optimization (because that affects the ability of the debugger to map the code from the executable to lines from the source code). To do this via CompleteSearch's Makefile, type
make <target> CXX_DEBUG="-g -O1"
2. Then invoke gdb, in gdb say run, and then backtrace, e.g. (where $ is the shell prompt and (gdb) is the gdb prompt)
$ gdb try-intersect (gdb) run <put command line parameter here> [Program will be executed within gdb] (gdb) backtrace [will print the state of the frame stack just after the crash, i.e., it will show in which function the error occurred, and from which function that function was called, and so on.]
Often this gives a strong hint at what happened alrady.
3. In the worst case, one has to step through the program, set breakpoints, watch certain variables (and run the code until they change), etc. Here is a short synopsis of the most useful gdb commands. For a manual, see [TODO: link to a good online resource]:
(gdb) set history save on // so that commands are still available in the next invocation of gdb (gdb) breakpoint CompletionServer.cpp:176 // set breakpoint at this line of code (gdb) run // run program until next breakpoint or end (gdb) print x // print content of variable x from code (gdb) continue // continue running program until next breakpoint or end (gdb) step // continue until next line of code (gdb) next // like step, but do a function call in one step (gdb) watch x - y // watch an expression (run and continue will stop when it changes) (gdb) help watch // get short help on any command (gdb) delete // delete all breakpoints