Environment Variables

RTK environment variables for build scripts, debug servers, and Cortex-Debug

Overview

Oberon RTK uses environment variables prefixed with RTK_ to configure paths to external tools, debug adapters, and resources inside the framework's source tree. There are three layers of usage:

Getting started – no env vars needed. A first-time user can build a program with the Astrobe IDE, drag-drop the resulting UF2 file to a Raspberry Pi Pico (or use the vendor flasher for STM32), and observe the running program via serial. None of the RTK_* variables are required for this path.

Build scripts. Programs that involve a multi-step build chain – notably S/NS programs, where sec-epilogue, gen-secure, and the two-pass S compile go beyond what the Astrobe IDE alone drives – are built from the command line via the framework's build scripts. The build-script subset of the env vars (RTK_REPO_ROOT, RTK_ASTROBE_*, RTK_ARM_ATTR_CFG) is required at this layer. Programs are still flashed and observed via serial at this stage; the debugger toolchain is not yet involved.

With debugging. Adding a debugger – manual GDB, OpenOCD via the framework's server scripts, or Cortex-Debug in VS Code – pulls in the rest of the variables: GDB and objdump paths, OpenOCD servers and their scripts directories, and SVD files for the target MCU(s). See Your First Debug Session for the steps to bring this layer up.

Set-up is automated by the framework's set-up scripts:

Windows: <repo>/tools/setup/set-rtk-env.cmd – uses setx to persist the values to the user's Windows environment, so they are visible across cmd sessions, VS Code, and any tool launched from the Start menu.
macOS or Git Bash: <repo>/tools/setup/set-rtk-env.sh – sourced from ~/.bashrc (or ~/.zshrc on macOS zsh) so the values are exported in every interactive shell.

Both scripts ship with example values from one development set-up – the user must edit them to match their installation. The scripts also document the inheritance rules (which processes pick up the values when) and the subsets of variables needed for each scenario (RP-only debug, STM32 instead of or alongside RP, bash builds on macOS, etc.).

The reference below describes each variable's meaning. Example values are omitted – consult the set-up script for working examples.

Repo Location

RTK_REPO_ROOT: Absolute path to the user's checkout of the oberon-rtk repo. Lets build scripts and debug-server scripts compose paths to in-repo resources (config/, lib/, tools/..., targets/svd/, targets/arm/...) without hardcoding install locations. Required by the build scripts and by everything that derives from it (SVD files, ARM ELF attribute config).

Platform Run-time Prefix

RTK_EXERUN

Prefix used by bash build scripts to wrap Windows .exe invocations so the same script content runs on both platforms:

${RTK_EXERUN} "${RTK_ASTROBE_BUILD_2350}" ...

On Windows: empty (bash drops the prefix during word- splitting; the .exe runs directly via Git Bash). On macOS: mono (the .exe runs under the Mono framework). See Astrobe on macOS for Mono set-up.

Astrobe Products

The _2350 / _2040 suffix denotes the Astrobe product name, not the target MCU:

Astrobe for RP2350 (the M33 product) – builds for RP2350 and STM32 M33 boards.
Astrobe for RP2040 (the M0+ product) – builds for RP2040.

Two products imply two parallel sets of variables.

RTK_ASTROBE_BUILD_2350: Path to AstrobeBuild.exe from the Astrobe for RP2350 product. Used by build scripts for RP2350 and STM32 builds.
RTK_ASTROBE_LINK_2350: Path to AstrobeLink.exe from the same product.
RTK_ASTROBE_FOLDER_2350: Value passed to AstrobeBuild as the substitution base for %AstrobeRP2350% tokens in .ini library search paths.
RTK_ASTROBE_BUILD_2040: Path to AstrobeBuild.exe from the Astrobe for RP2040 product. Used by build scripts for RP2040 builds.
RTK_ASTROBE_LINK_2040: Path to AstrobeLink.exe from the same product.
RTK_ASTROBE_FOLDER_2040: Substitution base for %AstrobeRP2040% tokens in .ini library search paths.

ARM Toolchain (xPack arm-none-eabi-gcc)

RTK_GDB: Path to the Python-enabled GDB executable (arm-none-eabi-gdb-py3). Used by Cortex-Debug and by manual GDB sessions.
RTK_OBJDUMP: Path to arm-none-eabi-objdump. Used by Cortex-Debug to read symbol information.
RTK_READELF: Path to arm-none-eabi-readelf. 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.

OpenOCD Servers

Three OpenOCD variants are needed across the supported targets, each from a different source.

RTK_OPENOCD_XPACK: Path to the xPack OpenOCD executable. Used for STM32U585 (ST-LINK and J-Link probes; xPack supports both).
RTK_OPENOCD_RPI: Path to the Raspberry Pi fork of OpenOCD. Required for RP2040 and RP2350 because the RPi fork includes the relevant target configurations.
RTK_OPENOCD_STM: Path to the ST fork of OpenOCD (bundled with STM32CubeIDE). Required for STM32H573 because xPack OpenOCD lacks the stm32h5x.cfg target configuration.
RTK_OPENOCD_RPI_SCRIPTS: Path to the Raspberry Pi OpenOCD scripts directory (passed to the RPi-fork OpenOCD via -s).
RTK_OPENOCD_STM_SCRIPTS: Path to the ST OpenOCD scripts directory (st_scripts, passed to the ST-fork OpenOCD via -s). Includes the stlink-dap interface configuration used for STM32H573 ST-LINK debugging.

SVD Files

The SVD (System View Description) files live in the framework repo at <repo>/targets/svd/; the set-up script derives all four variables from RTK_REPO_ROOT.

RTK_SVD_RP2040: Path to the SVD file for RP2040.
RTK_SVD_RP2350: Path to the SVD file for RP2350.
RTK_SVD_STM32U585: Path to the SVD file for STM32U585.
RTK_SVD_STM32H573: Path to the SVD file for STM32H573.

Used by Cortex-Debug's register viewer to provide peripheral-register definitions.

ARM ELF Attribute Configuration

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. The file lives in the framework repo at <repo>/targets/arm/arm-elf-attr.cfg; the set-up script derives this from RTK_REPO_ROOT.

RP2040 Stage-2 Boot Loader

RTK_BOOT2: Path to the RP2040 second-stage boot loader binary (boot2.bin, exactly 256 bytes). Read by make-elf when --boot2 is given on the command line; there is no command-line override. The framework distributes a pre-compiled boot2.bin at <repo>/tools/boot2/boot2.bin; the set-up script derives this from RTK_REPO_ROOT. See make-elf for the --boot2 option semantics.

GDB Host

RTK_GDB_HOST

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

Cortex-Debug does NOT consult this variable – its GDB-server connection is configured per-project in launch.json (gdbTarget, etc.).

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. Not RTK_-prefixed because it changes with every test run.
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.

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)