Reference guide29Environment and Help Tools

Starts the Docker-based build environment with the correct path mappings and host variables for the current project.

The normal invocation styles are: run a command directly, start the shell through shell or --shell, or install wrapper stubs with install. The command also controls the host-to-container mappings that later affect host-open, host-edit, and related bridge commands.

Important environment variables include ROBUILD_DOCKER_VERSION, ROBUILD_DOCKER_IMAGE, and ROBUILD_DOCKER_REGISTRY for container selection, ROBUILD_DIRVARS and ROBUILD_DIRBINDS for extra mapped directories, ROBUILD_VARS for host variables to pass through, ROBUILD_VNC for Pyromaniac VNC support, and ROBUILD_EDITOR for the editor used by host-edit.

This reference covers the documented invocation modes and the environment variables that matter for normal use. It is not an exhaustive subcommand reference; run robuild --help for the full, current live option list.

The build environment supplies a small wrapper for man so that the most natural help lookup form also finds the environment's own documentation. A plain command such as man riscos64-link first checks whether the requested name exists as a local riscos-help topic page or command page.

If such a page exists, the wrapper runs riscos-help or riscos-help --command and shows that page through the normal local pager path. If there is no matching local page, or if you use a more complex man form such as man 1 make, man -k pattern, or a multi-argument invocation, the wrapper falls back directly to the system man command.

This makes man useful as a general first stop inside the environment: local build-environment commands and topics are preferred when available, while ordinary Unix manual pages remain accessible without learning a separate command.

riscos-transformcli rewrites a command line written in RISC OS terms into the POSIX layout used inside the container. Many wrapper commands use it automatically so they can accept RISC OS-style source trees, filenames, typed output names, and directory-variable syntax while still invoking ordinary host-side tools underneath.

Typical rewrites include source names such as c/main, h/main, s/start, and cmhg/head, together with common build directories such as o, o32, o64, rm, util, and bin. The transformer also recognises typed output names such as files ending in ,ff8, ,ffc, or ,ffa, and the upstream documentation states that it expands path references written in the angle-bracket form <Export$Dir> through the standard ..._DIR environment variables.

This could not be confirmed in this build. Direct invocation with a bracketed path such as <Export$Dir> always passed the argument through unchanged, both for riscos-transformcli and riscos64-transformcli. Indirect routes were also tried without success: compiling with an -I<Export$Dir>.Lib include path through riscos-cc, and running riscos-amu export on a library skeleton with ROBUILD_TRANSFORMCLI_DEBUG set, neither produced any sign of the expansion happening. Treat the angle-bracket form as undemonstrated in this image rather than relying on it; if a path needs to be built from EXPORTS_DIR or a similar variable, expand it yourself in the shell instead. If BUILD64=1 is already set, the normal mode prefers the matching RO64... variables first; to force that behaviour regardless of the current build selection, use riscos64-transformcli instead.

Direct use is uncommon because most user-facing wrappers already invoke the transformer for you. Calling it yourself is mainly useful when debugging wrapper behaviour, checking how a path will be rewritten, or running an arbitrary command through the same translation layer by hand.

The command creates and reuses a .rotransform/ tree in the working directory and a cache under ${XDG_CACHE_HOME:-$HOME/.cache}/robuild-transform. Set ROBUILD_TRANSFORMCLI_CLEAN to 1 to rebuild those transformed links and caches, and use ROBUILD_TRANSFORMCLI_DEBUG for more detailed bitfield-style tracing.

riscos64-transformcli is the same underlying transformer as riscos-transformcli, but invoked in the 64-bit mode that prefers RO64... path variables when expanding RISC OS-style directory references.

It rewrites source and build-tree names such as c/main, h/main, s/start, cmhg/modhead, and output directories such as o64, aif64, or typed names ending in ,ff8. The upstream documentation also describes angle-bracket path variables such as <Export$Dir> being expanded into host paths, but this could not be confirmed in this build by any tested method, direct or indirect; see the equivalent note under riscos-transformcli.

