Debug on Linux Platforms

The GNU^® Debugger gdb, available on Linux^® systems, provides complete source code debugging, including the ability to set breakpoints, examine variables, and step through the source code line-by-line.

In this procedure, the MATLAB^® command prompt >> is shown in front of MATLAB commands, and linux> represents a Linux prompt; your system might show a different prompt. The debugger prompt is <gdb>.

This example shows the general steps to debug yprime.c, found in the MATLAB fullfile(matlabroot,"extern","examples","mex") folder.

Attach to MATLAB Process with gdb

Start MATLAB.
Compile the source MEX file with the -g option, which builds the file with debugging symbols included. At the MATLAB prompt, type:
```
>> mex -g yprime.c
```
Get the MATLAB process ID number. (since R2025a)
```
>> matlabProcessID
```
```
ans =

  uint64

   38932
```
At the Linux terminal, attach MATLAB to gbd using the process ID number.
```
linux> gdb -p 38932
```
Start the debugger.
```
<gdb> continue
```
When you want to start debugging MATLAB, interrupt gdb and enter the following commands.
```
<gdb> Ctrl+C
<gdb> handle SIGUSR1 stop print
```
If the JVM^® is loaded, type this command:
```
<gdb> handle SIGSEGV SIGBUS nostop noprint
```
To see if Java^® is loaded, at the MATLAB prompt, type:
```
>> jenv
```
Set a breakpoint at mexFunction, the entry point to your MEX function.
```
<gdb> break mexFunction
<gdb> continue
```
In MATLAB, run your MEX file.
```
>> yprime(1,1:4)
```
At this point you can step through your code.
```
<gdb> step
```
To complete the debugging session, type:
```
<gdb> continue
```

yprime finishes and MATLAB displays:

ans =

    2.0000    8.9685    4.0000   -1.0947

Start MATLAB with gdb

To debug with gdb:

At the Linux prompt, start the gdb debugger using the matlab function -D option.
```
linux> matlab -Dgdb
```
Tell gdb to stop for debugging.
```
<gdb> handle SIGUSR1 stop print
```
Start MATLAB without the desktop.
```
<gdb> run -nodesktop
```
If the JVM is loaded, type this command:
```
<gdb> handle SIGSEGV SIGBUS nostop noprint
```
To see if Java is loaded, at the MATLAB prompt, type:
```
>> jenv
```
Compile the source MEX file with the -g option, which builds the file with debugging symbols included. For this example, at the MATLAB prompt, type:
```
>> mex -g yprime.c
```
In MATLAB, enable debugging with the dbmex function and run your binary MEX file.
```
>> dbmex on
>> yprime(1,1:4)
```
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.
```
<gdb> break mexFunction
<gdb> continue
```
Once you hit one of your breakpoints, you can make full use of any commands the debugger provides to examine variables, display memory, or inspect registers.
To proceed from a breakpoint, type:
```
<gdb> continue
```
After stopping at the last breakpoint, type:
```
<gdb> continue
```
yprime finishes and MATLAB displays:
```
ans =

    2.0000    8.9685    4.0000   -1.0947
```
From the MATLAB prompt you can 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:
```
<gdb> quit
```
You return to the Linux prompt.

Refer to the documentation provided with your debugger for more information on its use.