This extension integrates MIEngine to support debugging of C/C++ programs using gdb.

Since this extension uses the same debug adapter (MIEngine) as ms-vscode.cpptools, it also uses the same type attribute "cppdbg". Therefore, a launch.json configuration designed for ms-vscode.cpptools can be used directly with this extension.

You should have gdb installed.

Please provide feedback by filing an issue on Gitee

A launch.json file is used to configure the debugger. To get started with debugging you need to fill in the program field with the path to the executable you plan to debug.

example configurations

{
    "name": "C++ Launch",
    "type": "cppdbg",
    "request": "launch",
    "program": "enter program name, for example: ${workspaceFolder}/a.out",
    "args": [],
    "stopAtEntry": false,
    "cwd": "${workspaceFolder}",
    "environment": [],
    "externalConsole": false,
    "MIMode": "gdb",
    "setupCommands": [
        {
            "description": "Enable pretty-printing for gdb",
            "text": "-enable-pretty-printing",
            "ignoreFailures": true
        }
    ],
    "miDebuggerPath": "/usr/bin/gdb"
}

Specifies the full path to the executable the debugger will launch or attach to. The debugger requires this location in order to load debug symbols.

Tells the Visual Studio Windows Debugger what paths to search for symbol (.pdb) files. Separate multiple paths with a semicolon. For example: "C:\\Symbols;C:\\SymbolDir2".

An optional flag that tells the Visual Studio Windows Debugger to require current source code to match the pdb.

Tells GDB or LLDB what paths to search for .so files. Separate multiple paths with a semicolon. For example: "/Users/user/dir1;/Users/user/dir2".

Used only when launching the debuggee. For attach, this parameter does not change the debuggee's behavior.

• Windows: When set to true, it will spawn an external console. When set to false, it will use integratedTerminal.
• Linux: When set to true, it will spawn an external console. When set to false, it will use integratedTerminal.
• macOS: When set to true, it will spawn an external console through lldb-mi. When set to false, the output can be seen in debugConsole. Due to limitations within lldb-mi, integratedTerminal support is not available.

In order to support Integrated Terminal with gdb on Windows, the extension adds console redirection commands to the debuggee's arguments to have console input and output show up in the integrated terminal. Setting this option to true will disable it.

Optional flags to determine what types of messages should be logged to the Debug Console.

• exceptions: Optional flag to determine whether exception messages should be logged to the Debug Console. Defaults to true.
• moduleLoad: Optional flag to determine whether module load events should be logged to the Debug Console. Defaults to true.
• programOutput: Optional flag to determine whether program output should be logged to the Debug Console. Defaults to true.
• engineLogging: Optional flag to determine whether diagnostic engine logs should be logged to the Debug Console. Defaults to false.
• trace: Optional flag to determine whether diagnostic adapter command tracing should be logged to the Debug Console. Defaults to false.
• traceResponse: Optional flag to determine whether diagnostic adapter command and response tracing should be logged to the Debug Console. Defaults to false.

.natvis file to be used when debugging. See Create custom views of native objects for information on how to create Natvis files.

When a visualizerFile is specified, showDisplayString will enable the display string. Turning on this option can cause slower performance during debugging.

Example:

{
   "name": "C++ Launch (Windows)",
   "type": "cppvsdbg",
   "request": "launch",
   "program": "C:\\app1\\Debug\\app1.exe",
   "symbolSearchPath": "C:\\Symbols;C:\\SymbolDir2",
   "externalConsole": true,
   "logging": {
       "moduleLoad": false,
       "trace": true
    },
   "visualizerFile": "${workspaceFolder}/my.natvis",
   "showDisplayString": true
}

JSON array of command-line arguments to pass to the program when it is launched. Example ["arg1", "arg2"]. If you are escaping characters, you will need to double escape them. For example, ["{\\\"arg1\\\": true}"] will send {"arg1": true} to your application.

Sets the working directory of the application launched by the debugger.

Environment variables to add to the environment for the program. Example: [ { "name": "config", "value": "Debug" } ], not [ { "config": "Debug" } ].

Example:

{
   "name": "C++ Launch",
   "type": "cppdbg",
   "request": "launch",
   "program": "${workspaceFolder}/a.out",
   "args": ["arg1", "arg2"],
   "environment": [{"name": "config", "value": "Debug"}],
   "cwd": "${workspaceFolder}"
}

Indicates the debugger that will connect to. Must be set to gdb or lldb. This is pre-configured on a per-operating system basis and can be changed as needed.