Most users never call this tool directly because the 64-bit compiler, linker, and archive wrappers invoke it automatically when they need command-line translation. Direct use is mainly for debugging path rewriting, experimenting with wrapper behaviour, or running another command through the same translation layer by hand.

The command creates and reuses a .rotransform/ tree in the working directory and a cache under ${XDG_CACHE_HOME:-$HOME/.cache}/robuild-transform. Set ROBUILD_TRANSFORMCLI_CLEAN to 1 to force a rebuild of those transformed links and caches, and use ROBUILD_TRANSFORMCLI_DEBUG for more detailed bitfield-style tracing.

riscos-help is the main entry point for the environment's local documentation. It displays topic help pages, command reference pages, the environment version, and the accumulated changelog.

Topic help is read from the general help directory and command help from the command-reference directory. When a name matches both a topic and a command page, the topic page is shown; use -c or --command to force the command page. Pages are displayed through riscos-less.

If no local page matches and the lookup name looks like a SWI call in the form OS_Claim or XOS_Claim, riscos-help passes the name to riscos-prm so that Programmer's Reference Manual SWI documentation can be reached through the same entry point.

With no argument the command lists the available help topics, as shown in the example below. The set of topics grows as the environment gains features, so treat the listing as a snapshot of the current build rather than a fixed list.

The special names provide additional functions. commands lists the command reference pages; there is one page for every command supplied by the environment, so it doubles as an index of the available tools, and any of those commands can then be read with riscos-help command. changelog shows the accumulated changelog, and version prints the environment version number.

When the built documentation has been included in the image, in /riscos-resources/guide, two further names become available. guide opens the HTML manual and guide-pdf opens the PDF manual. Because the manual is shipped inside the container where the host cannot see it directly, each command first copies it into the host-visible cache directory ~/.cache/riscos-build-help and then opens it through host-open. When the documentation is absent, these names are omitted and report that the guide is not available.

With no argument, or with -h or --help, the command prints its syntax, lists the available help topics, lists the guide commands when the built documentation is present, and points to riscos-prm for Programmer's Reference Manual lookups.

riscos-prm looks up existing material from the Programmer's Reference Manuals and displays the relevant section. It is the tool to reach for when you know the name of a SWI, vector, service call, command, or chapter, or when you need the upstream reference URL.

By default, SWI calls and service calls are displayed as readable markdown in the terminal, while other content is launched in a browser on the host through the same host-opening path used by host-open. Use --url to print the documentation URL instead of opening it, or --open to force the browser to launch.

SWIs and service calls may be looked up by name or by hexadecimal number, using the forms "SWI 33" or "Service 400C0". For multi-reason SWIs, a reason code may be supplied as a further argument, as in riscos-prm OS_File 1.

The search can be narrowed to a particular kind of interface with --vector, --swi, --service, --command, or --chapter. The corresponding plural options, --vectors, --swis, --services, --commands, and --chapters, list all of the known entries of that kind.

The --summary option produces a concise interface summary for a SWI, optionally without tables when --no-tables is given. This is the form used by riscos-swi-lsp when offering editor hover help.

riscos-less is a thin wrapper around less that enables the build environment's RISC OS-aware filter setup before the pager starts. The wrapper does not invent a new pager syntax; it exists to ensure that the configured lesspipe and lessfilter logic is applied consistently.

The filter layer can colour or decode many plain-text formats automatically through tools such as pygmentize, nano-colour, jq, csvkit, and grcat. In practice that covers many source and text forms, including shell, Perl, Python, C, assembler, Pascal, Fortran, makefiles, Dockerfiles, Jenkinsfiles, BBC BASIC text, Markdown, YAML, JSON, CSV, XML, SVG, Graphviz, and JUnit XML result files.

