Installation and setup (Rust)

This chapter discusses how to add v5gdb to your existing Rust project, assuming you use the vexide runtime.

Important

v5gdb is compatible with vexide v0.9.0-alpha.1 or later.

Project setup

Start by adding v5gdb to your project.

cargo add v5gdb

To enable debugging support, add the following line somewhere in your program, preferably near the beginning.

use v5gdb::{debugger::V5Debugger, transport::StdioTransport};

#[vexide::main]
async fn main(peripherals: Peripherals) {
    v5gdb::install(V5Debugger::new(StdioTransport::new()));
    
    // ...rest...
}

If you've enabled Link Time Optimization for the build profile you plan to debug in, you will need to disable it. v5gdb does not support debugging programs that have LTO enabled.

Debugger setup

You'll need to install some system dependencies.

Platform	Command
macOS	brew install gdb
Ubuntu	apt install gdb-multiarch gcc pkg-config libudev-dev
Fedora	dnf install gdb gcc systemd-devel
Windows, via msys2	pacman -S mingw-w64-ucrt-x86_64-gdb
(Other)	Let us know what works for you

Additionally, install the v5gdb command line interface. This is a support program that helps GDB connect to your VEX V5 brain.

cargo install --git https://github.com/vexide/v5gdb v5gdb-cli

Usage

To enter the debug console, place a manual breakpoint somewhere in your code. This is the only breakpoint you will have to place at build-time.

use v5gdb::{debugger::V5Debugger, transport::StdioTransport};

#[vexide::main]
async fn main(peripherals: Peripherals) {
    v5gdb::install(V5Debugger::new(StdioTransport::new()));
    
    // ...setup...

    v5gdb::breakpoint!();

   // ...rest...
}

Upload your program (avoid using --release when debugging):

cargo v5 upload

When your program reaches the breakpoint, it will pause execution. At this point, you can now view the debug console by running the v5gdb command in your terminal.

You will need to specify the path name of the executable ELF file you are running on the V5. Generally, this path is of the form:

• ./target/armv7a-vex-v5/debug/[PROGRAM_NAME]

$ v5gdb ./target/armv7a-vex-v5/debug/my_program

GNU gdb (GDB) 16.3
Copyright (C) 2024 Free Software Foundation, Inc.
Reading symbols from ./target/armv7a-vex-v5/debug/my_program...
Remote debugging using :35537
0x0380b240 in basic::main::main::{async_fn#0} () at examples/basic.rs:26
26          v5gdb::breakpoint!();
(gdb)

Tip

You cannot run v5gdb at the same time as commands like pros, cargo v5, or vexcom.

Considerations

If you try to debug a program that was built with the "release" profile, you might find it act more unpredictably because of the optimizations made by the compiler. Additionally, if you have LTO enabled, you may find that v5gdb has trouble hooking into certain events like program exits and prints. To avoid these issues, we recommend debugging programs built in the "dev" profile without optimizations turned on.

If your uploads are taking too long or failing intermittently, it's acceptable to enable optimizations for your dependencies to reduce the size of your executable:

[profile.dev.package."*"]
opt-level = "z"