Introduction

One of the purposes of RISC OS Pyromaniac is to provide a means by which RISC OS tools and modules can be run on other systems. Whilst usually this is by starting a RISC OS environment and running those tools, it is ocassionally useful to be able to run host tools, and call in to RISC OS to run the tools. For example, using cross-compiling tools to build a component, and calling the RISC OS environment to test it.

The Pyromaniac command server provides one way of doing this, with a persistent RISC OS environment within which commands may be run. With the command server, a RISC OS environment can be provisioned, and when needed commands can be run within it.

Components

There are two components to the command server - the pyro-server tool, and the pyro-client tool.

The pyro-server tool works in a similar way to the pyro.py tool, but instead of exiting once the system has completed booting and running its commands, it remains running, and instead runs either a specified host command, or your current shell. When the command or shell exits, the RISC OS environment will be terminated.

The pyro-client tool can be run whilst within the command or shell started by pyro-server. It will communicate with the server to run the commands supplied to it within the RISC OS environment. Input and output will be supplied to the RISC OS command, so interactive tools and pipes can be used. Errors will be reported with a return code of 1, and for a return code is set explicitly it will be returned. The use of ctrl-C will send an escape character to the currently running process.

Every command executed is executed within the same environment. This means that if you load modules, set environment variables or change any of the state of the system, it will persist from run to run.

Usage

Interactive

For interactive invocation, you might start the server with just a simple invocation:

$ scripts/pyro-server

This will invoke a shell within which the pyro-client can run. Exit the shell with exit, ctrl-D, or any equivalent for the shell.

The pyro-server tool may be invoked with any of the configuration commands accepted by the pyro.py tool. For example, the command line may include the loading of modules, the setting of system variables, or any configuration commands. It may be most useful to bundle all the configuration into a configuration file and use the --config-file switch. The options for Pyromaniac are terminated by --, and may be followed by a command to run in place of the shell.

For example, to run a BASIC program you might use a sequence like:

$ scripts/pyro-server --load-module modules/BASIC,ffa
$ scripts/pyro-client /MyProgram
$ exit

Commands run through the pyro-client tool can be passed through pipes.

$ scripts/pyro-client help modules | grep Internet

RISC OS commands which return an error, or which set a non-0 return code, will return the non-0 return code in the host system.

Scripted

Most invocations of the server will not use the interactive form, but instead will wish to invoke another process. For example, to invoke the Make tool, the following server invocation might be used:

$ script/pyro-server --load-module modules/BASIC,ffa -- make

Configuration

The server has all the same configuration options that the standard pyro.py tool has, together with a few configuration options of its own. The default configuration is set up to be hopefully the most useful settings for interactive or automated use.

There are currently 3 configuration options in the pyroserver group.

`pyroserver.report_rc`

When the client is used, it can report the return code from the command that was executed when the RISC OS command exits. This is taken either from the return code if one has been set, or set to 1 if the command run returned an error. This return code will be set as the status from the client itself by default.

However, this can be disabled by setting the pyroserver.report_rc option to no. Or it can be replaced by a textual representation of the return code by setting the option to text.

`pyroserver.port`

The port used by the server is configurable. It defaults to 18794, but if you wish to run multipe servers this can be changed.

`pyroserver.change_directory`

When the client is run it will check the directory that you are in and attempt to mirror this directory within the RISC OS environment. This means that if you cd into other directory and do run a client command cat, you will see the directory you have changed to in the host. This only works when the directory is actually within the tree that RISC OS can see, obviously.

If this feature is not required, it can be disabled by setting the pyroserver.change_directory option to no.