Debugging on Mac Platforms

Using Xcode

This example shows how to debug the MEX-file, yprime.c, using Xcode.

Copy the source MEX file

The yprime.c source code is in the matlabroot folder. In MATLAB®, copy the file to a local, writable folder, for example /usr/work/my_data. Create the folder if it does not already exist.

copyfile(fullfile(matlabroot,'extern','examples','mex','yprime.c'), ...
fullfile('/','usr','work','my_data'))

Set your current folder in MATLAB to /usr/work/my_data.

Compile the source MEX file

Compile the source MEX-file with the -g option, which adds debugging symbols.

mex -g yprime.c

MATLAB creates the binary MEX-file, yprime.mexmaci64.

Create an empty Xcode project for debugging

In Xcode,

  • Select File > New > Project.

  • In the Choose a template for your project dialog box, in the OS X section, select Other.

  • Select Empty.

  • Set Product Name to debug_yprime.

Add yprime files to the project

To add breakpoints to your source code file, add the yprime.c file to the project. You can either drag the file directly into the project or right-click in the project and click Add files to "debug_yprime" to add files.

Make sure the Destination option, Copy items into destination group's folder (if needed), is unchecked. Unchecking this option enables breakpoints to be added to the file that MATLAB runs.

Click Finish to add the file.

Create a scheme

  • Select Product > Scheme > New Scheme....

  • Set Name to debug.

  • Set Target to None.

  • Press OK. The scheme editing dialog box opens.

  • Set the Run > Info > Executable option to the MATLAB executable to use to debug the MEX-file, for example, MATLAB_R2014a.app.

Add a symbolic breakpoint

Open the Debug menu:

  • In Xcode 4.6.x:

    Select Product > Debug > Create Symbolic Breakpoint .

  • In Xcode 5.0 and later:

    Select Debug > Breakpoints > Create Symbolic Breakpoint.

Set Symbol to NSApplicationMain.

Click Add action to add the following debugger command:

process handle -p true -n false -s false SIGSEGV SIGBUS

Check Automatically continue after evaluating.

Set breakpoints

To add a breakpoint to yprime.c, click the gutter next to the line where you want execution to pause. For more information, refer to the Xcode documentation.

Start MATLAB

Click Run at the top left of the project window (or type Command-R) to start the MATLAB executable. The executable pauses twice; press Continue.

Run the binary MEX-file in MATLAB

In MATLAB, change the current folder to the folder with the yprime files.

Run the binary MEX-file.

yprime(1,1:4)

The debugger opens yprime.c at the first breakpoint.

Press Continue. MATLAB displays:

ans =

    2.0000    8.9685    4.0000   -1.0947

Using LLDB

LLDB is the debugger available with Xcode on Mac OS X systems. Refer to the documentation provided with your debugger for more information on its use.

In this procedure, >> indicates the MATLAB command prompt, and % represents a Mac Terminal prompt. The debugger prompt is (lldb).

Debug MEX Without JVM

This example debugs the yprime MEX-file without the Java® Virtual Machine (JVM™). Running MATLAB in this mode minimizes memory usage and improves initial startup speed, but restricts functionality. For example, you cannot use the desktop.

  1. Compile the source MEX-file with the -g option, which builds the file with debugging symbols included. At the Terminal prompt, type:

    % mex -g yprime.c
  2. Start the lldb debugger using the matlab function -D option:

    % matlab -Dlldb
    
  3. Start MATLAB using the -nojvm startup flag:

    (lldb) run -nojvm
  4. In MATLAB, enable debugging with the dbmex function and run your MEX-file:

    >> dbmex on
    >> yprime(1,1:4)

    The debugger traps a user-defined signal and the prompt returns to lldb.

  5. You are ready to start debugging.

    It is often convenient to set a breakpoint at mexFunction so you stop at the beginning of the gateway routine.

    (lldb) b mexFunction
    
  6. Once you hit a breakpoint, you can use any debugger commands to examine variables, display memory, or inspect registers. To proceed from a breakpoint, type:

    (lldb) c
  7. After stopping at the last breakpoint, type:

    (lldb) c

    yprime finishes and MATLAB displays:

    ans =
    
        2.0000    8.9685    4.0000   -1.0947
    
  8. From the MATLAB prompt, return control to the debugger by typing:

    >> dbmex stop

    Or, if you are finished running MATLAB, type:

    >> quit
  9. When you are finished with the debugger, type:

    (lldb) q

    You return to the Terminal prompt.

Debug MEX with JVM

To debug a MEX-file with the JVM, you must first handle SIGSEGV and SIGBUS process signals. To do this, start MATLAB, stop at the first instruction, and then handle the signals.

  • At the Terminal prompt, compile the MEX-file and start the lldb debugger.

    % mex -g yprime.c
    % matlab -Dlldb
    
  • Start MATLAB.

    (lldb) process launch -s
  • Tell the process to continue when these process signals occur.

    (lldb) process handle -p true -n false -s false SIGSEGV SIGBUS
    
  • You can set break points and execute other debugger commands.

Was this topic helpful?