RISC OS Build EnvironmentROBE

Appendix36Appendix B: Common Workflows

Overview

This appendix provides short recipe-style workflows for common tasks. It is intended as a quick reminder once the earlier chapters have explained the concepts in more detail.

Using these workflow recipes

This appendix collects compact command sequences for the most common jobs: creating a command, creating a module, running a remote test, packaging a ZIP, and generating documentation.

Workflow recipes

Create and build a command

Use this sequence for a minimal command project. 

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

riscos-amu BUILD32=1

Create and build a module

Use this sequence for a minimal C module project. The CMHG or CMunge description file then generates the veneer object and header used by the rest of the build. 

riscos-project create --type cmodule --name MyModule --skeleton

riscos-cmunge -px -32bit -throwback -o o32.modhead -d h.modhead cmhg.modhead

riscos-amu BUILD32=1

Run a remote test

This shows the minimal pattern for sending a built command to the remote run service. 

riscos-build-run aif32/MyTool,ff8 --command MyTool --timeout 30

A return code of 0 indicates the command succeeded; any non-zero value indicates a failure, such as a RISC OS error, a timeout, or a startup problem reported by the remote service.

Package a release ZIP

This packages a binary while preserving the RISC OS filetype metadata. 

riscos-zip -v mytool.zip aif32/MyTool,ff8

riscos-unzip -l mytool.zip

Create documentation

This is the minimal PRM-in-XML authoring and build workflow. 

mkdir -p prminxml html

riscos-prminxml -f skeleton -o prminxml/mycomponent.xml

riscos-prminxml -f lint prminxml/mycomponent.xml

riscos-prminxml -f html5+xml -O html prminxml/mycomponent.xml

host-open html/mycomponent.html

host-open opens the generated page in the host's default browser so the rendered output can be checked, rather than only confirming that the build step produced no errors.

Prepare an allocation request

Use this when a project needs an allocation request file for the RISC OS Open allocations service. 

cat > request.yaml <<'EOF'

SchemaVersion: 1

FormatVersion: 1.00

Developer:

  Name: Example Developer

  Company: null

  DeveloperNumber: null

  Address1: null

  Address2: null

  Address3: null

  Address4: null

  Phone: null

  Fax: null

  Email: example@example.invalid

Registrations:

  - Reservation:

      Type: ModName

      Text: ExampleModule

EOF

riscos-allocate --create request.yaml -o request,fb0

This creates a binary Allocate request that can then be mailed to allocate@riscosopen.org. For the YAML schema and the historical binary layout, see Appendix N: Allocate request file formats.

Port an existing C library

Use this sequence to create and validate the first-pass RISC OS port for an upstream C repository. 

riscos-cport mylib

cd mylib/RISCOS

riscos-amu export

riscos-amu

The final riscos-amu build confirms the exported headers and libraries actually compile against the generated makefile, matching this guide's own principle of always building a newly created project before extending it; see Porting existing C projects for the full validated porting sequence, including running the library's own tests where it has them.