RISC OS Build EnvironmentROBE

Workflow guides7Files, Directories, and Variables

Introduction and Overview

The build environment relies on predictable directory mappings and a small set of environment variables. Understanding these mappings avoids confusion about where files are stored, where outputs appear, and how extra host directories or variables can be passed into the container.

Standard mappings

Standard mapped directories

The most important built-in mappings are:

  • Source tree: host current directory or Git repository mapped to /riscos-source.
  • Built output: host built/ mapped to /riscos-built.
  • Shell startup: host ~/.config/riscos-build/bash.d mapped to ~/.bash.d.
  • User bin: host ~/.config/riscos-build/bin mapped to ~/bin.
  • Cache: host ~/.cache/riscos-build mapped to ~/.cache.

Git and user configuration mappings

The environment also maps the user's Git configuration and credentials, plus selected shell support files such as .inputrc. This preserves normal author identity and Git aliases, although not every host configuration pattern can be reproduced. Included configuration files, credential rewriting, worktrees, and submodules all have practical limits.

System Variables

Inside the container, a small set of environment variables name the standard directories described above, plus the resource tree that ships with the image itself. Scripts and ad-hoc commands can use these instead of hard-coded paths.

ROSOURCE_DIR
The in-container path of the mapped source tree

Always set to /riscos-source, the mapped source tree described under Standard mapped directories. Provided as a named variable so scripts do not need to hard-code the path.

cd $ROSOURCE_DIR

ROBUILD_DIR
The in-container path of the mapped built-output tree

Always set to /riscos-built inside the container. This is the same name used on the host side to choose which host directory is bind-mounted there; see ROBUILD_DIR in the host-variable list below. Once inside the container, the variable always reads back as the in-container mount point, regardless of which host directory was mapped.

RORESOURCES_DIR
The in-container path of the shipped toolchain and resource tree

Always set to /riscos-resources. This tree is built into the image itself, rather than mapped from the host, and holds the wrapper commands, exported headers and libraries, shared makefiles, and other resources that the environment ships with.

ROTOOL_DIR
Directory containing the host-side wrapper commands

Set to $RORESOURCES_DIR/Install/Tools/Linux. This directory is added to PATH, which is how commands such as riscos-cc and riscos-amu are found without an explicit path.

ROSYSMODULES
Directory containing the shipped RISC OS system modules

Set to $RORESOURCES_DIR/Install/Modules. This is where the standard system modules (BASIC,ffa, SCL,ffa, FPEmulator,ffa, Obey,ffa) live, and is the same directory the environment's own Pyromaniac configuration uses to load them. See Pyromaniac and runtime execution for a worked example loading a module from this directory directly with pyro.

pyro --load-internal-modules --load-module $ROSYSMODULES/BASIC,ffa --command "Basic -quit MyProgram"

ROLIBRARY
Directory containing the shipped RISC OS library utilities

Set to $RORESOURCES_DIR/Install/Library. This mirrors the RISC OS $.Library directory of general-purpose RISC OS utilities, such as ModServices, that are run inside a live RISC OS session rather than as host-side wrapper commands.

BUILD_DIR
Legacy alias for ROBUILD_DIR

Always set to the same value as ROBUILD_DIR (/riscos-built). This variable predates ROBUILD_DIR and is kept for compatibility with older scripts; new scripts should use ROBUILD_DIR instead.

Startup controls

ROBUILD host variables

Host-side variables that commonly affect startup are:

  • ROBUILD_DOCKER_VERSION, ROBUILD_DOCKER_IMAGE, and ROBUILD_DOCKER_REGISTRY for image selection;
  • ROBUILD_DIRVARS and ROBUILD_DIRBINDS for extra directory mappings;
  • ROBUILD_DIR to choose which host directory is mapped as /riscos-built, useful when several projects should share one export area;
  • ROBUILD_VARS for copying additional variables into the environment;
  • ROBUILD_EDITOR to control the editor used by host-edit;
  • ROBUILD_VNC when VNC availability matters for Pyromaniac sessions (Pyromaniac and VNC are explained in Pyromaniac and runtime execution, Part 3).

To pass a simple host variable through into the environment: 

export ROBUILD_VARS="ENABLE_TESTS=1"

riscos-shell

echo $ENABLE_TESTS

1

Run the export and riscos-shell lines on the host, before entering the container; the echo line is then run inside the resulting shell to confirm the variable arrived. ROBUILD_VARS also accepts a bare variable name, such as ROBUILD_VARS=ENABLE_TESTS, to copy the host's current value of that variable rather than setting a new one.

Additional directory mappings

Two mechanisms are available for custom directory mapping.

  • ROBUILD_DIRBINDS takes explicit host-path=environment-path pairs.
  • ROBUILD_DIRVARS names variables whose values should be mapped in, or gives explicit VAR=host-path assignments.

If the mapping should be shared in a project without setting shell variables manually, a .rodirs file may be used instead.

An explicit extra bind mount looks like this: 

export ROBUILD_DIRBINDS=$PWD/mylibs/newlib=/mylibs/newlib

riscos-shell

ls /mylibs/newlib

As with ROBUILD_VARS, run the export and riscos-shell lines on the host; the ls line is then run inside the container to confirm the extra directory is mounted and visible. ROBUILD_DIRBINDS mappings must use the exact form <host-path>=<guest-path>; an entry without the = separator is rejected with Bind mappings in ROBUILD_DIRBINDS must be in the form <host-path>=<guest-path>.

Runtime variables and diagnostics

Environment variables inside the container

Once inside the environment, variables such as ROBUILD_DOCKER_VERSION, ROBUILD_PROJECT, ROBUILD_HOST_NAME, and ROBUILD_HOST_PATH describe the running context. If VNC is available, the shell also exposes ports through variables such as ROBUILD_VNC_PORT and ROBUILD_NOVNC_PORT.

A further group of in-container variables support the host-bridge and AI agent mechanisms:

  • ROBUILD_CONTROL_PORT is the port the host-bridge commands (host-open, host-edit, host-run, and host-copy) connect to on host.docker.internal to ask the host to act on their behalf. Together with ROBUILD_HOST_PATH, this is what makes those commands work; either being unset disables them.
  • ROBUILD_OAUTH_PORT is a port mapped through for OAuth authentication flows used by some AI agent wrappers.
  • ROBUILD_MAPPED lists every host directory that was bind-mounted into the container for this session, as space-separated host-path:container-path entries, which is useful when diagnosing whether an expected directory mapping actually took effect.

Transformation diagnostics

When filename translation or wrapper path handling fails, the variables ROBUILD_TRANSFORMCLI_CLEAN and ROBUILD_TRANSFORMCLI_DEBUG control cleanup and debug tracing for the transform layer. These are diagnostic settings rather than part of the normal workflow.