How can I use Visual Studio Code to debug my MinGW C/C++ file?

I have a C/C++ MEX file compiled by the MinGW64 compiler with the -g flag. How can I debug my MEX through Visual Studio Code?

Answer 1

[MathWorks Support Team]

The GDB debugger that comes with the MinGW64 compiler can be used to debug your MEX code with Visual Studio Code (VS Code). The debugging process is outlined in the steps below.

Preliminaries

Download the VS Code project

Download and unzip the attached folder ("MEX VSCode debugging example.zip"), which encapsulates the VS Code example project featured in this article. The folder contains the C++ MEX source code ("offset.cpp") and the Visual Studio .vscode folder with the JSON project files ("settings.json", "c_cpp_properties.json", and "launch.json"). Note that the "offset.cpp" code comes from the documentation example: Create a C++ MEX Source File.

Install the MinGW64 compiler

Install the MinGW64 compiler, if you have not already done so. See MATLAB Support for MinGW-w64 C/C++/Fortran Compiler for a table of supported MinGW64 versions by MATLAB release and download instructions. Important note: The debugging workflow outlined below will not work with the MinGW 8.1 due to a known issue.

Install the "C/C++ for Visual Studio Code" extension

Install the Microsoft "C/C++ for Visual Studio Code" VS code extension, if you have not already done so. In the left panel, select "Extensions", search for "microsoft c/c++", select "C/C++ IntelliSense, debugging, and code browsing" ("ms-vscode.cpptools"), and "install". This extension is needed to support debugging the MEX C/C++ native code.

Debugging workflow

Edit the "settings.json" file

Open the ".vscode/settings.json" file, which stores user and workspace configuration settings. 

.vscode/settings.json

{
"matlab.root": "C:/Program Files/MATLAB/R2025b",
// The MinGW path should be to the parent folder of the bin directory
"mingw.root": "C:/ProgramData/MATLAB/SupportPackages/R2025b/3P.instrset/mingw_w64.instrset"
}

You will need to edit the values for the "matlab.root" and "mingw.root" keys to correspond to your MATLAB and MinGW64 root paths. In the above example, we are using the default MATLAB and MinGW64 root paths for R2025b.

You can locate your MATLAB root folder using the following command in MATLAB.

>> matlabroot

When installing MinGW64 from MATLAB, the default location for MinGW64 root is as follows.

C:/ProgramData/MATLAB/SupportPackages/<MATLAB release>/3P.instrset/mingw_w64.instrset

For non-default install locations, the MinGW64 root path should be the parent folder for the "bin" directory. Note that VS Code requires forward slashes "/" for path definitions.

The configuration settings, above, are used to define MATLAB and MinGW64 paths in the ".vscode/c_cpp_configuration.json" and ".vscode/launch.json" files. The "c_cpp_configuration.json" file is not required for debugging, but will improve your editor experience (symbol navigation, code completion, header resolution). 

The ".vscode/launch.json" file configures the debugging workflow. 

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) Attach R24a and earlier",
            "type": "cppdbg",
            "request": "attach",
            "program": "${config:matlab.root}/bin/win64/MATLAB.exe",
            "processId": "${command:pickProcess}",
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "text": "handle SIGSEGV nostop"
                },
                {
                    "text": "handle SIGSEGV noprint"
                }
            ],
            "miDebuggerPath": "${config:mingw.root}/bin/gdb.exe"
        },
       {
            "name": "(gdb) Attach R24b and later",
            "type": "cppdbg",
            "request": "attach",
            "program": "${config:matlab.root}/bin/win64/MATLAB.exe",
            "processId": "${command:pickProcess}",
            "MIMode": "gdb",
            "miDebuggerPath": "${config:mingw.root}/bin/gdb.exe"
        }

    ]
}

In this example, it configures the GDB debugger to attach to a running MATLAB session so you can debug your MEX files while they execute. It also defines two configurations: (gdb) Attach R24a and earlier and (gdb) Attach R24b and later, depending on your MATLAB release. 

In releases R2024a and earlier, the GDB debugger tends to stop on all first chance SIGSEGVs, so it actually stops on any thrown SIGSEGV, even if it is going to be caught and dealt with correctly. The JVM started by MATLAB throws these SIGSEGVs on purpose and then catches them as part of its JIT process, and we do not want to stop in the debugger every time this happens. To tell the debugger to ignore these SIGSEGVs, we add "setupCommands", which are essentially GDB commands that automatically run when the debugger is started. For MATLAB R2024b and later, we need to remove the SIGSEGV setup commands, otherwise MATLAB will not hit the breakpoints set in Visual Studio Code. 

