Overview
A companion video playlist demonstrates many of the workflows covered in this manual, recorded against the build environment itself. They are useful alongside the text for readers who want to see a tool or workflow in motion before trying it themselves.
The full playlist is at RISC OS Build Environment video playlist. Each entry below links directly to that video within the playlist, so viewers can carry on to the next or previous video from there.
Videos
1. Installing the build environment
Installing the Docker image on Linux, macOS, and Windows under WSL2, choosing between the regular and 64-bit image variants, installing the host-side tools into ~/bin, and a first look at the installed toolchain and the riscos-help system.
2. Your first CLI program
Creating a minimal command-line project from an empty Git repository with riscos-project create, touring the generated skeleton and VersionNum file, building with riscos-amu, running the result with riscos-build-run, and committing the result to Git.
3. Creating a GitHub repository
Publishing the first project to GitHub: creating the remote repository, choosing public or private visibility, connecting the local repository to the remote, generating a personal access token, and pushing the existing commits.
4. Adding GitHub repository features
Using riscos-project to add .gitattributes, .gitignore, GitHub Actions and GitLab CI files, a .robuild.yaml test description, an MIT licence, issue and pull-request templates, CODEOWNERS, and a README, then reviewing the resulting GitHub presentation, a passing Actions run, and a downloadable build artefact.
5. A simple module
Creating a skeleton RISC OS C module instead of a command-line tool with riscos-project create --type cmodule --skeleton, touring the CMHG file and module C source, building the module variants with riscos-amu, and adding the same repository extras before publishing the module to GitHub.
6. Claiming vectors
Extending the skeleton module to claim WrchV and convert written characters to upper case: declaring the vector handler in CMHG, implementing it in C, looking up SWI OS_Claim and SWI OS_Release with riscos-prm, wiring the claim and release into module initialisation and finalisation, and testing the result with riscos-build-run.
7. BASIC text and graphics
Writing a textual BBC BASIC program that computes Collatz sequence lengths, running it in the build environment, and charting the output: untokenised BASIC source files, error handling with ON ERROR and ERL/10, drawing rectangles to the screen, saving a screenshot from a RISC OS run, and tokenising the source into a standard BASIC file for inspection with riscos-dump.
8. Building 64-bit RISC OS C code
Rebuilding the same C source for 64-bit RISC OS with a small change to the build command: BUILD64=1 with riscos-amu, the resulting aif64 and o64 output directories, and the --arch AARCH64 flag needed to boot a 64-bit environment with riscos-build-run.
9. Some other tools in the build environment
A rapid survey of supporting tools beyond the compiler and builder: file inspection and disassembly with riscos-dump, riscos-dumpi, and riscos-less; API lookup with riscos-prm; archive handling; BASIC tokenising and detokenising; DrawFile and sprite conversion; StrongHelp tools; and the 64-bit ObjAsm wrapper that translates ObjAsm syntax for the GNU assembler toolchain.
Related information
For the written equivalent of these workflows, see First Session, Project creation and management, 64-bit development, and Documentation lookup and inspection.