Installation and setup (Cpp)

This chapter discusses how to add v5gdb to a C++ project using PROS.

Caution

By default, PROS uses the .bss section as the stack. This will corrupt v5gdb's memory. Until they fix this, you must edit the PROS linker script to set a dedicated stack.

Append the following code to the v5.ld file in your PROS project before using v5gdb:

SECTIONS {
    .stack (NOLOAD) : {
       . = ALIGN(16);
       __stack_start = .;
       . = ORIGIN(HEAP);
       __stack = .;
       __stack_end = .;
    } > RAM
} INSERT AFTER .bss;

Installing v5gdb

You will need to separately compile the v5gdb command line tool before you can use it in your C++ project. v5gdb is a Rust project, so you'll need to install Rust as well as these system dependencies:

Platform	What to install
macOS	Install Rust and xcode-select --install
Ubuntu	Install Rust and apt install gcc pkg-config libudev-dev
Fedora	Install Rust and dnf install gcc systemd-devel
Windows	Install Rust and Visual Studio
(Other)	Let us know what works for you

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

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

Next, add the v5gdb library to your PROS project by running these commands:

pros c add-depot v5gdb https://raw.githubusercontent.com/vexide/v5gdb/depot/preview.json
pros c apply v5gdb

Project setup

To enable debugging support, add the following lines to your initialize function, preferably near the beginning

#include "v5gdb/v5gdb.h"

void initialize() {
    v5gdb::install();
    // ...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.

Debugger setup

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

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.

#include "v5gdb/v5gdb.h"

void initialize() {
    v5gdb::install();

    // ...setup...

    v5gdb::breakpoint();

    // ...rest...
}

Upload your program:

pros mu

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.

$ v5gdb

GNU gdb (GDB) 16.3
Copyright (C) 2024 Free Software Foundation, Inc.
Reading symbols from ./bin/hot.package.elf...
add symbol table from file "./bin/cold.package.elf"
Reading symbols from ./bin/cold.package.elf...
Remote debugging using :35537
initialize () at src/main.cpp:19
19              printf("Hello world\n");
(gdb)

You may now use GDB to debug your program: for instance, type "continue" to resume execution, or press Ctrl-C to pause the program.

Tip

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