Debugging

This page provides help with debugging in BRAHMS.

Getting maximal information

The BRAHMS executable understands various options that change (generally, raise) the detail level of the log. These are detailed under Command Line, but the switches --d and --dd provide almost maximal and maximal information, respectively, and will probably be all you need. --dd is just like --d but run-phase event calls in the worker threads are logged (there are a lot of these, typically, so this will slow your execution considerably).

You can pass these options via the Matlab Bindings by using the syntax out = brahms(sys, exe, opt, opt, ...). Alternatively, use inv = brahms('prep', sys, exe) to set up the call and then invoke BRAHMS from the shell, passing the arguments directly to the executable.

Attaching a system debugger

Use inv = brahms('prep', sys, exe) in Matlab to prepare a BRAHMS invocation but not invoke it. You will find the call that would have been made to invoke in inv.launch, and you can then invoke that from a command shell. Hence, you can now invoke the executable through a debugger. On Linux, I think the syntax would be gdb <command line>, and then you would type run at the gdb prompt to set it off. But don't quote me on that.

This won't help you much unless you have debugging symbols available. Turn on generation of debugging symbols when you compile your process. If you want to debug BRAHMS itself, you will have to build it with debug symbols in, or obtain a debug build (not available at time of writing). But you won't need a debug build of BRAHMS to debug your component.

Charles's Experience

Problem

I am developing a Brahms component in C++ and it is dying in its run or init phase. I want to step through my C++ code with gdb, but as part of the brahms run, without worrying about BRAHMS source code.

Solution

You do not need to recompile Brahms itself with debug info. Make sure your component is compiled with g++ -g (-g is the debug flag). Build a system including the component as a matlab script, go.m. Run Brahms from matlab using this go.m script; this creates an XML file, ~/SystemML/BRAHMS/temp/unnamed-exe.xml (or some such). Execute this XML file using BRAHMS at the shell, i.e. not through Matlab, for example:

OS Shell Prompt
$ export LD_LIBRARY_PATH=/home/charles/SystemML/BRAHMS/bin $ brahms-execute ~/SystemML/BRAHMS/temp/unnamed-exe.xml

We can also run it through gdb with

OS Shell Prompt
$ export LD_LIBRARY_PATH=/home/charles/SystemML/BRAHMS/bin $ gdb --args brahms-execute ~/SystemML/BRAHMS/temp/unnamed-exe.xml

In gdb, we need to set a breakpoint in our function of interest. This is a little harder than usual because at this point, our module hasn't been loaded (dynamically by BRAHMS) yet, so none of its symbols are known to gdb. Instead, we can query the .so file corresponding to our module, to manually see the symbols for our function, in this case "callPython". Look for a line containing your function, for example:

OS Shell Prompt
$ nm /home/charles/SystemML/Namespace/dev/temp/python/brahms/0/libbrahms-dev_temp_python.so.0 | grep callPython ... 000017a0 T _ZN17dev_temp_python_010callPythonEbRSt6vectorI12DOUBLE_ARRAYSaIS1_EES4_ ...

The big name on the right is the (mangled) symbol. In gdb, set a breakpoint and then run, using:

OS Shell Prompt
gdb> b _ZN17dev_temp_python_010callPythonEbRSt6vectorI12DOUBLE_ARRAYSaIS1_EES4_ gdb> run

and the code breaks as desired. How cool is that?