Reference guide34Pyromaniac and Runtime Tools

riscos-run is the simplest local runtime command. It starts a clean RISC OS instance, sets the current RISC OS directory from the host working directory, and executes one command line inside that session.

The normal form is riscos-run <riscos-command>. If Pyromaniac options must be supplied first, place them before -- so the wrapper knows where the RISC OS command begins. If no arguments are supplied, the wrapper falls back to the interactive gos shell mode.

Everything after the command position is joined into one RISC OS command line, so ordinary host-shell quoting is still needed when the RISC OS command contains spaces or shell metacharacters. Output and return status are reflected back to the host shell in the normal way.

VNC can be enabled explicitly with --vnc, or implicitly through ROBUILD_VNC when the environment is configured to expose graphics sessions. Other pyro switches can also be passed through before the separator when the wrapper needs lower-level control.

riscos-basic is the convenience wrapper for starting BBC BASIC locally inside the build environment. With no arguments it opens an interactive BASIC prompt. With arguments it invokes the RISC OS *BASIC command using those arguments.

This is a one-shot wrapper like riscos-run, not a persistent session. It is therefore a good fit for quickly running one textual or tokenised BASIC program, or for checking a short interactive BASIC sequence in a clean environment.

The program named on the command line may be a tokenised BASIC file, usually suffixed ,ffb, or a textual BASIC file, usually suffixed ,fd1. The runtime command itself still uses the RISC OS leafname.

The command line is appended directly to the RISC OS *BASIC command, so common forms such as -quit and -chain behave as they would on a native system. The same wrapper-level --vnc behaviour described for riscos-run also applies here.

The wrapper passes arguments through directly to *BASIC. This entry documents the wrapper behaviour, not the full native *BASIC command reference.

riscos-gos starts an interactive Supervisor prompt in a fresh Pyromaniac instance. It is the high-level wrapper for manual command-by-command work when you want something closer to a booted RISC OS command line than a one-shot wrapper provides.

The wrapper loads the default runtime configuration and the extra gos.pyro configuration needed for the shell-style environment, including system boot and the reset behaviour expected for an interactive session. The session ends when the usual RISC OS quit command is used.

Unlike pyro-server, this is still a single attached session. When the shell exits, the Pyromaniac instance is discarded rather than being reused for later host-side commands.

pyro is the low-level Pyromaniac entry point exposed directly by the environment. It starts a fresh RISC OS instance, applies requested configuration, loads modules or PyModules, and then executes commands, entry points, or binaries inside that instance.

Execution actions supplied on the command line are grouped by type rather than taken strictly in argument order. If exact sequencing matters, use --action or a configuration file. For persistent command-serving sessions, move to pyro-server instead.

A bare pyro invocation with only --load-module boots a minimal environment that supplies almost no commands beyond GOS, even after loading an ordinary module: things such as Modules and Help are not available because the supporting internal modules that normally provide them are not loaded. Add --load-internal-modules to boot the fuller internal module set before loading your own module, or list what is actually available first with --list-commands.

YAML configuration files passed to --config-file can contain the top-level keys config, variables, modules, and execute. The modules section can load RMA, ROM, internal, or Python modules, and the execute section can express ordered actions such as commands, system boot, input injection, waits, resets, and host-file execution.

Useful debug names commonly used in practice include start, execute, swi, trace, traceswi, traceswiargs, fsexpand, fspath, fssave, tickers, vectors, and modcommands.

Advanced wrapper-specific environment variables include PYROMANIAC_ISOLATED, PYROMANIAC_NO_PRIVATE_PKGS, PYROMANIAC_ENVDIR, PYROMANIAC_RUN, and PYROMANIAC_RUNSHELL.

Use --list-actions, --list-debug, --list-config, and --help-config when you need the exact runtime-generated detail for action payloads, debug names, or configuration keys.

pyro-server starts a long-lived Pyromaniac environment and keeps it alive while a host shell or host command runs. During that time, pyro-client can send RISC OS commands into the same live instance without restarting Pyromaniac for each command.

The command accepts the same core switch set as pyro before --. After that separator, the remaining words name the host command to run instead of opening an interactive shell.

Every command sent through pyro-client sees the same RISC OS state, so loaded modules, system variables, current directory, and application state persist from one client call to the next. When the host shell or host command exits, the server session is terminated.

Important server-side controls live in the pyroserver configuration group:

pyro-client is the companion command to pyro-server. It sends one RISC OS command line into an already-running persistent Pyromaniac session.

Because the server remains alive, later client invocations can reuse the same modules, variables, filesystem state, and process state established by earlier commands. This is the main reason to use the server/client pair instead of repeated riscos-run calls.

Input and output are forwarded through the client, so pipes and interactive commands are supported. If the RISC OS command reports an error, the client normally returns status 1, unless the server configuration is set to suppress that, return a more specific code, or print the return code textually.

By default the client also mirrors the current host working directory into the RISC OS environment when that directory is inside the visible filesystem tree. Pressing control-C sends an escape character to the running RISC OS command, and the client requests return-code reporting from the server using a private OSC escape protocol.

The return-code and directory-mirroring behaviour are therefore configured on the server side rather than by client-only switches.

riscos-modservices inspects the live resident module chain and reports which service calls each module appears to handle. It is a runtime debugging tool for identifying service ownership, checking handler coverage, or confirming which module claims a particular service number.

Without a filter, the command lists every service number it can determine for resident modules that have service handlers. With -s, it prints only the modules that appear to handle that one service value.

Each output line begins with the module name followed by one or more service numbers written in hexadecimal with an & prefix. For non-standard handlers, the first reported service may be prefixed with an annotation character: * means a non-standard entry sequence was decoded successfully, - means a handler was present but no handled services could be determined, ? means the handler could not be interpreted reliably, and ! means a standard service entry with no service list pointer.

The command requires a live RISC OS environment because it enumerates currently resident modules and inspects their service handlers. It is therefore complementary to pyro --list-modules: use --list-modules to see what is loaded, and riscos-modservices to inspect service-handler ownership.