Debugging Octave: Difference between revisions

Jump to navigation Jump to search
733 bytes removed ,  29 July 2020
no edit summary
(→‎Helpful gdb commands: Mention Octave-specific gdb macros)
No edit summary
Line 11: Line 11:
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.
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 Source files without GUI=
= Tools for debugging =
There are different tools for debugging. This article concentrates on describing how to use <code>gdb</code>.
 
If you run Octave from a build tree, execute <code>./run-octave -g</code> to start a gdb session that is prepared to run Octave (with the necessary environment correctly set up).  Note that when Octave runs in GUI mode, it forks at startup on Linux and MacOS systems, so this method will only work if <code>gdb</code> correctly follows the process across the <code>fork</code> and <code>exec</code> system calls.


Ubuntu introduced a patch to disallow ptracing of non-child processes by non-root users - ie. only a process which is a parent of another process can ptrace it for normal users - whilst root can still ptrace every process.
Alternatively, you can attach a debugger to a running Octave session.  Current development versions of Octave include the command <code>__debug_octave__</code> to manage the details. Executing this command at the Octave prompt should open a separate window for a debugger session attached to the current Octave process.  On Linux systems, the default terminal window is <code>gnome-terminal</code>. On MacOS systems, the default debugger is <code>lldb</code>.
That's why gdb won't be able to link to the octave process if you start gdb from within an Octave session using the command


<syntaxhighlight lang="bash">
Independent of how <code>gdb</code> was started and Octave was attached to it, it is now possible to issue gdb commands on the <code>(gdb)</code> prompt. See e.g. the [https://sourceware.org/gdb/download/onlinedocs/gdb/index.html gdb documentation]. To return to Octave while gdb is still attached to it, execute <code>continue</code> (or <code>c</code>) at the <code>(gdb)</code> prompt.
octave> system (sprintf ("gnome-terminal --command 'gdb -p %d'", getpid ()), "async");
 
</syntaxhighlight>
*NOTE*:  Ubuntu introduced a patch to disallow ptracing of non-child processes by non-root users - ie. only a process which is a parent of another process can ptrace it for normal users - whilst root can still ptrace every process.
That's why gdb won't be able to link to the octave process if you start gdb from within an Octave session using the <code>__debug_octave__</code> command


You can temporarily disable this restriction by doing:
You can temporarily disable this restriction by doing:
Line 26: Line 29:
and then reopen the gdb using the command mentioned above from within an Octave session or if you have admin right you can simply do:
and then reopen the gdb using the command mentioned above from within an Octave session or if you have admin right you can simply do:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
octave> system (sprintf ("gnome-terminal --command 'sudo gdb -p %d'", getpid ()), "async");
__debug_octave__ ("gnome-terminal --command 'sudo gdb -p %d'")
</syntaxhighlight>
 
 
Instead you can debug octave without gui using: 
<syntaxhighlight lang="bash">
./run-octave -g --no-gui
 
</syntaxhighlight>
</syntaxhighlight>


Line 50: Line 46:
</syntaxhighlight>
</syntaxhighlight>


start now the GNU debugger with octave.  On most Unixy systems, you can start gdb from within an Octave session by evaluating a command like
start now the GNU debugger with octave by following the instructions above.
 
<syntaxhighlight lang="bash">
octave> system (sprintf ("gnome-terminal --command 'gdb -p %d'", getpid ()), "async");
</syntaxhighlight>
 
at the Octave prompt.  This command will open a terminal window running gdb attached to the Octave process.  At this point, Octave will be stopped.


Now you can set a breakpoint in the line of interest of your oct-file in gdb prompt:
Now you can set a breakpoint in the line of interest of your oct-file in gdb prompt:
Line 71: Line 61:


the debugger will stop on the above defined line and you can start debugging according to the manual of GNU debugger.
the debugger will stop on the above defined line and you can start debugging according to the manual of GNU debugger.
= Tools for debugging =
There are different tools for debugging. This article concentrates on describing how to use <code>gdb</code>.
If you run Octave from a build tree, execute <code>./run-octave -g</code> to start a gdb session that is prepared to run Octave (with the necessary environment correctly set up).
Alternatively, you can attach <code>gdb</code> to a running Octave. For this, execute <code>gdb</code> in a shell. (On Windows, use the msys2 shell that can be started with the file <code>cmdshell.bat</code> in Octave's installation folder). Find the PID of the running Octave process and attach to it from the <code>(gdb)</code> prompt with <code>attach *PID*</code> (replace <code>*PID*</code> with the actual PID).
Yet another possibility is to start <code>gdb</code> using the <code>system</code> command at the Octave prompt. Depending on the used Linux shell, the command might look similar to (see the above comments wrt running this from the GUI in some distributions):
system (sprintf ("gnome-terminal -- gdb -p %d", getpid ()), false, "async");
On Windows, you can issue:
system (sprintf ("start gdb -p %d", getpid ()));
The last approach might not be useful for debugging some kinds of errors. The OS might kill the shell that runs gdb as soon as the spawning process (i.e. Octave) crashes.
Independent of how <code>gdb</code> was started and Octave was attached to it, it is now possible to issue gdb commands on the <code>(gdb)</code> prompt. See e.g. the [https://sourceware.org/gdb/download/onlinedocs/gdb/index.html gdb documentation]. To return to Octave while gdb is still attached to it, execute <code>continue</code> (or <code>c</code>) at the <code>(gdb)</code> prompt.


== Producing a stack trace ==
== Producing a stack trace ==
Line 93: Line 67:


Attach <code>gdb</code> to Octave as described before and return execution to Octave. Then, execute whatever commands are necessary to cause Octave to crash. At that point, you will be back in the gdb session. Type <code>where</code> or <code>bt</code> at the gdb prompt to obtain a stack trace.
Attach <code>gdb</code> to Octave as described before and return execution to Octave. Then, execute whatever commands are necessary to cause Octave to crash. At that point, you will be back in the gdb session. Type <code>where</code> or <code>bt</code> at the gdb prompt to obtain a stack trace.
When running in GUI mode or debugging threading issues, it is usually useful to get information about all the execution threads at the point of the crash.  To do that, use the gdb command <code>thread apply all bt</code>.


You could also get some help from your system tools. In most GNU/Linux systems whenever a crash happens in a software, a <i>core dump</i> will be generated. These core dumps are handled by a registered component of the system and finally might be stored somewhere in the directory tree. You should find them, view them and inspect them.
You could also get some help from your system tools. In most GNU/Linux systems whenever a crash happens in a software, a <i>core dump</i> will be generated. These core dumps are handled by a registered component of the system and finally might be stored somewhere in the directory tree. You should find them, view them and inspect them.

Navigation menu