runner.invocation

This section describes the usage of the metal.runner. We will assume that the command is available, though you might need to either use the absolute path or add the path to the PATH variable.

Here's an overview of all parameters:

Plugins can add other parameters.

Option	Shortcut	Description	Value type	Default
--config-file	C	Configuration file	single string	none
--dbg	G	Command for the debugger	single string	dbg
--dbg-args	U	Arguments to pass to debugger	multiple strings	none
--exe	E	The binary to run required	single string	none
--args	A	Args to pass to the process	multiple strings	none
--log	L	Generate the logfile	single string	none
--lib	P	Breakpoint plugins	multiple strings	none
--remote	R	Remote address of gdb-server	single string	none
--other	O	Other processes to launch, i.e. gdb-server	multiple strings	none
--other-log	F	Folder with the logs for other processes. If not set, the output is disregarded.	path	none
--debug	D	Enable the debug log, i.e. put the whole gdb-communication into the log	bool switch	disabled
--timeout	T	Communication Timeout [s]	single int]	10
--source-dir	S	Folder to look for sources	path	none
--init-script	I	The init script(s) for the debugger initialization	multiple paths	none
--help	H	List all parameters, including those of plugins, then do nothing	bool switch	disabled

The parameter exe is required.

You can also use stderr and stdout instead of a filename for log.

Config File

Since the call might get rather long, configuration and response files can be used. Config files are set through --config-file or -C. Configuration files have a simple format of key=value. Response files are passed as with gnu tools in the form of @response-file where response-file contains text in the same format as passed to the program.

E.g. if you have a configuration file config-file

exe=test.exe

response file response-file with the following content

--exe=test.exe

and a config file with the following

the follwing commands are equal:

metal.runner --exe=test.exe
metal.runner --config-file=config-file
metal.runner @response-file

This also works for plugin-provided commands.

Gdb call

The gbd-command can be set explicitly, if the location might need to be changed or the dbg has a prefix, as in arm-none-eabi-gdb.

If the db-command contains a string, you will need to put it in quotes.

To pass arguments directly to gdb, you can pass parameter directly to it, using --dbg-args.

note You will have to put the parameter list into quotes like `metal.runner --dbg=arm-none-eabi-gdb --dbg-args="-b 57.600"

Executable

The executable Argument is required, and does not require to be executable on the hosting machine. Additionally arguments for the main program may be passed.

metal.runner --exe=test.exe --args arg1 arg2

If you use an embedded target, the exe needs to be the elf file, not the hex. The debu symbols will not be loaded into the rom.

This argument can also be used as an positional argument, together with the gdb argument.

metal.runner gdb test.exe

Log file

The dbg-runner provides log files, which describes the inner workings of the dbg-runner. It does not give the verbatim interaction between the gdb and the runner.

metal.runner --exe=test.exe --log=logfile.txt

Debug output

The debug option will switch on the output of the verbatim interaction between the runner and the dbg process. It will be printed out to stderr. The main purpose is for debugging plugin development.

metal.runner --exe=test.exe --debug

Breakpoint Plugins

This option is used to provide plugins. It can either be the path of a plugin binary or the name of a provided one.

metal.runner --exe=test.exe --lib metal-newlib-syscalls ../bin/my-test-plugin.dll

The dbg-runner looks in it's own directory for a fitting library, and trying to put lib in front and either .dll or .so in the back. That means that exit-code will also look for libexit-code.dll or libexit-code.so

' Remote

In order to simplify remote execution the --remote property is provided, which is simply forwarded to dbg to allow remote debugging.

metal.runner --exe=test.elf --remote=127.0.0.1:3333

Other processes

In order to simplify launching of gdb servers like openocd, they can be passed via the --other option. That will cause the process to be launched before gdb and will be terminated after gdb exits.

metal.runner --exe=test.exe --other "process1 --option" "process2 --option"

Initialization Scripts

In order to properly initialize a gdb-server such as openocd a initialization script can be provided. Several of those can be passed with --init-script and will be executed in that order. The dbg-server provides some builtins, currently one for the openocd.

** If no init-script is provided the dbg-runner will just call run for a local session and continue with a remote server.**

Timeout

The timeout options allows the setting of a timeout in seconds, which's default is 10 seconds. This timeout does not affect the communication with the gdb server in remote debugging, but the maximal time between two breakpoint occurrences. It can be disable by setting it to zero.

metal.runner --exe=test.exe --timeout 20