piodebuggdb
Debug PlatformIO projects with GDB
TLDR
View documentation for the original command
SYNOPSIS
piodebuggdb [options]
PARAMETERS
--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.
DESCRIPTION
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.
DEBUGGING WORKFLOW
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.
CONFIGURATION
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.
SEE ALSO
gdb(1)