Debugging Octave

Preliminaries

Since compilation of all the source from scratch can take long it is good to have a source folder where most of the source has been compiled. To do this, you can create a parallel build:

mkdir dbg-octave
cd dbg-octave
/path/to/octave/source/configure FFLAGS=-g CFLAGS=-g CXXFLAGS=-g --enable-bounds-check --prefix=/opt/dbg-octave
make # or make -jN where N is the number of CPU cores

This will create a new build of Octave in a different directory without optimisations (no -O2 gcc parameter) and with debug symbols compiled in. This build is useful for debugging Octave itself.

Debugging oct-files

To debug oct-files, avoid making any optimization during compilation. Use export CXXFLAGS="-ggdb -Wall -O0" for C++ code or export CFLAGS="-ggdb -Wall -O0" for C code to suppress optimization. Compile the oct-file with the debug flag -g which enables debug symbols

mkoctfile -g file.cpp

start now the GNU debugger with octave

gdb octave

and run it

(gdb) run

Octave will start up. To load the symbol table the function needs to be executed, for example by invoking the help function

octave:1> help file

Now halt execution of Octave by typing ctrl+c, you'll see again the gdb prompt. Set now a breakpoint in the line of interest

(gdb) b file.cpp:40

by typing c the execution of octave will continue and you can run your oct-file directly or via an m-script.

octave:1> x = file(y)

the debugger will stop on the above defined line and you can start debugging according to the manual of GNU debugger.

If you encounter problem with interrupting octave (i.e. "^C" is only printed when you press ctrl+c and control is not transferred to gdb) then you might follow following steps (which should work always).

1. Start gdb
   

   > gdb octave
   

2. Catch loading of your oct-file ("file" below is a regex matching name of your oct-file)
   

   (gdb) catch load file
   

3. Run octave
   

   (gdb) r
   

4. From octave request loading of your oct-file by calling function
   

   octave> x = file(y)
   

5. Control will switch to gdb just after oct-file is loaded and at this point all symbols from oct-file are available so you can either set up a breakpoint at particular line or at function entry.
   

   (gdb) b file.cpp:40
   

6. Resume execution of octave by
   

   (gdb) c
   

and debugger will stop at the breakpoint defined.

Tools for debugging

GDB

To start Octave under gdb use the script run-octave at the top level of the build tree and run it with the command-line option -g like this

   cd /octave/build/tree
   ./run-octave -g

Producing a stack trace

Sometimes Octave will crash, meaning, it terminates abruptly and returns control to the operating system shell. In these cases, it is very helpful to produce a stack trace to diagnose the problem. To do so, you need to (re)compile Octave with debugging symbols and run the debugger, as explained above. Then, run Octave:

gdb> run

execute whatever commands you think are necessary to produce the crash. When Octave crashes, you will be back in a gdb session. Type bt here to obtain a stack trace.

Most used commands

gdb documentation

Emacs

In short:

To start Octave in debug mode within emacs type

M-x gud-gdb

then change the command in the minibuffer to

Run gud-gdb (like this): /path/to/octave/build/tree/run-octave -gud

For more info use this link to the emacs manual section on debuggers operation

ddd

gui for gdb