Reference guide25Project and CI

Creates and maintains the standard editable project files used by RISC OS components in this environment. Its main jobs are generating a new Makefile,fe1, optionally creating starter source skeletons, updating object lists, generating Git and CI support files, creating PR and license templates, and incrementing the project version through VersionNum.

The main operations are:

The project templates support these component types:

Without --type, the default type is command. Without --name, the tool picks a type-appropriate default name such as MyCommand, MyModule, or MyLibrary.

create-pr uses the environment variables GITHUB_USER_LOGIN and GITLAB_USER_LOGIN (see the System Variables section below) when populating ownership templates. After creating a new component, the normal next step is to build it immediately with riscos-amu.

The C++ templates target the 64-bit toolchain. With --skeleton, c++command creates cc/main and a Makefile,fe1 using LibraryCommand with ${CLIB} ${C++LIB} in LIBS. The c++module template creates cc/module, cmhg/modhead, and a Makefile,fe1 using CModule with ${C++LIB} in LIBS. Build either template with riscos-amu BUILD64=1.

The fcommand skeleton creates a real Fortran project template. With --skeleton it creates f90/main and a Makefile,fe1 using LibraryCommand with ${CLIB} ${FLIB} in LIBS. The starter source includes VersionFortran, so create that companion file when needed and refresh it with riscos-vmanage.

Use create-license list to enumerate the installed license templates. Then pass the chosen template name as the positional argument to create-license.

Creates and updates VersionNum as the main version source for a project. If language-specific companion files such as VersionAsm, VersionBas,ffb, or VersionFortran already exist, riscos-vmanage update refreshes them from the current VersionNum data.

For BASIC projects, the generated VersionBas,ffb library provides PROCinit_version and a set of version variables derived from the main version file.

Use -version x.yy when you need to supply the version explicitly for init or set.

Reads a VersionNum-style header and substitutes its #define values into a template or source file. It is commonly used for Messages, !Help, generated release text, and BBC BASIC source files that need embedded version strings.

Substitutions are written as {Name}. If Name is defined in the version file, its value is inserted into the output. Undefined names are left unchanged and normally produce a warning. Use \{ when a literal left brace is required in the output.

The input is treated as ordinary text. The tool does not modify the source file in place; it writes a separate output file.

riscos-allocate works with the request format used by the historical !Allocate desktop application. It reads binary Allocate request files, can print a summary for inspection, can extract those files into a UTF-8 YAML description, and can recreate the binary request after the YAML has been edited.

With no conversion switch, the command displays a human-readable summary of the binary request. Use --extract when you want one YAML file, or --extract-files when filetype attachments should be written out as sibling files instead of being embedded in YAML.

Use --create to rebuild a binary request from YAML. The input may be either a YAML file or a directory containing Allocation.yaml; detached attachment filenames are resolved relative to that file or directory. If -o is omitted, extract mode writes YAML to standard output and create mode writes the binary request to standard output.

The YAML description preserves the developer details and the ordered registration list. Text fields in the binary format are Latin-1, so the creator warns and replaces characters outside Latin-1 with ?. It also warns about missing fields, unexpected fields, missing detached files, and other structural problems in the YAML input.

The YAML schema and the binary Allocate request format are described in Appendix N: Allocate request file formats.

Scans an existing C repository and creates a RISCOS/ subdirectory containing a normal RISC OS port skeleton. The generated tree links the original files into RISCOS/c/ and RISCOS/h/, creates makefiles with riscos-project, and prepares library exports or command makefiles for later editing.

The tool is intended as a structural first pass. Let it discover the obvious inputs, then use the override switches to correct unusual layouts, generated headers, host-only test sources, or command-specific dependencies. Once the generated tree is structurally correct, validate it with riscos-amu export for libraries or with a specific makefile build for command ports.

When discovery is wrong, the most useful controls are usually --exclude-source, --command-source, --define, --command-define, and --include. These usually remove the need for broader source edits until the final compiler-validation stage.

Autodiscovery covers source files but not headers: a run with no --header switch reports Exported headers: None and Compile-time headers: None in RISCOS_PORT.md even when the original repository has a header directory, and the export build then fails to find any #include that needs them. Pass --header for each public header file or directory explicitly. Generated headers also land flatly in RISCOS/h/ with no subdirectory prefix, so a source tree that uses namespaced includes such as #include "mylib/util.h" needs those includes rewritten to the flat form before riscos-amu export succeeds.

Runs one or more RISC OS commands remotely, optionally returning files or directories to the host project afterwards.

The most common pattern is to upload one or more files, add one or more --command switches for the RISC OS commands to execute, and then use either --return-file or --return-dir together with --return-to when you want artifacts copied back to the host.

Use --timeout to stop runaway jobs, --arch or the --32 and --64 shorthands to select the target architecture, and --ansi if ANSI-coloured output is preferred. --quiet and --very-quiet reduce wrapper chatter.

Uploads a prepared archive directly to the build service and writes returned artifacts back to the host.

The command is the lower-level client underneath riscos-build-run. Use -i to supply the input archive, -o to choose the output filename prefix, -b to save the textual build log separately, and -A to select aarch32 or aarch64.

For service control, use -s to point at a different build-service URI, -t for timeout control, -a on|off for ANSI text, and -q or -Q to suppress non-essential messages.