Running the Python Tools

How to run the Python programs in the tools directory

How to run the Python programs in the tools/ directory. All tools use the Python standard library only – no external packages are needed.

The Practical Problem

The tools live in tools/, but you run them from your project directory where the build output is. A command like this will not work:

cd tools
python make-elf.py SignalSync.bin:10000100 --debug

Python finds make-elf.py, but SignalSync.bin is back in the project directory. You would need the full path to the binary, which is somewhat clumsy and cumbersome.

In practice, you are in the project directory (eg. examples/v3.0/stm/u585i-iot/SignalSync/) and all file references on the command line are relative to that directory.

Recommended: PYTHONPATH + Module Mode

Set PYTHONPATH to include the tools/ directory, then use python -m to run tools by module name. This way, all file arguments stay relative to the project directory.

Setting PYTHONPATH

Windows (cmd):

set PYTHONPATH=C:\path\to\oberon-rtk\tools

Windows (PowerShell):

$env:PYTHONPATH = "C:\path\to\oberon-rtk\tools"

macOS (bash/zsh):

export PYTHONPATH=/path/to/oberon-rtk/tools

These commands set the variable for the current terminal session only.

To make PYTHONPATH permanent on Windows, open Settings > System > About > Advanced system settings > Environment Variables and add a new user variable named PYTHONPATH with the path to tools/ as its value. New terminal windows will pick it up automatically.

On macOS, add the export line to ~/.zshrc (or ~/.bash_profile).

Running a Tool

With PYTHONPATH set, run from the project directory:

python -m make-elf SignalSync.bin:10000100 --debug --bss 20000000:20040000

Python's -m flag finds make-elf.py on PYTHONPATH and runs it. File arguments (SignalSync.bin, etc.) resolve relative to your current directory as expected. Module imports (eg. make-elf importing elfdata) also resolve via PYTHONPATH.

Other tools work the same way:

python -m gen-rdb SignalSync.map

Alternative: Explicit Path

If you prefer not to set PYTHONPATH, give the full path to the tool:

python C:\path\to\oberon-rtk\tools\make-elf.py SignalSync.bin:10000100 --debug

This works because each tool that imports a library module (such as make-elf.py importing elfdata from tools/pylib/) adds the library path to sys.path internally. No additional configuration is needed.

Module Imports Between Tools

Some tools import library modules from tools/pylib/:

Tool	Imports
`make-elf.py`	`elfdata` (from `pylib/`)
`check-elf.py`	`elfdata` (from `pylib/`)

Each tool adds pylib/ to sys.path internally, so imports work regardless of how the tool is invoked (PYTHONPATH, explicit path, or python -m).

GDB and Python (Test Engine)

gdbtestengine.py runs inside GDB's embedded Python interpreter, not as a standalone script. This requires the Python-enabled GDB build:

arm-none-eabi-gdb-py3

The plain arm-none-eabi-gdb (without -py3) does not include Python and cannot run the test engine.

gdbtestengine (Code Tests)

The code test engine is loaded via GDB's source command. A typical ~/.gdbinit defines an alias:

define run-test
  source /path/to/tools/pylib/gdbtestengine.py
end

Usage (interactive):

(gdb) set environment SPEC compare-test.spec
(gdb) run-test

Usage (batch):

arm-none-eabi-gdb-py3 -batch \
  -ex "set environment SPEC compare-test.spec" \
  -ex "run-test"

The engine reads the SPEC environment variable to find the test specification file. Other environment variables:

Variable	Default	Purpose
`SPEC`	(required)	Spec file name (resolved relative to `RTK_GDB_TESTS_SPECS_DIR`)
`RTK_GDB_TESTS_SPECS_DIR`	`rdb-gdb-tests/specs`	Directory containing spec files
`RTK_PROJECT_DIR`	current directory	Project root
`RTK_REPORTS_DIR`	`reports/` next to spec	Report output directory

These can be set with (gdb) set environment or as OS environment variables. The engine checks both. See Environment Variables.

Common Pitfalls

ModuleNotFoundError: No module named 'make-elf' (or similar): You are using python -m without PYTHONPATH set. Set PYTHONPATH to include the tools/ directory as described above, or use an explicit path instead.
python command not found: Try python3 (common on macOS and some Linux distributions).
Wrong Python version (2.x): Ensure python resolves to Python 3.9 or later. Run python --version to check.
No module named 'gdb': You ran a test engine script with standalone Python instead of under GDB. Use arm-none-eabi-gdb-py3 -batch -x script.py, not python script.py.
GDB prints Python scripting is not supported: You are using arm-none-eabi-gdb instead of arm-none-eabi-gdb-py3. Switch to the -py3 variant.