Editing Debugging Octave

Jump to navigation Jump to search
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.

Latest revision Your text
Line 1: Line 1:
= Preliminaries =
= 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:
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:


Line 10: Line 9:
</syntaxhighlight>
</syntaxhighlight>


This will create a new build of Octave in a different directory without optimizations (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.


= Tools for debugging =
= Debugging Source files without GUI=


There are different tools for debugging. This article concentrates on describing how to use <code>gdb</code>.
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 command


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.
<syntaxhighlight lang="bash">
 
octave> system (sprintf ("gnome-terminal --command 'gdb -p %d'", getpid ()), "async");
Alternatively, you can attach a debugger to a running Octave session.  Current 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>.
</syntaxhighlight>
 
For some kinds of errors on some OS, the last approach might not be useful. The OS might kill the shell that runs gdb as soon as the spawning process (i.e. Octave) crashes. In that case, you can attach to Octave from an "independent" shell. Execute <code>getpid ()</code> in Octave and take note of the displayed *PID*. Open a shell and execute <code>gdb -p *PID*</code> (replace <code>*PID*</code> with the actual PID). On Windows, use the msys2 shell that can be started with the file <code>cmdshell.bat</code> in Octave's installation folder.
 
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.
 
*NOTE:  Ubuntu introduced a patch to disallow ptracing of non-child processes by non-root users - i.e. 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 31: Line 24:
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
</syntaxhighlight>
</syntaxhighlight>
and then reopen <code>gdb</code> using the command mentioned above from within an Octave session or if you have admin rights 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">
__debug_octave__ ("gnome-terminal --command 'sudo gdb -p %d'")
octave> system (sprintf ("gnome-terminal --command 'sudo gdb -p %d'", getpid ()), "async");
</syntaxhighlight>
 
 
Instead you can debug octave without gui using: 
<syntaxhighlight lang="bash">
./run-octave -g --no-gui
 
</syntaxhighlight>
</syntaxhighlight>


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


start now the GNU debugger with octave by following the instructions above.
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
 
<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 66: Line 72:
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 =
== Producing a stack trace ==
== Producing a stack trace ==


Sometimes Octave might 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. For this, it can be useful to (re)compile Octave with debugging symbols. Otherwise, the stack trace can be harder to read and optimizations might make debugging more difficult. (But it is also possible to produce a stack trace with a "standard" build.)
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 , only if you can afford such a huge work, and run the debugger, as explained above.  Then execute whatever commands are necessary to cause Octave to crash. At that point, you will be back in a gdb session. Type <code>where</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.
But if you can't or don't want to recompile octave ,which is totally normal, then you can 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 can be stored somewhere in the directory tree. You should find them, view them and inspect them.
 
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.


=== Where are core dumps stored? ===
=== Where are core dumps stored? ===
 
It differs on each system. First you should see what does handle core dumps on your system. to do so, type this in a shell terminal:
It differs on each system. First you should see how core dumps are handled on your system. To do so, type this in a shell terminal:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
$ cat /proc/sys/kernel/core_pattern
$ cat /proc/sys/kernel/core_pattern
</syntaxhighlight>
</syntaxhighlight>
This may print a file name pattern along with a path where all core dumps will be saved <b>ONLY</b> if it does not start by a pipe or '|'. If it does, <i>the kernel will treat the rest of the pattern as a command to run.  The core dump will be written to the standard input of that program instead of to a file</i>, and you need to consult that program's help or manual.
This may print a file name pattern along with a path, where all core dumps will be saved <b>ONLY</b> if it does not start by a pipe or '|'. If it does, <i>the kernel will treat the rest of the pattern as a command to run.  The core dump will be written to the standard input of that program instead of to a file</i>, and you need to consult that program's help or manual.


=== How to view a core dump? ===
=== How to view a core dump? ===
To do this you should use gdb. Core dumps are saved under root user, so you may need to change owner of the core dump you are interested in if you are not logged in as root. After that type in the terminal:
To do this you should use gdb. Core dumps are saved under root user, so you may need to change owner of the core dump you are interested in if you are not logged in as root. After that type in the terminal:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
Line 102: Line 103:
3. Some debug info are missing. In this case gdb itself will tell you how to install them. Install them and start gdb again.
3. Some debug info are missing. In this case gdb itself will tell you how to install them. Install them and start gdb again.


If everything worked fine, you can use <code>where</code> command in gdb prompt to see a full stack trace of the crash.
If everything worked fine, you can use 'where' command in gdb prompt to see a full stack trace of the crash.
 
=== Helpful gdb commands ===


=== Most used commands ===
[http://www.gnu.org/software/gdb/documentation gdb documentation]
[http://www.gnu.org/software/gdb/documentation gdb documentation]


The following command shows the back trace of all threads belonging to the Octave process:
For debugging octave_value variables (e.g. <code>my_octave_value</code>) to find out what the variable actually is (instead of just it's base class):
<syntaxhighlight lang="bash">
(gdb) thread apply all bt
</syntaxhighlight>


For debugging octave_value variables (e.g. <code>my_octave_value</code>) to find out what the variable actually is (instead of just it's base class):
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
(gdb) print *(my_octave_value.rep)
(gdb) print *(my_octave_value.rep)
</syntaxhighlight>
</syntaxhighlight>
The file <code>etc/gdbinit</code> in the Octave repository contains some macros that can be helpful:
* <code>display-dims DIM_VECTOR</code>: Display the contents of an Octave dimension vector.
* <code>display-dense-array ARRAY</code>: Display the contents of an ordinary, i.e., dense Octave array.
* <code>display-sparse-array SPARSE_ARRAY</code>: Display the contents of a sparse Octave array.
* <code>show-octave-dbstack</code>: Display the contents of the current Octave debugging stack.


== ddd ==
== ddd ==
 
[http://www.gnu.org/software/ddd gui for gdb]
[http://www.gnu.org/software/ddd GUI for gdb]


[[Category:Development]]
[[Category:Development]]
Please note that all contributions to Octave may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see Octave:Copyrights for details). Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel Editing help (opens in new window)
Retrieved from "https://wiki.octave.org/Debugging_Octave"