The same filter chain also decodes many binary and structured formats into a readable text form before paging them. These include tokenised BBC BASIC through riscos-basicdetokenise; AIF, utility, and module binaries through riscos-dumpi; generic binaries through riscos-dump; AOF files through riscos-decaof; ALF libraries through riscos-libfile; ELF files through objdump or riscos64-objdump; ar archives; Mach-O binaries; Python bytecode; certificates and keys through openssl; property lists through plutil; ZIP archives through unzip or riscos-unzip; Spark, ArcFS, and Squash archives through riscos-nspark; StrongHelp manuals through riscos-shextract; TBAFS archives through riscos-tbafs; DrawFiles through riscos-decdrawf; sprite files through riscos-dumpsprites; and templates or Toolbox resources through riscos-ccres.

Content-based detection is used as well as suffix matching. The filter can recognise formats such as XML, ELF, AOF, ALF, DrawFile, Mach-O, ZIP, tokenised BASIC, textual BASIC, StrongHelp, and Spark archives from the file content, and it also infers useful types from RISC OS filetype suffixes such as ,aff, ,3d6, ,b21, ,ff9, ,fae, and ,fec.

Use riscos-less as the broad first-pass viewer when you are exploring an unfamiliar file. Switch to a specialist command when you need exact control over options, output format, or further processing than the pager view gives you.

Normal less options are passed through unchanged. This entry does not duplicate the pager's full switch reference because the wrapper adds no command-specific options of its own.

nano-colour is the terminal highlighter used by parts of the build environment's pager and shell-viewing workflow. It reads NanoRC syntax definitions, selects a syntax either explicitly or by matching the target file, and writes ANSI-coloured text to standard output.

The syntax source may be supplied as the final positional parameter or through NANOCOLOUR_DIR. The path may name either one NanoRC file or a directory containing files ending in .nanorc together with a file named nanorc. Relative include directives are resolved relative to the including file, and a leading ~ is expanded through HOME.

Without -s or --syntax, the command first compares the target path against the file-matching regular expressions supplied on syntax lines. If no file rule matches, it reads the first line of the target file and tests any header expressions. When no syntax is identified, normal mode copies the input unchanged; with --supported, the command instead exits with status 1 and produces no output.

When reading from standard input, explicit syntax selection is normally required because automatic selection depends on the supplied file path and, for header rules, on the first line of a real file. The recognised NanoRC subset and colour forms are described in Appendix S: NanoRC syntax format.

riscos-swi-lsp is an editor integration tool rather than a shell lookup command. It runs a Language Server Protocol server which understands common RISC OS SWI call forms and can return hover help and insertion completions for editors that speak LSP.

The LSP model separates language knowledge from editor-specific plug-ins. An editor starts the server, keeps it informed about the current document and cursor position, and asks for features such as hover information or completion results. That lets the same SWI-aware backend work across multiple editors without reimplementing the SWI logic for each one.

With no transport option, the server uses standard input and output. That is the normal configuration for local editor integration. Use --tcp to listen on a TCP socket instead, or --ws for a WebSocket transport. When either socket mode is selected, --host and --port choose the bind address and port.

The server prefers to obtain summary text by running riscos-prm --summary --no-tables for the hovered SWI. If that command is unavailable or does not return data, the server falls back to its bundled SWI database so that basic help and completion remain available.

The current parser recognises C forms such as _swi(...) and _swix(...), BBC BASIC forms such as SYS "OS_File", and assembler SWI instructions. For C and BASIC it can often decode register inputs and outputs, including _IN, _OUT, _INR, and _OUTR flags, and can infer reason codes for many multi-function SWIs from the supplied register values.

Hover requests return Markdown describing the interface, and completion requests can insert a skeleton call for _swix(SWI_Name,...) or SYS "SWI_Name",... using the known register interface. Assembler support is currently simpler: the SWI name can be recognised for hover lookup, but reason-code inference is not generally available there.