Debug on macOS Platforms

Using Xcode

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

Copy Source MEX File
Compile Source MEX File
Create Empty Xcode Workspace for Debugging
Add yprime Files to Xcode Workspace
Create Scheme
Add Symbolic Breakpoint
Set Breakpoints in Your MEX File
Start Xcode Debugger and Run MATLAB
Run Binary MEX File in MATLAB

Copy 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 /Users/Shared/work. Create the folder if it does not exist, and set it as your current folder in MATLAB.

workdir = fullfile('/','Users','Shared','work');
mkdir(workdir)
copyfile(fullfile(matlabroot,'extern','examples','mex','yprime.c'),workdir)
cd(workdir)

Compile Source MEX File

Compile the source MEX file with the -g option, which adds debugging symbols. MATLAB creates the binary MEX file, yprime.mexmaca64 on macOS with Apple silicon.

mex -g yprime.c

Create Empty Xcode Workspace for Debugging

In Xcode,

Select File > New > Workspace.
In the file selection dialog box, set the Workspace name in the Save As: field to debug_yprime.
Select the /Users/Shared/work folder in which to store the workspace. To select the folder, either navigate to the folder, or press the Command+Shift+G keyboard shortcut to toggle the Go to the folder: menu and type the full path /Users/Shared/work.
Click Save.

Add yprime Files to Xcode Workspace

To add the yprime.c file to the workspace, drag it from the /Users/Shared/work folder in the Finder into the navigator column on the left side of the Xcode workspace window.
Clear the Destination option, Copy items into destination group's folder (if needed). Clearing this option enables breakpoints to be added to the file that MATLAB runs.
To add the file, click Finish.

Create Scheme

Select Product > Scheme > New Scheme....
Leave Target set to None.
Set Name to debug.
Press OK. The scheme editing dialog box opens.
Set the Run > Info > Executable option to Other.... In the file selection window, press the Command+Shift+G keyboard shortcut to toggle the Go to the folder: menu. Specify the full path to the MATLAB_maca64 executable inside the MATLAB application bundle. An example of a full path is /Applications/MATLAB_R2023b.app/Contents/MacOS/MATLAB_maca64.
Select Wait for executable to be launched.
Click Close.

Add Symbolic Breakpoint

Select Debug > Breakpoints > Create Symbolic Breakpoint.
Set Symbol to NSApplicationMain.
To add the following debugger command, click Add action:
```
process handle -p true -n false -s false SIGSEGV SIGBUS
```
If the breakpoint editor pane disappears, right-click the new breakpoint and select Edit Breakpoint… to get back to it
Check Automatically continue after evaluating actions.

Set Breakpoints in Your MEX File

Select View > Navigators > Show Project Navigator.
Click yprime.c in the navigator column.
Click the gutter next to the line where you want execution to pause, for example, at the first line in mexFunction().
For more information, refer to the Xcode documentation.

Start Xcode Debugger and Run MATLAB

To start the debugger, in Xcode select Product > Run. Alternatively, click the Run button with the triangle icon near the top left corner of the workspace window.
Wait for Xcode to display the message Waiting for MATLAB to launch at the top of the Workspace window. This action might take some seconds, especially the first time you use this procedure.
Start the MATLAB executable from the Mac Terminal prompt (see Start from Terminal Window) or from the Finder. If MATLAB is already running, right-click the MATLAB icon in the Dock and select Open Additional Instance of MATLAB.
Xcode displays the message Running MATLAB: debug.

Run Binary MEX File in MATLAB

In this new instance of MATLAB, change the current folder to the folder with the yprime files and run the MEX file.

workdir = fullfile('/','Users','Shared','work');
cd(workdir)
yprime(1,1:4)

The Xcode debugger halts in yprime.c at the first breakpoint.

At this point you can step through your code, examine variables, etc., but for this exercise, select Continue from the Debug menu. The execution of yprime finishes and MATLAB displays:

ans =

    2.0000    8.9685    4.0000   -1.0947

As long as this instance of MATLAB continues running, you can execute your MEX file repeatedly and Xcode halts at the breakpoints you set.

Using LLDB

LLDB is the debugger available with Xcode on macOS 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.

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
```
Start the lldb debugger using the matlab function -D option:
```
% matlab -Dlldb
```
Start MATLAB using the -nojvm startup flag:
```
(lldb) run -nojvm
```
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.
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
```
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
```
After stopping at the last breakpoint, type:
```
(lldb) c
```
yprime finishes and MATLAB displays:
```
ans =

    2.0000    8.9685    4.0000   -1.0947
```
From the MATLAB prompt, return control to the debugger by typing:
```
>> dbmex stop
```
Or, if you are finished running MATLAB, type:
```
>> quit
```
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, first handle SIGSEGV and SIGBUS process signals. Start MATLAB and stop at the first instruction.

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.