The path to the debugger (such as gdb). When only the executable is specified, it will search the operating system's PATH variable for a debugger (GDB on Linux and Windows, LLDB on OS X).

Additional arguments to pass to the debugger (such as gdb). For example: specify the code path "miDebuggerArgs": "--directory=${workspaceRoot}/xxx".

If set to true, the debugger should stop at the entry-point of the target (ignored on attach). Default value is false.

If set to true, the debugger should stop after connecting to the target. If set to false, the debugger will continue after connecting. Default value is false.

JSON array of commands to execute in order to set up the GDB or LLDB. Example: "setupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }].

If provided, this replaces the default commands used to launch a target with some other commands. For example, this can be "-target-attach" in order to attach to a target process. An empty command list replaces the launch commands with nothing, which can be useful if the debugger is being provided launch options as command-line options. Example: "customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }].

The command to execute after the debugger is fully set up in order to cause the target process to run. Allowed values are "exec-run", "exec-continue", "None". The default value is "exec-run".

Example:

{
   "name": "C++ Launch",
   "type": "cppdbg",
   "request": "launch",
   "program": "${workspaceFolder}/a.out",
   "stopAtEntry": false,
   "customLaunchSetupCommands": [
      { "text": "target-run", "description": "run target", "ignoreFailures": false }
   ],
   "launchCompleteCommand": "exec-run",
   "linux": {
      "MIMode": "gdb",
      "miDebuggerPath": "/usr/bin/gdb"
   },
   "osx": {
      "MIMode": "lldb"
   },
   "windows": {
      "MIMode": "gdb",
      "miDebuggerPath": "C:\\MinGw\\bin\\gdb.exe"
   }
}

• loadAll: If true, symbols for all libs will be loaded, otherwise no solib symbols will be loaded. Modified by ExceptionList. Default value is true.
• exceptionList: List of filenames (wildcards allowed) separated by semicolons ;. Modifies behavior of LoadAll. If LoadAll is true then don't load symbols for libs that match any name in the list. Otherwise only load symbols for libs that match. Example: "foo.so;bar.so"

If you want to debug a Windows dump file, set this to the path to the dump file to start debugging in the launch configuration.

Full path to a core dump file to debug for the specified program. Set this to the path to the core dump file to start debugging in the launch configuration. Note: core dump debugging is not supported with MinGw.

Network address of the debugger server (for example, gdbserver) to connect to for remote debugging (example: localhost:1234).

Example Configuration

{
     "name": "gdb remote debug",
     "type": "cppdbg",
     "request": "launch",
     "program": "${workspaceFolder}/a.out",
     "args": [],
     "stopAtEntry": true,
     "cwd": "${workspaceFolder}",
     "environment": [],
     "externalConsole": false,
     "miDebuggerServerAddress": "localhost:1234",
     "MIMode": "gdb",
     "setupCommands": [
         {
             "description": "为 gdb 启用整齐打印",
             "text": "-enable-pretty-printing",
             "ignoreFailures": true
         }
     ]
}

Full path to debug server to launch.

Arguments for the debugger server.

Server-started pattern to look for in the debug server output. Regular expressions are supported.

If set to true, search stdout stream for server-started pattern and log stdout to debug output. Default value is true.

If set to true, search stderr stream for server-started pattern and log stderr to debug output. Default value is false.

Time in milliseconds, for the debugger to wait for the debugServer to start up. Default is 10000.

For information about attaching to a remote process, such as debugging a process in a Docker container, see the Pipe transport settings article.

If provided, this explicitly controls hardware breakpoint behavior for remote targets. If require is set to true, always use hardware breakpoints. Default value is false. limit is an optional limit on the number of available hardware breakpoints to use which is only enforced when require is true and limit is greater than 0. Defaults value is 0. Example: "hardwareBreakpoints": { require: true, limit: 6 }.

Defaults to ${command:pickProcess} which will display a list of available processes the debugger can attach to. We recommend that you leave this default, but the property can be explicitly set to a specific process ID for the debugger to attach to.

Indicates whether the configuration section is intended to launch the program or attach to an already running instance.

Deprecated, This option is no longer needed as the target architecture is automatically detected.

Indicates the underlying debugger being used. Must be cppdbg。

This allows mapping of the compile-time paths for source to local source locations. It is an object of key/value pairs and will resolve the first string-matched path. (example: "sourceFileMap": { "/mnt/c": "c:\\" } will map any path returned by the debugger that begins with /mnt/c and convert it to c:\\. You can have multiple mappings in the object but they will be handled in the order provided.)