Introduction and Overview
The build environment includes documentation tools for three different jobs: looking up existing RISC OS interface documentation, generating new structured documentation, and browsing symbol-oriented reference data. New users often benefit from understanding which tool is intended for which question.
Local help and manuals
Topic help and command help
Use riscos-help for environment-specific topics such as installation, projects, variables, and Pyromaniac usage. Use individual command help for wrapper-specific syntax. In practice, riscos-help answers workflow questions, while --help answers command syntax questions.
The built manual: guide and guide-pdf
When the built documentation has been included in the image, the complete manual can be opened on the host desktop without leaving the build environment. riscos-help guide opens the HTML manual in a browser, and riscos-help guide-pdf opens the PDF manual.
The manual is shipped inside the container, where the host cannot see it directly, so each command first copies the manual into the host-visible cache directory ~/.cache/riscos-build-help and then asks the host to open it through host-open. Because the copy is refreshed on each call, the opened manual always matches the version installed in the environment.
Both commands are only available when the built documentation is present, in /riscos-resources/guide. When it is present, the two commands are also listed in the no-argument riscos-help output; when it is absent, they are omitted and report that the guide is not available.
riscos-help guide
Opening the HTML guide on the host system...
Opening host file: <host-cache-path>/riscos-build-help/index.html
riscos-help guide-pdf
Opening the PDF guide on the host system...
Opening host file: <host-cache-path>/riscos-build-help/ROBE.pdf
Reference lookup and library discovery
riscos-prm
riscos-prm looks up existing PRM material. It is useful when you know the name of a SWI, want to locate a PRM chapter, or need the URL for upstream reference material.
For example:
riscos-prm --chapters
Chapters:
Commands and the CLI
ADFS
...
riscos-prm --url OS_File
http://www.riscos.com/support/developers/prm/fileswitch.html#40713
--chapter restricts the search to chapter names, such as "An introduction to RISC OS", not SWI, vector, service, or command names. A SWI such as OS_File is looked up without --chapter, or with the more explicit --swi switch.
riscos-libsearch
riscos-libsearch answers a different class of discovery question: not "which PRM chapter describes this interface?" but "which library or header exports this symbol?". It searches the indexed export databases for the system libraries and the locally built export tree, so it is useful when you are trying to work out which header to include, which library to add to a makefile, or whether a locally built library is shadowing the built-in one.
Bare queries are interpreted by shape. A name ending in .h is treated as a header lookup; other names are treated as function or define lookups. More explicit switches such as --func, --lib, or --symbols are useful when you already know the kind of result you want.
This is a typical sequence when discovering how to link against a library:
riscos-libsearch jpeg_read_header
Library: JPEG
RISCOS: C:JPEG.h.jpeglib
File: /riscos-built/Export/Lib/JPEG/h/jpeglib
Include: #include "JPEG/jpeglib.h"
Define: jpeg_read_header = jReadHeader
riscos-libsearch --lib JPEG
Library: JPEG
Host Path: /riscos-built/Export/Lib/JPEG
Include Path: C:JPEG.
...
riscos-libsearch --symbols C:JPEG.h.jpeglib
Define: DCTSIZE = 8 - The basic DCT block is 8x8 samples at line 41
...
Use riscos-prm when you need RISC OS API reference material. Use riscos-libsearch when you need build-time discovery for headers, defines, functions, and library variants.
Inspecting files and resources
Displaying file contents
Documentation work often depends on being able to inspect generated files and resource files directly. The general-purpose starting point is riscos-less, which can apply format-aware viewing for many file types, but the environment also provides more specific tools when you need exact bytes, disassembly, or a decoded textual form.
Using riscos-less first
riscos-less is the broadest inspection tool in the environment. It is still the normal less pager, but it loads the build environment's filter chain first, so many files are colourised or decoded automatically before the pager opens.
In practice this means that one command often gives a useful first view of:
- source files such as C, assembler, Pascal, Fortran, shell, Python, Jenkinsfile, Dockerfile, and BBC BASIC text;
- structured text such as JSON, CSV, Markdown, YAML, XML, SVG, and JUnit XML results;
- RISC OS binaries and file formats such as tokenised BASIC, AIF, utility, and module files, AOF files, ALF libraries, DrawFiles, sprites, templates, Toolbox resources, StrongHelp manuals, TBAFS archives, ZIP archives, and Spark or ArcFS archives;
- host-side binary formats such as ELF executables, Mach-O binaries, Python bytecode, certificates, keys, and property lists.
That makes riscos-less the best first stop when you do not yet know whether a file needs a dedicated tool. When the generic filtered view is not precise enough, move to the specialist tools below.
For example:
riscos-less aif32/Example,ff8
riscos-less Resources/Templates,fec
riscos-less results.xml
Hex dumps and disassembly
Use riscos-dump when you need to inspect bytes, words, headers, or offsets exactly as they are stored. Use riscos-dumpi when you need to inspect executable code as ARM, Thumb, or AArch64 instructions.
For example, these commands show the header words in an Absolute file and then disassemble the same binary:
riscos-dump --words aif32/Example,ff8
Offset : 0 4 8 C : Text
8000 : E1A00000 E1A00000 EB00000C EB000284 : ................
8010 : EF000011 0000136C 00000014 00000000 : ....l...........
...
riscos-dumpi aif32/Example,ff8
00008000 : e1a00000 : .... : MOV r0, r0 ; AIF: Decompression branch
00008004 : e1a00000 : .... : MOV r0, r0 ; AIF: Self relocation branch
00008008 : eb00000c : .... : BL &00008040 ; AIF: Zero init branch
...
Sprites, DrawFiles, and object files
Use riscos-dumpsprites to summarise the sprites in a sprite file, validate its structure, or inspect one named sprite in detail. Use riscos-decdrawf to decode a DrawFile into the text form accepted by riscos-mkdrawf. Use riscos-decaof to inspect AOF object files, including area declarations, relocations, debug information, symbols, and disassembly.
Use riscos-mkdrawf when you want a DrawFile to be generated from source-controlled text rather than drawn by hand in !Draw. The mkdrawf description language lets you define objects such as paths, text, font tables, sprites, groups, tagged objects, text areas, options, transformed text or sprites, and JPEG images. It also has variables, macros, loops, conditionals, file inclusion, arithmetic, units, and colour names, so generated drawings can be parameterised in the same way as other build artefacts.
The usual workflow is to keep the mkdrawf source file in the project, build a DrawFile with riscos-mkdrawf, and use riscos-decdrawf only when recovering or reviewing an existing DrawFile. The decoded output is intended to be accepted by riscos-mkdrawf, although external sprite and JPEG output may need filename references to be kept in step.
When you need to move between GIFs and sprite-based resources, use riscos-intergif. It can convert GIF files to sprite files and back, can read Draw files as input, and can also join or split animation frame sequences. This makes it useful both for preparing web-facing images from RISC OS resources and for turning external GIF assets into sprite resources for packaging. The conversion direction is detected from the input file itself, so there is no separate switch to say whether the input is a GIF or a sprite; only -o is needed to name the output.
These commands are typical when checking packaged resources or compiler output:
riscos-dumpsprites --check Resources/Sprites,ff9
Resources/Sprites,ff9: OK
riscos-intergif Logo.gif -o Resources/Logo,ff9
riscos-intergif Resources/Logo,ff9 -o Logo.gif
riscos-mkdrawf logo.mkdrawf Resources/Logo
riscos-decdrawf Resources/Logo,aff > logo.txt
riscos-decaof -drsg o/main
** Header (file o/main)
AOF file type: Little-endian, Relocatable object code
...
** Relocation table
At 000034: Instr[ebfffff1] PC-relative to symbol exit
...
** Symbol Table (file o/main):-
...
riscos-mkdrawf appends the ,aff filetype suffix itself, so the output name given on the command line should be the bare leafname (Resources/Logo); giving Resources/Logo,aff produces Resources/Logo,aff,aff instead.
For the underlying sprite and template formats, see ../appendix/sprite-file-format and ../appendix/template-file-format. For the mkdrawf DrawFile source language, see ../appendix/mkdrawf-file-format.
Templates and Toolbox resources
Use riscos-ccres when you need to convert Wimp Template files or Toolbox Resource files into an editable text form, or rebuild the binary form from that text. This is particularly useful when you want resource data to be reviewable in Git.
This is the usual round-trip:
riscos-ccres Templates,fec Templates.txt
riscos-ccres Templates.txt Templates,fec
riscos-ccres is silent on success in both directions; check the exit status or the timestamp of the output file to confirm it ran.
The tool decides the conversion direction from the input contents rather than from the filename, and text input must begin with either RESF:1.01 for Toolbox Resources or Template: for Wimp Templates. For the editable text syntax itself, see Appendix P: CCres textual file formats.
Do not validate a round-trip by comparing the rebuilt binary file byte for byte with the original. riscos-ccres normalises the output into its own serialisation. The reliable check is to convert the rebuilt binary back to text and compare that text with the source text.
When C code needs stable symbolic names for template icons, use riscos-templateheader to generate a header from the template validation strings. The tool scans indirected text icons, looks for an N validation tag, and emits icon constants in either the default Nettle form or the WinEdit form selected with -t winedit.
That fits naturally after template editing. As with other tools that write a RISC OS-style dotted output path, the directory component (h/ here) must already exist:
riscos-ccres Templates,fec Templates.txt
mkdir -p h
riscos-templateheader Templates,fec h.icons
Editor-assisted lookup
riscos-swi-lsp and editor assistance
riscos-swi-lsp is aimed at SWI-oriented reference work inside an editor, rather than at shell-based lookup. It provides a Language Server Protocol service for RISC OS SWI calls, so an editor can ask for hover help and completions while you write code.
The Language Server Protocol, usually shortened to LSP, is a standard way for editors and IDEs to talk to language-aware tools. Instead of each editor needing its own special plug-in for SWI assistance, the editor speaks the common protocol and the server supplies the language knowledge. In practice that means one SWI-aware server can support several editors with the same core features.
In normal use the editor starts riscos-swi-lsp as a separate process and talks to it over standard input and output. The tool can also listen on TCP or WebSocket transports, but stdio is the usual editor configuration because it is simple and does not require a separate port.
The server prefers to fetch SWI summaries through riscos-prm --summary --no-tables, which gives it current PRM-derived interface text. If that command is not available, it falls back to its bundled SWI database so that hover help and completions still work for many common calls.
The server recognises several common source forms:
- C calls using _swi(...) and _swix(...);
- BBC BASIC calls using SYS "SWI_Name";
- assembler calls using SWI SWI_Name.
For C and BASIC, the server can often decode the supplied registers and infer reason codes for multi-function SWIs such as OS_Byte or OS_File. Assembler support is more limited at present: the SWI name is recognised for hover lookup, but reason-code inference is not generally available there.
Completions are most useful when you have already typed the SWI name and the opening part of the call. The server can then expand a skeleton _swix(...) or SYS "..." call using the known register interface for that SWI.
For example, an editor would typically be configured to launch the command as:
riscos-swi-lsp
If you need to debug a client configuration or connect through a network-aware editor bridge, the alternative transports are:
riscos-swi-lsp --tcp --host 127.0.0.1 --port 2087
riscos-swi-lsp --ws --host 127.0.0.1 --port 2087
This tool complements riscos-prm rather than replacing it. Use riscos-prm when you want direct shell lookup or the full PRM chapter context, and use riscos-swi-lsp when you want that interface knowledge surfaced inside the editor as you write C, BASIC, or assembler.
Related tools
The wider environment also includes tools such as riscos-libsearch for library discovery and StrongHelp support tools for maintaining traditional RISC OS help content. Those tools become more relevant later when documentation needs to connect code, headers, and external references.
Video 9 of Video walkthroughs surveys these and several other supporting tools in quick succession.