RISC OS Build EnvironmentROBE

Appendix35Appendix A: Naming conventions and project files

Overview

RISC OS development in a host filesystem requires two naming systems to coexist: host filenames and RISC OS filenames. This appendix summarises the conventions used by the build environment so that examples in the earlier chapters can be read correctly.

Naming conventions

Host and RISC OS filename forms

On the host side, RISC OS filetypes are represented by comma suffixes such as TestProgram,fd1 or Module,ffa. In RISC OS command usage, the suffix is removed and directories use dots instead of slashes, so the same files appear as TestProgram or Module.

A host file with no comma suffix at all is not given a filetype by this convention; the wrapper tools treat it as a plain host file rather than inferring a RISC OS filetype, so project source files should always carry an explicit suffix. Files using the older RISC OS load/exec address scheme instead of a single filetype number are encoded on the host as name,llllllll,eeeeeeee rather than a 3-hex-digit suffix; this form is rarely seen in modern project sources. Characters permitted in a RISC OS leafname but not representable directly in a host filename (most commonly the forward slash, which is the host directory separator but a literal character within a RISC OS leafname) are not given any special escaping by this build environment's own tools; avoid them in project filenames. See the riscos-filesystem skill for the full filename and filetype reference.

Directory naming

Source directories on the host commonly use names such as c/, s/, h/, and output directories such as aif32/ or rm32/. When those are addressed through RISC OS commands, slashes become dots.

Important project files

The main project files described throughout this manual are:

  • Makefile,fe1 for AMU-driven builds;
  • VersionNum and related version files;
  • .robuild.yaml for remote build or run jobs;
  • prminxml/*.xml for PRM-in-XML documentation sources.

Output directory naming

Build outputs are usually grouped by type and architecture, for example aif32/ for 32-bit absolutes or rm32/ for 32-bit modules. Documentation generated for this manual is written separately into html/ so that the rendered output cannot overwrite the PRM-in-XML sources.

Filename mappings

Host and RISC OS filename pairs

These examples show the same paths and files in host and RISC OS naming forms. 

c/module on the host corresponds to c.module in RISC OS commands.

test,fd1 on the host corresponds to test in RISC OS commands.

aif32/Tool,ff8 on the host corresponds to aif32.Tool in RISC OS commands.

There is no dedicated tool in this environment for checking a hand-translated path. The practical way to confirm one is correct is to use it directly: run *Cat on the RISC OS-style path (or *Ex for a directory) through riscos-build-run; if the translation is wrong, the command reports that the object cannot be found rather than silently succeeding.