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 currently only compatible with the main branch of vexide, which has some unreleased bug fixes. Use the following dependency spec in Cargo.toml.

[dependencies.vexide]
version = "0.8.0"
branch = "main"
git = "https://github.com/vexide/vexide.git"

Project setup

Start by adding v5gdb to your project.

cargo add --git https://github.com/vexide/v5gdb 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...
}

It's okay to install a debugger even if you aren't sure whether you'll be using v5gdb - the debugger's features only activate when you first hit a breakpoint.

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 unpredictable 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"