Compile the MEX code for debugging

In order to debug your MEX code in the VS Code editor, it must be compiled with the MinGW64 compiler and the "-g" debug flag. 

Open MATLAB and select the MinGW64 compiler using "mex -setup c" or "mex -setup cpp", depending on whether you are using C or C++ code. See Change Default Compiler for more information on changing the compiler. In this example, MATLAB indicates that the MinGW64 compiler is already selected.

>> mex -setup cpp
MEX configured to use 'MinGW64 Compiler (C++)' for C++ language compilation.

If you have multiple MinGW64 installations, MATLAB uses the version located at the "MW_MINGW64_LOC" environment variable. You can set the desired MinGW64 compiler using

>> setenv("MW_MINGW64_LOC","path/to/MinGW64/root/folder")

or check the location of the selected MinGW64 compiler using

getenv("MW_MINGW64_LOC")

The path should be the same as your "mingw.root" path in ".vscode/settings.json".

Compile the MEX file with the -g flag. We need this flag to cut optimizations in compilation and add debug symbols. For example, we create "offset.mexw64" here: 

>> mex -g offset.cpp
Building with 'MinGW64 Compiler (C++)'.
MEX completed successfully.

After compiling, you should see an "offset.mexw64" file. For more information on the "-g" flag and other compiler options see: MEX options.

Set breakpoints in the C/C++ code

Place a breakpoint on an executable line of code. For example, open "offset.cpp" and add a breakpoint on line 16 to stop the execution before the "checkArguments" function.

Attach the MATLAB process

MATLAB is running, so now we can attach our Visual Studio Code to its process. To ensure that you select the correct MATLAB process, determine the process ID for your MATLAB session using the appropriate method below.

R2024b and earlier

>> feature('getpid')

R2025a and later

>> matlabProcessID

In the left panel, select "Run and Debug" to open another panel. At the top, next to the green arrow button, open the dropdown and select either (gdb) Attach R24a and earlier or (gdb) Attach R24b and later, depending on which MATLAB release you are using. 

This selects one of the attach configurations we created in the ".vscode/launch.json" file. From here, select the green run arrow and VS Code will ask you to select a process. Attach to the MATLAB executable corresponding to your process ID by typing the process ID into the prompt and selecting the process. 

Run the MEX function

Now you can run your MEX function from MATLAB. For example,

>> offset(2, [1 2 3]) % Returns [3 4 5]

The breakpoint will be hit, and you can now step through and debug the code from inside VS Code. If MATLAB is unresponsive, make sure the VS Code debugger is not paused. See the Notes below for more information.

Notes

1. For more details on this workflow, please refer to this blog post, "MEX Debugging. Redefined.", by Martijn Aben.

2. While MATLAB is attached to the VS Code debugger, occasional pauses may occur due to handling SIGSEGVs thrown by the JVM started in MATLAB. In the "Run and Debug" panel, the VS Code Call Stack will show "PAUSED ON EXCEPTION" when VS Code pauses due to a SIGSEGV. As mentioned above, these SIGSEGVs are thrown on purpose as part of MATLAB's JIT process. During these pauses, MATLAB will be unresponsive, but you can hit "Continue" in VS Code to continue your workflow. 

Troubleshooting

If you receive a "program path is missing or invalid" error when attaching to the MATLAB process, try the following. 

1. Close and reopen MATLAB, then attach to the new MATLAB PID.

If the debugger is not stopping at the breakpoints in your code, here are some easily overlooked details to check for.

1. Make sure that you are not using MinGW 8.1. See the Install the MinGW64 compiler section.
2. MATLAB is not configured to the correct compiler. MEX might not be configured to the correct compiler for C/C++ language compilation. Ensure you have selected the "MinGW64 Compiler" and recompile the MEX code. See the Select the MinGW64 compiler section above for more details.
3. Debug symbols are not included in the MEX file. Compiling MEX files with debug symbols activated is necessary for breakpoints to work. To compile with symbols, use the "-g" flag. See the Compile with the debug flag section above. 
4. The "launch.json" file uses incorrect paths. Debugging may not work if paths in your launch configuration are incorrect. Ensure that you are pointing to the correct MATLAB and MinGW64 root folders in the "settings.json" file. These root folders are used in the "launch.json" file to point to the MATLAB and GDB executable files. See the Edit the settings.json file section above.