RISC OS Build EnvironmentROBE

Introduction4First Session

Introduction and Overview

This chapter walks through a short first session in the build environment. The goal is to confirm that the shell starts correctly, that directory mapping is understood, and that a simple project can be created and built successfully.

The examples use a command-line project because it is the smallest complete workflow: create a project, build it, inspect the output, and locate the resulting files.

Technical Details

Starting a shell

On a wrapper-based installation, the normal interactive entry point is riscos-shell. Inside the shell the current directory is mapped from the host, usually relative to the root of the current Git repository.

That mapping means the source tree is visible in /riscos-source, while exported build artifacts appear in /riscos-built and are reflected in the host built/ directory.

A typical first entry into the shell is: 

riscos-shell

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

The prompt shows the container user, the current directory (always rooted at /riscos-source), and the current Git branch in brackets. Seeing this prompt confirms that the shell started and the source tree mapping worked.

Reading local help

The environment includes two complementary help forms:

  • riscos-help <topic> for broader topics such as installation, projects, or variables;
  • <command> --help or command-help entries for individual wrappers.

New users should begin with riscos-help howto-start, then move to riscos-help projects and riscos-help build-and-link as needed.

This manual is also included in the environment. Use riscos-help guide to open the HTML version or riscos-help guide-pdf to open the PDF version on the host system.

For example: 

riscos-help howto-start

# Getting started with the build environment



The build environment contains the compilers and tools necessary

to build RISC OS components. It also contains a tool to create

stub code for new projects. The `riscos-project` tool can be used

to create a new Makefile, and code to build simple programs.

...

Creating and building a first project

The quickest starting point is a command skeleton:

Use riscos-project to create it and riscos-amu to build it.

The default build creates an absolute file in aif32/FirstTool,ff8. The exact directories used depend on the makefile type and build macros, but command skeletons use the standard aif32/ output path.

The complete first build sequence is: 

mkdir FirstTool

cd FirstTool

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

Creating project of type 'command' for 'FirstTool'

Creating makefile: ./Makefile,fe1

Creating skeleton source files

Creating file: c/main

Creating VersionNum: VersionNum

riscos-amu BUILD32=1

riscos-cc   -c  -Wc -fa   -IC: -za1 -Otime -apcs 3/32/fpe2/swst/fp -D__CONFIG=32 -o o32/main c/main

Norcroft RISC OS ARM C vsn 5.18 (JRF:5.18.134)  [Mar  5 2026]

riscos-link -rescan -C++ -aif -o aif32.FirstTool o32.main C:o.stubsGS

FirstTool: All built {Disc}

The final All built {Disc} line confirms a successful build. The Norcroft compiler version line will vary between environment releases, so do not expect an exact match.

Inspecting outputs

Once the build completes, inspect the output in two places:

  • the project directory, where intermediate and primary build outputs such as aif32/ appear;
  • the mapped built area in built/ on the host when a project exports files to /riscos-built.

Binary contents may be examined with riscos-dump, riscos-dumpi, or more conveniently with riscos-less.

For a quick inspection: 

riscos-less aif32/FirstTool,ff8

00008000 : e1a00000 : .... : MOV     r0, r0          ; AIF: Decompression branch

00008004 : e1a00000 : .... : MOV     r0, r0          ; AIF: Self relocation branch

00008008 : eb00000c : .... : BL      &00008040       ; AIF: Zero init branch

0000800c : eb000285 : .... : BL      &00008a28       ; AIF: Entry point branch

...

riscos-less recognises the AIF (Application Image Format; see Glossary) header and disassembles the code, annotating the standard AIF fields. Seeing disassembled instructions rather than an error confirms that the file is a valid absolute binary.

Where to go next

After a successful first build, continue with Shell and host integration and Project creation and management for the day-to-day workflow. The first two videos in Video walkthroughs walk through installation and this same first-project sequence on screen.