debugger.md

Debugger

ecode implements the Debug Adapter Protocol (DAP) for debugger support. This enables seamless debugging integration with various languages through a common protocol. DAP is used by VS Code and other major editors and has been implemented for a wide range of programming languages. For more information, see the list of implementations.

Initially, ecode provides support for some of the most common debug adapter implementations, with plans to add support for more languages in future updates.

How It Works

There are two ways to use the debugger in ecode:

1. Using Default ecode Configurations: These configurations are designed to work seamlessly with your build settings. The executable used in these default options is the Run Target of your currently selected Build Configuration.

2. Using Custom Launch Configurations: Users can provide custom launch configurations within the project folder. These configurations should be located at .ecode/launch.json or .vscode/launch.json. ecode uses the same launch.json format as VS Code, ensuring compatibility for users migrating from other DAP-based editors. However, ecode will only recognize currently supported debuggers, as DAP implementations can vary significantly in configuration details.

Using ecode Default Configurations

Once you have a Build Configuration with a selected Run Target, this will be used for the default Launch and Attach configurations for your language.

• Launch Configurations: These configurations start an executable from your local environment, with the process managed by the debugger. This is the most common setup for most users. To use it:

  • Ensure your Run Target is ready.
  • Go to the Debugger tab in the Side Panel.
  • Select the debugger based on the language you want to debug. For example, C or C++ binaries can be debugged using gdb or lldb-dap (also known as lldb-vscode), depending on your platform.
  • Choose the appropriate Debugger Configuration, such as Launch Binary.
  • Click Debug or press Ctrl/Cmd + F5 to start debugging.

• Attach Configurations: These configurations allow the debugger to attach to an already running process, either locally or remotely. You can attach to a process via its process ID or its binary name/path. Some configurations include a (wait) option, which waits for the process to start before attaching.

  The default Attach to Binary option will also use the current Run Target to execute the binary. Unlike the Launch configuration, here the process is managed by ecode instead of the debugger. This feature is particularly useful for debugging CLI programs from the terminal if the Run Target is configured with Run in Terminal.

Using Custom Launch Configurations

ecode supports custom launch configurations through the launch.json file, which can be placed in either the .ecode/ or .vscode/ folder within your project directory. This format is fully compatible with VS Code, making it easy for users transitioning from other editors.

Creating a launch.json File

The launch.json file defines how debugging sessions are launched or attached. A basic configuration looks like this:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Program",
      "type": "lldb",
      "request": "launch",
      "program": "${workspaceFolder}/bin/myapp",
      "args": ["--verbose"],
      "cwd": "${workspaceFolder}",
      "stopOnEntry": false
    }
  ]
}

Key Fields Explained

• name: The display name for the configuration in the ecode debugger interface.
• type: The debugger type, such as gdb, lldb, or any supported DAP adapter.
• request: Specifies whether to launch a new process or attach to an existing one.
• program: The path to the executable you want to debug.
• args: Optional. Command-line arguments passed to the program.
• cwd: The working directory for the program.
• stopOnEntry: Optional. If true, the debugger will pause at the program's entry point.

Advanced Customization

You can create multiple configurations for different scenarios, such as:

• Attaching to a remote process:

{
  "name": "Attach to Remote",
  "type": "gdb",
  "request": "attach",
  "host": "192.168.1.100",
  "port": 1234
}

• Debugging with environment variables:

{
  "name": "Launch with Env Vars",
  "type": "lldb",
  "request": "launch",
  "program": "${workspaceFolder}/bin/myapp",
  "env": {
    "DEBUG": "1",
    "LOG_LEVEL": "verbose"
  }
}

ecode will automatically detect and load configurations from launch.json, prioritizing .ecode/launch.json if both are present. This approach ensures flexibility and consistency across projects, whether you're starting fresh or migrating from VS Code.

ecode supports the same launch.json schema as VS Code, including standard input types such as:

• pickProcess: Prompts the user to select a running process from a list. This is useful for attaching the debugger to an already running application.
• pickString: Allows the user to select from a predefined list of string options.
• promptString: Prompts the user to manually enter a string value, useful for dynamic input during debugging sessions.

In addition to these standard inputs, ecode extends functionality with an extra input type:

• pickFile: This ecode-specific input allows users to select a binary file directly from the file system. It is particularly useful when you need to choose an executable to be run and debugged without hardcoding the path in your launch.json.

These input options make custom configurations flexible and dynamic, adapting to different debugging workflows and environments.

Variables Reference

ecode supports all vscode variable substitution in debugger configuration files. Variable substitution is supported inside some key and value strings in launch.json files using ${variableName} syntax.

Predefined variables

The following predefined variables are supported:

• ${userHome} - the path of the user's home folder
• ${workspaceFolder} - the path of the folder opened in VS Code
• ${workspaceFolderBasename} - the name of the folder opened in VS Code without any slashes (/)
• ${file} - the current opened file
• ${fileWorkspaceFolder} - the current opened file's workspace folder
• ${relativeFile} - the current opened file relative to workspaceFolder
• ${relativeFileDirname} - the current opened file's dirname relative to workspaceFolder
• ${fileBasename} - the current opened file's basename
• ${fileBasenameNoExtension} - the current opened file's basename with no file extension
• ${fileExtname} - the current opened file's extension
• ${fileDirname} - the current opened file's folder path
• ${fileDirnameBasename} - the current opened file's folder name
• ${cwd} - the task runner's current working directory upon the startup of VS Code
• ${lineNumber} - the current selected line number in the active file
• ${selectedText} - the current selected text in the active file
• ${execPath} - the path to the running VS Code executable
• ${defaultBuildTask} - the name of the default build task
• ${pathSeparator} - the character used by the operating system to separate components in file paths
• ${/} - shorthand for ${pathSeparator}

Language-Specific Configurations

In addition to general configurations, ecode offers language-specific settings, such as loading core dumps. Each debugger and language may provide different configurations based on the debugger's capabilities and the language's characteristics.

Debugger keybindings object keys

• debugger-breakpoint-enable-toggle: Toggles enable/disable current line breakpoint (if any)
• debugger-breakpoint-toggle: Toggles breakpoint in current line
• debugger-continue-interrupt: If debugger is running: continues or interrupt the current execution. If debugger is not running builds and run the debugger.
• debugger-start: Starts the debugger
• debugger-start-stop: Starts or stops the debugger (depending on its current status)
• debugger-step-into: Steps into the current debugged line
• debugger-step-out: Steps out the current debugged line
• debugger-step-over: Steps over the current debugged line
• debugger-stop: Stops the debugger
• toggle-status-app-debugger: Opens/hides the debugger status bar panel

Debugger config object keys

• fetch_globals: Enable/Disable if global variables should be fetched automatically (when available)
• fetch_registers: Enable/Disable if registers should be fetched automatically (when available)
• silent: Enable/Disable non-critical Debugger logs