RISC OS Build EnvironmentROBE

Introduction1Introduction to the RISC OS Build Environment

Introduction and Overview

The RISC OS Build Environment is a Docker-based development environment for building RISC OS software from Linux, macOS, Windows, and WSL2 host systems. It packages the Norcroft toolchain, wrapper commands, help files, and optional subsystems so that a developer can work in a normal host checkout while using tools that behave in a way that is familiar to RISC OS projects.

This guide is arranged in three phases. Part 1 gets a new user from installation to a first successful build. Part 2 explains the normal daily workflow. Later chapters then move into optional subsystems and grouped command reference. Readers who already know the environment well may jump directly to the reference chapters, but new users should follow the earlier chapters in order.

What problem the environment solves

RISC OS development depends on tools, file conventions, and build patterns that do not naturally exist on a typical host system. The environment addresses that gap by providing:

  • a standard container image containing the toolchain and libraries;
  • wrapper commands such as riscos-cc, riscos-amu, and riscos-project;
  • host integration for editing, opening files, and clipboard transfer;
  • help topics and command help aimed specifically at RISC OS work;
  • optional support for 64-bit development, Pyromaniac runtime execution, and AI-assisted workflows.

Typical use cases

The environment is primarily intended for software development, but the tools cover more than plain compilation. Common use cases include:

  • cross-compiling commands, modules, libraries, and applications;
  • generating project skeletons and standard project administration files;
  • running remote builds and tests through the RISC OS Build Service;
  • building PRM-in-XML and StrongHelp documentation;
  • packaging ZIP archives with preserved RISC OS filetypes;
  • querying exported headers and libraries from the installed resource sets.

Technical Details

Core concepts

The environment has a small number of concepts that appear throughout this manual:

  • Docker image: the packaged build system and tools that are run on demand.
  • Wrapper command: a host-side command such as riscos-cc that starts the container with the right mappings. Wrapper commands call into robuild, the underlying entry point that actually starts the container, automatically; see Glossary and Installation for more on robuild itself.
  • Container shell: an interactive bash shell inside the build environment, usually started with riscos-shell or robuild shell.
  • Mounted source tree: the host working directory mapped to /riscos-source inside the container.
  • Built output: the host built/ directory mapped to /riscos-built for exported results.

The simplest way to see those concepts together is to start an interactive shell and inspect the built-in help: 

riscos-shell

charles@riscos-builder /riscos-source (documentation-book)$

riscos-help howto-start

# Getting started with the build environment

...

The bracketed text in the prompt is the current Git branch; see First Session for the full description of the prompt format.

Wrapper commands can also run individual tools directly from the host without opening a long-lived shell: 

riscos-project create --type command --name MyTool --skeleton

Creating project of type 'command' for 'MyTool'

Creating makefile: ./Makefile,fe1

Creating skeleton source files

Creating file: c/main

Creating VersionNum: VersionNum

riscos-amu BUILD32=1

...

MyTool: All built {Disc}

Why the host mapping matters

The environment is designed so that most work still happens in a normal host checkout. If the current directory is inside a Git repository, the wrapper maps the repository root to /riscos-source and restores the relative current directory inside that tree. This lets Git, editors, generated files, and build outputs stay where the host user expects.

That behaviour becomes important in later chapters when the manual refers to host paths and RISC OS paths side by side. The distinction is explained in Appendix A: Naming conventions and project files.

How the manual is organised

Readers who are new to the environment should continue with Prerequisites and then Installation. Experienced users may prefer to skip to the workflow chapters in Part 2: Core workflow guides or the grouped command reference in Part 4: Tool-group reference chapters.