Environment Variables

RTK environment variables for tools, debug servers, and VS Code.

Overview

Oberon RTK uses environment variables prefixed with RTK_ to configure paths to external tools, debug adapters, and support files. Setting these variables once (as permanent user environment variables) means that tool version updates require changing only the variable, not every script, configuration file, or launch configuration that references it.

On Windows, set permanent user variables via Settings > System > About > Advanced system settings > Environment Variables.

On macOS/Linux, add export lines to ~/.zshrc or ~/.bashrc.

Python Tools

RTK_ARM_ATTR_CFG

Path to the master arm-elf-attr.cfg file containing ARM ELF attribute definitions per MCU. Used by gen-rdb when --attr-cfg is not given on the command line. There is no built-in default.

Example: <path-to-repo>\oberon-rtk\targets\arm\arm-elf-attr.cfg

RTK_READELF

Path to the readelf binary. Used by check-elf when --readelf is not given on the command line. If neither is set, arm-none-eabi-readelf is searched on PATH.

Example: C:\xPack\xpack-arm-none-eabi-gcc-14.2.1-1.1\bin\arm-none-eabi-readelf.exe

RTK_GDB_HOST

GDB server host and port. Used by elftestengine (structural ELF tests) and gdbtestengine (code tests). Default: localhost:3333.

Example: localhost:3333

GDB Test Engine (gdbtestengine)

These variables are typically set via GDB's set environment command or as OS environment variables. The test engine reads both.

SPEC

Spec filename (required). Resolved relative to the specs directory. This is not an RTK-prefixed variable because it changes with every test run.

Example: halt-test.spec

RTK_PROJECT_DIR

Project root directory. Must contain rdb/, *.elf, and *.map. Default: current working directory.

RTK_GDB_TESTS_SPECS_DIR

Spec directory within the project. The spec file resolves to RTK_PROJECT_DIR / RTK_GDB_TESTS_SPECS_DIR / SPEC. Default: rdb-gdb-tests/specs.

RTK_REPORTS_DIR

Report output directory. When set, resolves to RTK_PROJECT_DIR / RTK_REPORTS_DIR. When not set, reports are written to a reports/ directory next to the specs directory.

Debug Server Scripts

Scripts in tools/scripts/ that start OpenOCD for specific target/probe combinations.

RTK_OPENOCD_XPACK

Path to the xPack OpenOCD executable. Used by STM32 server scripts (both ST-LINK and J-Link).

Example: C:\xPack\xpack-openocd-0.12.0-7\bin\openocd.exe

RTK_OPENOCD_RPI

Path to the Raspberry Pi fork of OpenOCD. Used by RP2350 server scripts (CMSIS-DAP probe). The RPi fork is required because it includes the RP2350 target configuration.

Example: C:\RPI\openocd\openocd.exe

RTK_OPENOCD_RPI_SCRIPTS

Path to the Raspberry Pi OpenOCD scripts directory. Used by RP2350 server scripts and VS Code launch configurations.

Example: C:\RPI\openocd\scripts

RTK_OPENOCD_STM

Path to the ST fork of OpenOCD (from STM32CubeIDE). Required for STM32H5 targets because xPack OpenOCD lacks the stm32h5x.cfg target configuration. Uses a different adapter driver (stlink-dap.cfg) than xPack OpenOCD (stlink-swd.cfg).

Example: C:\STM\STM32CubeIDE_2.0.0\...\tools\bin\openocd.exe

RTK_OPENOCD_STM_SCRIPTS

Path to the ST OpenOCD scripts directory (st_scripts). Used by STM32H573 server scripts and VS Code launch configurations.

Example: C:\STM\STM32CubeIDE_2.0.0\...\resources\openocd\st_scripts

RTK_OPENOCD_CFG_STLINK

Path to the OpenOCD interface configuration file for ST-LINK. Used by STM32U585 server scripts and VS Code launch configurations. Not used for STM32H573 (which uses stlink-dap.cfg from the ST scripts directory).

Example: <path-to-repo>\oberon-rtk\tools\config\OpenOCD\stlink-swd.cfg

VS Code (Cortex-Debug)

These variables are referenced in .vscode/launch.json files using the ${env:RTK_...} syntax.

RTK_GDB

Path to the Python-enabled GDB executable.

Example: C:\xPack\xpack-arm-none-eabi-gcc-14.2.1-1.1\bin\arm-none-eabi-gdb-py3.exe

RTK_OBJDUMP

Path to objdump. Used by the Cortex-Debug extension to read symbol information.

Example: C:\xPack\xpack-arm-none-eabi-gcc-14.2.1-1.1\bin\arm-none-eabi-objdump.exe

RTK_SVD_STM32U585

Path to the SVD file for STM32U585. Provides peripheral register definitions for the Cortex-Debug register viewer. Merged SVD files include PPB peripherals (NVIC, SysTick, SCB, MPU, SAU, etc.) that vendor SVDs omit.

Example: <path-to-repo>\oberon-rtk\targets\svd\STM32U585-merged.svd.xml

RTK_SVD_STM32H573

Path to the SVD file for STM32H573.

Example: <path-to-repo>\oberon-rtk\targets\svd\STM32H573-merged.svd.xml

RTK_SVD_RP2350

Path to the SVD file for RP2350.

Example: <path-to-repo>\oberon-rtk\targets\svd\rp2350-merged.svd.xml

RTK_OPENOCD_XPACK, RTK_OPENOCD_CFG_STLINK, RTK_OPENOCD_STM, RTK_OPENOCD_STM_SCRIPTS, RTK_OPENOCD_RPI, RTK_OPENOCD_RPI_SCRIPTS : Also used in launch.json for the OpenOCD server path, scripts directory, and interface configuration. See Debug Server Scripts above.

Resolution Order

For variables that can also be set via command line arguments, the resolution order is:

Command line argument (highest priority)
Environment variable
Built-in default (if any)