Installation and setup (Cpp) - vexide/v5gdb GitHub Wiki

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.