Workflow guides8Project Creation and Management

Project files

The files most often managed during project setup are:

• Makefile,fe1 for the AMU build definition;
• VersionNum plus optional language-specific companion files VersionAsm, VersionBas, and VersionFortran, each only updated by riscos-vmanage if it already exists;
• .gitignore and .gitattributes;
• .robuild.yaml for remote build or test execution;
• CI workflows and issue or pull request templates.

Creating a project skeleton

The normal starting point is:

Available project types include commands, C modules, assembler modules, libraries, applications, and selected language-specific command skeletons. The default type is command if no type is supplied.

For a simple command skeleton:

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

Creating project of type 'command' for 'MyTool'

Creating makefile: ./Makefile,fe1

Creating skeleton source files

Creating file: c/main

Creating VersionNum: VersionNum

Videos 5 and 6 of Video walkthroughs follow the same skeleton command with --type cmodule, then extend the generated module to claim a vector.

Updating source lists

When a project gains new source files, riscos-project update can refresh the object list in the makefile by scanning the standard source directories. This is a convenience rather than a required step; manual editing of the makefile remains possible and normal.

Managing VersionNum

The riscos-vmanage tool manages the VersionNum workflow directly. Typical operations are:

• riscos-vmanage init to create an initial version file;
• riscos-vmanage inc to increment the version by 0.01;
• riscos-vmanage set x.yy to set an explicit version.

The riscos-project inc command is the project-level shortcut for the same increment operation.

If a project needs a fresh version file and then an increment:

riscos-vmanage init --version 0.01

riscos-vmanage inc

Version number now 0.02

init is silent on success; inc, set, and update all report the resulting major version number once they have written the file.

Substituting version data into other files

Once a project has a VersionNum file, the riscos-vtranslate tool can copy values from it into text resources and source files. This is the normal way to keep version strings in step across files such as Messages, !Help, release notes, and generated BASIC sources without editing each file manually.

The input file is copied to a new output file. Any name written as {Name} is looked up in VersionNum and replaced with the matching #define value. Unknown names are left unchanged and normally produce a warning, which is useful for spotting misspelt tokens. A literal left brace may be written as \{.

A simple text-resource translation looks like this. RISC OS filenames have no extensions, and a dot is read as a directory separator, so the input and output names here must be plain leafnames rather than Messages.src-style host names with a dot in them:

riscos-vtranslate VersionNum MessagesSrc Messages

If MessagesSrc contains text such as Version: {Module_FullVersionAndDate}, the output file Messages will contain the expanded version string from VersionNum. A dotted name such as Messages.src would instead be read as the file Messages/src and fail with Could not read Messages/src unless that directory and file genuinely exist.

The same mechanism can be used with BASIC source files before tokenising them, so a project can keep version placeholders in a textual ,fd1 source and translate them into a build copy when required.

BBC BASIC sources and version files

The normal conversion helpers are riscos-basictokenise and riscos-basicdetokenise.

For BBC BASIC projects, keep the editable source in textual form with the host suffix ,fd1. That format works well with Git, diff tools, and normal host editors. Tokenised BASIC files with the suffix ,ffb should normally be treated as build artifacts or managed files rather than as the preferred source form for manual editing.

When a tokenised program must be reviewed or recovered, detokenise it first. Both conversion tools are silent on success:

riscos-basicdetokenise -i !RunImage,ffb -o Source,fd1

To create a tokenised BASIC program from a textual source file:

riscos-basictokenise Source,fd1 !RunImage,ffb

If the BASIC source contains version placeholders, translate it before tokenising:

riscos-vtranslate VersionNum Source,fd1 BuildSource,fd1

riscos-basictokenise BuildSource,fd1 !RunImage,ffb

As with the text-resource case above, the comma in Source,fd1 is the host-side filetype suffix, not a dotted extension, so these names are already in the correct bare-leafname form.

The version-management tools also support a BASIC companion file called VersionBas. The main VersionNum file remains the source of truth, but if a tokenised BASIC version library is needed for the project it can be enabled by creating VersionBas,ffb and then asking riscos-vmanage to update the managed files. The generated BASIC library provides PROCinit_version and variables such as version_full$ derived from VersionNum.

riscos-vmanage init --version 0.01

touch VersionBas,ffb

riscos-vmanage update

Version number now 0.01

Once VersionBas,ffb exists, later riscos-vmanage inc, riscos-vmanage set, and riscos-vmanage update operations keep it aligned with the main version file automatically.

The same "create the file, then let riscos-vmanage keep it updated" pattern applies to the assembler companion file VersionAsm and the Fortran companion file VersionFortran; see 64-bit Development for the Fortran case, including the generated file's contents.

Project administration helpers

The environment includes project administration helpers that create ordinary editable files:

• riscos-project create-git for Git ignore and attribute files;
• riscos-project create-pr for issue, PR, and ownership templates;
• riscos-project create-ci for CI workflow files and .robuild.yaml;
• riscos-project create-license for a project license file.

A new module project often starts with this sequence:

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

Creating project of type 'cmodule' for 'MyModule'

Creating makefile: ./Makefile,fe1

Creating skeleton source files

Creating file: cmhg/modhead

Creating file: c/module

Creating VersionNum: VersionNum

riscos-amu BUILD32=1

...

MyModule: Module built {RAM}

riscos-project create-git

riscos-project create-ci

Creating CI for 'MyModule'

riscos-amu output is abbreviated above; it runs riscos-cmunge on the CMHG header, compiles the C source, and links the module, printing each command as it runs. riscos-project create-git is silent on success and writes .gitignore and .gitattributes directly.

When to add them

These helpers are usually applied after the first successful build of a new project skeleton. That keeps the initial validation step focused on whether the generated source and makefile structure are sound, and then adds the source control, licensing, and automation files once the project has a confirmed build baseline.

The generated files are ordinary project files intended for review and local editing. Treat them as the maintained source form for CI behaviour, licensing, and repository administration rather than as opaque generated artifacts.

Preparing allocation requests

Some projects need names or number ranges to be registered with the RISC OS Open allocations service before release. Common examples include module names, SWI chunks, error blocks, filetypes, service blocks, and reserved names such as star commands or application names.

The build environment includes riscos-allocate for working with Allocate request files. It is useful when you want the request in source control, need to review or edit it as text, or need to recreate the binary file to mail to the allocations service.

The normal process is:

1. Decide which resources need allocating for the project.
2. Write a YAML request description, or extract and edit an existing request with riscos-allocate.
3. Create the binary Allocate request with riscos-allocate.
4. Send the request to allocate@riscosopen.org, normally as the generated ,fb0 request file.

The YAML description schema and the historical binary request layout are documented in Appendix N: Allocate request file formats.

Simple reservation example

The smallest useful request is often a reservation for a module name, application name, or star command. This example reserves a module name called ExampleModule.

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

Create the binary request file with:

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