Introduction : Installation

Introduction and Overview

Installation consists of choosing how the build environment will be entered. Most users on Linux, macOS, and WSL2 will install the wrapper commands into a directory on their PATH. Users who do not want a local wrapper installation may instead invoke the container directly with Docker commands.

This chapter covers both routes, explains the image-selection variables that affect startup, and shows the first checks that confirm the installation is usable.

Technical Details

Choosing an image label

All of the Docker commands in this chapter need a concrete image reference. The published images are named gerph/riscos-build, with a tag that selects the variant and version:

gerph/riscos-build:latest for the standard 32-bit toolchain;
gerph/riscos-build:latest-64bit to add the 64-bit tools;
gerph/riscos-build:latest-pyro to add Pyromaniac;
a specific version number in place of latest, for example gerph/riscos-build:3.000, to pin a release.

Most users should start with gerph/riscos-build:latest and move to a -64bit tag only once 64-bit development is needed. The examples below use gerph/riscos-build:latest; substitute a different tag as required.

Installing the wrapper commands

The wrapper installation command writes host-side launchers into a directory that is mapped as /riscos-built during the installation run. Choose an absolute host directory and ensure it is on the host PATH.

Once installed, the wrappers may be run directly from the host. Commands such as riscos-shell, riscos-amu, and riscos-project all use the same underlying image and directory-mapping logic.

One direct installation route is:

mkdir -p "$HOME/bin/riscos-build"

docker run --rm -v "$HOME/bin/riscos-build:/riscos-built" -e UID=$(id -u) gerph/riscos-build:latest install

Installing build environment using image latest

Installing into directory '/home/charles/bin/riscos-build'

  Create tool riscos-amu

  Create tool riscos-project

  ...

Installation complete. To see the README, use:

    riscos-shell help

The install run lists every wrapper tool it creates, so the output above is abbreviated; the final two lines confirm that installation succeeded.

Using the environment without local wrapper installation

If a wrapper installation is not desired, the environment can be entered directly with Docker. The important mapping is the source tree into /riscos-source.

For example:

docker run --init -it --rm -v $PWD:/riscos-source -e UID=$(id -u) gerph/riscos-build:latest robuild shell

user@51df92523b08 /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.

Selecting image versions

Wrapper startup can be influenced by host environment variables:

ROBUILD_DOCKER_VERSION selects a specific tagged image version;
ROBUILD_DOCKER_IMAGE overrides the image name;
ROBUILD_DOCKER_REGISTRY overrides the registry, with local used for a local registry.

Most users should leave these variables unset and use the default published image. They are primarily useful when pinning a version for repeatable work or testing a locally built image.

A simple version pin looks like this:

export ROBUILD_DOCKER_VERSION=3.000

riscos-shell

First verification steps

After installation, the first verification should be simple and low-risk:

start a shell with riscos-shell or robuild shell;
run riscos-help howto-start to confirm that topic help is available;
run riscos-project --help or another wrapper to confirm that tool startup works.

The next chapter turns those checks into a first short session inside the environment.

After installation, a simple help command is enough to verify that the wrapper starts the container and returns correctly:

riscos-project --help

riscos-project 0.04.79

Syntax: riscos-project <operation> <options>

Options:

    --help, -h              This help message

    ...

A version number and syntax summary confirm the wrapper reached the tool inside the container; an error from Docker itself (rather than from riscos-project) indicates a problem with the image reference or the host Docker setup instead.

Introduction3Installation