runner.introduction

The gdb-runner is a tool that automates the execution of gdb, utilizing plugins in order to implement breakpoints.

The main target for this tool is the usage on embedded systems without an operating system. We provide several libraries for testing and analyzation.

• Automate testing on embedded Systems
• Unintrusive monitoring and modifying
• Extension facilities
• Launch gdb-server in the same command

Example

As an example (The ^ is a linebreak in the command), we take a given arm elf with openocd through the dbg-runner, using our exit-code and newlib plugins.

metal.runner --gdb=arm-none-eabi-gdb --exe=arm-test.elf --lib metal-newlib-syscalls metal-exitcode ^
    --remote localhost:3333 --init-script openocd --other "openocd -f interface/stlink-v2.cfg -f target/stm32f4x.cfg -c init"

Now let's consider your code uses our [link dbg-runner.plugins.newlib newlib syscall] code and the main function of arm-test.elf looks like this:

#include <fstream>
#include <iostream>

int main(int argc, char * argv[])
{
    std::ofstream fs{"test-file.out"};
    
    fs << "my test string" << std::endl;
    
    std::cout << "Hello world!" << std::endl;    
    
    return 42;
}

The command given above will work as if the program was executed on the host machine, i.e. it will create a file test-file.out which contains "my test string", print out "Hello world!" to the console and will yield the exit code 42.

How to read this documentation

If you want to use this tool, see the sections Invocation and Plugins. The other sections are relevant for the development of custom plugins, which is explained in the Extension Manual