Skip to content

Command‐line interface

Jump to bottom
Lewis McClelland edited this page Oct 13, 2026 · 5 revisions

v5gdb has a command line interface that can decode messages received from the debugger over a USB connection to your V5 brain. This CLI is intended for use with the StdioTransport; if you make a custom transport, you will have to make your own alternative.

Usage

The arguments to v5gdb are the ELF files that describe the program which is currently running on the brain. All frameworks for the VEX V5 output these files as part of their build process, but they are placed in varying locations.

For PROS programs, specifying ELF files is optional; v5gdb can usually automatically discover them.

Example usage:

# PROS
v5gdb

# PROS (with ELF files specified; optional)
v5gdb ./bin/hot.package.elf ./bin/cold.package.elf

# vexide
v5gdb ./target/armv7a-vex-v5/release/your_program_name

Command-line Options

--tcp (TCP Server mode)

By default, v5gdb CLI opens directly into the gdb command-line REPL interface. If you'd like to use a custom GDB frontend, you can disable this behavior by specifying the --tcp flag, which makes v5gdb CLI run headless (similarly to gdbserver).

v5gdb --tcp=localhost:35537

When the --tcp flag is specified, v5gdb will start a TCP server and wait for a connection on the specified address and port. You can connect to it from a GDB frontend like this:

$ gdb -ex "target remote :35537" bin/monolith.elf
Reading symbols from bin/monolith.elf...
Remote debugging using :35537
(gdb)

The above example just uses GDB like normal, but TCP Server mode can be useful for integrating v5gdb with an IDE or code editor to set up graphical debugging.

In TCP Server mode, logs and other serial output from the program you are debugging will appear under the v5gdb command instead of being interleaved with your GDB session.

--no-discover-elf (ELF auto-discovery)

By default, if no ELF files are specified on the command line, v5gdb will search common locations in PROS projects for debug info stored in ELF files, including bin/monolith.elf, bin/hot.package.elf, and bin/cold.package.elf.

You can disable this feature using the --no-discover-elf command-line flag. ELF auto-discovery is always disabled in TCP Server mode.

--user-io <mode> (User I/O packet format)

PROS adds extra COBS encoding to all data written to stdout, which can make your prints look odd when v5gdb does not recognize that it needs to decode your program's output. This flag customizes how v5gdb interprets your program's output.

Supported modes:

  • --user-io auto (default): When v5gdb is running inside a PROS project, it will apply PROS-style program output decoding.
  • --user-io pros: v5gdb will always apply PROS-style program output decoding.
  • --user-io raw: v5gdb will not apply any additional processing to program output.

--debug-io

Enables TRACE-level logging for serial operations. All decoding errors and serial I/O will be logged.

This is the same as adding v5gdb::serial=trace to the V5GDB_LOG environment variable.

Logging

You can use the V5GDB_LOG environment variable to customize logging. Format details are available here.

Example:

$ V5GDB_LOG=debug v5gdb

Clone this wiki locally