Overview
The RISC OS Build Environment is supported by a set of GitHub Actions that simplify the integration of RISC OS projects into GitHub's CI/CD workflows. These actions allow for remote building and documentation generation without requiring a local RISC OS toolchain setup on the CI runner.
Action reference
Two primary actions are provided:
- riscos-build-service-action for remote building and testing;
- riscos-prminxml-action for documentation generation.
riscos-build-service-action
The gerph/riscos-build-service-action allows you to build RISC OS projects using the RISC OS Build Service. It uses a .robuild.yaml file in your repository to define the build and test steps. The file's own syntax is not repeated here; see Testing and running for how it is used, and the published syntax reference at build.riscos.online/robuildyaml.html for the full set of supported keys.
This action is particularly useful for:
- Building 32-bit and 64-bit RISC OS binaries;
- Running automated tests in a clean RISC OS environment;
- Collecting build artifacts and logs.
Inputs
| Input | Default | Description |
|---|---|---|
| architecture | aarch32 | Target architecture: aarch32 or aarch64. |
| timeout | 10 | Build timeout in seconds (maximum 600). If a build with the default timeout fails unexpectedly quickly, set timeout explicitly and check the action's published documentation for the current default. |
| files | * | Whitespace-separated glob patterns of files to send to the service. |
| output | output | Local directory where built output files will be written. |
| release | no | Set to yes to automatically version the output using VersionNum. |
| capture-filename | (none) | Filename used to save the build's standard output and error logs. |
Outputs
| Output | Description |
|---|---|
| output_filename | The full path to the generated build artifact. |
| output_filetype | The RISC OS filetype extension (e.g. ff8, feb). |
| project_version | The version number extracted from the project files. |
Example
A typical workflow step to build a project:
- name: Build on RISC OS
id: robuild
uses: gerph/riscos-build-service-action@v1
with:
architecture: aarch32
output: built
capture-filename: build.log
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: riscos-binary
path: ${{ steps.robuild.outputs.output_filename }}
Troubleshooting
On success, the step's output_filename, output_filetype, and project_version outputs are populated and the step itself reports success in the workflow run. If the remote build fails (a build error, a test failure, or the timeout being exceeded), the step fails and the workflow run stops at that step, the same as any other failing GitHub Actions step; the outputs are not populated in that case, so a later step that depends on them (such as the upload step above) will not run.
Set capture-filename whenever you need to see what the remote build actually did: it saves the build's standard output and error to the named file, which you can then upload as a separate log artifact (using actions/upload-artifact@v4 with that filename as its path) so the captured log is visible from the workflow run even when the build step itself fails before producing a binary.
riscos-prminxml-action
The gerph/riscos-prminxml-action handles the installation of the PRM-in-XML tools and generates HTML or PDF documentation from your source XML files.
Inputs
| Input | Default | Description |
|---|---|---|
| files | Required | Whitespace-separated list of XML files to process. |
| output | Required | Directory where generated files will be written. |
| lint | yes | Linting behaviour: yes (fail on error), no (skip), or quiet (report only). |
| pdf-generator | no | PDF generator to use: prince, weasyprint, or no. |
| style | none | Output style preset: prm, prm-ro2, prm-modern, or none. |
| format | html5+xml | Output format: html5+xml, stronghelp, or index. The index format builds the structured multi-document output described by an index.xml file (the same mechanism this book's own build uses to assemble its parts and chapters into one collection), rather than processing each input file independently. |
Example
Building a documentation set with Prince PDF generation:
- name: Build Documentation
uses: gerph/riscos-prminxml-action@v1
with:
files: |
prminxml/manual.xml
prminxml/reference.xml
output: output/html
style: prm-modern
pdf-generator: prince
- name: Upload Documentation
uses: actions/upload-artifact@v4
with:
name: documentation
path: output/html