piodebuggdb

View documentation for the original command

$ tldr pio debug

piodebuggdb [options]

--project-dir
    Specify the project directory. Defaults to the current working directory.

--environment
    Specify the environment to use. If not provided, PlatformIO will attempt to use the default environment. Use `pio env list` to show all available environments.

--interface
    Specify the debugging interface (e.g., 'jlink', 'stlink', 'cmsis-dap').

--device
    Specify the target device. This is crucial for correctly configuring GDB for the target architecture.

--program
    Specify the path to the program to be debugged. This is typically the compiled firmware file (e.g., .elf).

--gdb-path
    Specify the path to the GDB executable. Use if you don't want to use system GDB.

--verbose
    Enable verbose output.

--help
    Show help message and exit.

The `piodebuggdb` command provides a GDB (GNU Debugger) interface specifically tailored for debugging PlatformIO projects. It acts as a bridge, simplifying the process of connecting GDB to your embedded projects built with PlatformIO. This allows developers to step through code, inspect variables, set breakpoints, and perform other debugging operations directly within the GDB environment, leveraging PlatformIO's build and project management capabilities.

The primary function is to configure and launch GDB with the necessary settings and commands to interact with the target device (e.g., a microcontroller) based on the PlatformIO project configuration. This includes specifying the communication interface (e.g., JTAG, Serial), the target architecture, and the program to be debugged. It streamlines the debugging workflow, eliminating the need for manual GDB configuration and ensuring compatibility with PlatformIO project structures.

The typical workflow involves building your PlatformIO project, then using `piodebuggdb` to launch GDB with the correct configurations. From within GDB, you can then use standard GDB commands to set breakpoints, step through code, inspect variables, and perform other debugging tasks.

The `piodebuggdb` command abstracts away the complexity of manually configuring GDB for embedded development, making it easier to get started with debugging your PlatformIO projects.

Most settings are inferred from the platformio.ini file within the PlatformIO project. You can often omit explicit command-line parameters if your platformio.ini is configured correctly. For example, the `debug_tool` and `debug_port` options in platformio.ini can significantly impact how `piodebuggdb` configures the debugging session.

gdb(1)