Skip to content

Installation and setup (Rust)

Jump to bottom
Lewis McClelland edited this page Oct 25, 2026 · 8 revisions

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::prelude::*;

#[vexide::main]
async fn main(peripherals: Peripherals) {
    v5gdb::install(V5Debugger::stdio());

    // ...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

Please install GDB using one of the following commands:

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

You will also need to install the v5gdb command on your computer using one of the commands below. This is a support program that helps GDB running on your computer connect to your VEX V5 brain.

Shell script (macOS/Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/vexide/v5gdb/releases/download/v0.1.0-beta.1/v5gdb-cli-installer.sh | sh

PowerShell script (Windows)

powershell -ExecutionPolicy Bypass -c "irm https://github.com/vexide/v5gdb/releases/download/v0.1.0-beta.1/v5gdb-cli-installer.ps1 | iex"

Other

  • Cargo: cargo install v5gdb-cli@0.1.0-beta.1
  • Cargo Binstall: cargo binstall v5gdb-cli@0.1.0-beta.1
  • View the Releases page for detailed install instructions and manual downloads.

Usage

Upload your program, then start it. Avoid using --release when debugging.

cargo v5 upload

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, consider enabling optimizations for your dependencies to reduce the size of your executable:

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

Clone this wiki locally