diff --git a/launch.md b/launch.md new file mode 100644 index 000000000..6cc42e898 --- /dev/null +++ b/launch.md @@ -0,0 +1,151 @@ +# Configuring launch.json for C/C++ debugging + +The `launch.json` file is used to configure the debugger in Visual Studio Code. + +Visual Studio Code generates a `launch.json` with almost all of the required information. To get started +debugging you need to fill in the `program` field with the path to the executable you plan to debug. This must be specified for +both the launch and attach (if you plan to attach to a running instance at any point) configurations. + +The generated file contains two sections. One that configures debugging for launch and a second that configures debugging for attach. + +# Configure VS Code's debugging behavior + +Set or change the following options to control VS Code's behavior during debugging + +**program**: `Required` Specifies the full path to executable the debugger will launch or attach to. + +**symbolSearchPath**: Tells the _Visual Studio Windows Debugger_ what paths to search for symbol (.pdb) files. Separate multiple paths with a semicolon. Example `"C:\\Symbols;C:\\SymbolDir2"` + +**additionalSOLibSearchPath**: Tells _GDB or LLDB_ what paths to search for .so files. Separate multiple paths with a semicolon. Example: `"/Users/user/dir1;/Users/user/dir2"`. + +**externalConsole**: If set to `true`, launches an external console for the application. If `false`, no console is launched and VS Code's debugging console is used. Note this option is ignored in some cases for technical reasons. + +**logging**: 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. + +**visualizerFile**: .natvis file to be used when debugging. See [Natvis syntax reference](http://aka.ms/natvis#Anchor_8) for information on how to create natvis files. + +**Example:** + +```json +{ + "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": "${workspaceRoot}/my.natvis" +} +``` + + +# Configure the target application + +The following options enable you to modify the state of the target application when it is launched + +**args**: JSON array of command line arguments to pass to the program when it is launched. Example `["arg1", "arg2]`. + +**cwd**: Sets the the working directory of the application launched by the debugger. + +**environment**: Environment variables to add to the environment for the program. Example: `[ { "name": "squid", "value": "clam" } ]`. + +**Example:** + +```json +{ + "name": "C++ Launch", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceRoot}/a.out", + "args": ["arg1", "arg2"], + "environment": [{"name": "squid", "value": "clam"}], + "cwd": "${workspaceRoot}" +} +``` + +## Customizing GDB or LLDB + +You can change the behavior of GDB or LLDB by setting the following options. + +**MIMode**: Indicates the debugger that VS Code 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. + +**miDebuggerPath**: The path to the debugger (such as gdb). When unspecified, it will search the operating system's PATH variable for a debugger (GDB on Linux and Windows, LLDB on OS X). + +**stopAtEntry**: If set to true, the debugger should stop at the entrypoint of the target (ignored on attach). Default value is `false`. + +**setupCommands**: JSON array of commands to execute in order to setup the GDB or LLDB. Example: `"customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]`. + +**customLaunchSetupCommands**: 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 }]`. + +**launchCompleteCommand**: The command to execute after the debugger is fully setup in order to cause the target process to run. Allowed values are "exec-run", "exec-continue", "None". The default value is "exec-run". + +**Example:** + +```json +{ + "name": "C++ Launch", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceRoot}/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" + } +} +``` + +## Debugging dump files + +The C/C++ extension enables debugging dump files on Windows and core dump files Linux and OS X. + +**dumpPath**: 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. + +**coreDumpPath**: 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 debuging is not supported with MinGw._ + +## Remote debugging or debugging with a local debugger server + +**miDebuggerServerAddress**: Network address of the debugger server (e.g. gdbserver) to connect to for remote debugging (example: `localhost:1234`). + +**debugServerPath**: Full path to debug server to launch. + +**debugServerArgs**: Arguments for the the debugger server. + +**serverStarted**: Server-started pattern to look for in the debug server output. + +**serverLaunchTimeout**: Time in milliseconds, for the debugger to wait for the debugServer to start up. Default is 10000. + +## Additional properties + +**processId**: Defaults to `${command.pickProcess}` which will display a list of available processes the debugger can attach to. It is recommended to leave this default, but the property can be explicitly set to a specific process ID for the debugger to attach to. + +**request**: Indicates whether the configuration section is intended to `launch` the program or `attach` to an already running instance. + +**targetArchitecture**: `Deprecated` This option is no longer needed as the target architecture is automatically detected. + +**type**: Indicates the underlying debugger being used. Must be `cppvsdbg` when using the Visual Studio Windows debugger, and `cppdbg` when using GDB or LLDB. This is automatically set to the correct value when the +launch.json file is created. + +