Cross-compile Perl for RISC OS with perlriscos

You will finish with the documented build sequence for a RISC OS Perl cross-build, including the unusual but required replacement of miniperl with a native host build. This guide follows perlriscos(1) from the perl-doc package installed here as version 5.38.2-3.2ubuntu0.6.

Allow at least an hour for the toolchain, source tree and two builds. The exact compile time depends on the host and the cross compiler. You need a working GCCSDK cross compiler, REXEN, Perl source, a native build of Perl for the host, and a shell account that can write the source and build directories. The manual points to GCCSDK and REXEN as the required external components.

This is a build workflow, not a package installation recipe. It does not install anything system-wide, run a service, or require sudo in the documented steps. Keep the source and build output in a disposable working directory until the result has been tested.

1. Prepare the two build inputs

Build a native copy of Perl for the host first. Separately, place the Perl source you intend to cross-compile in its own directory. The native build supplies the executable needed later because the cross-compiled miniperl cannot run on the host.

$ mkdir -p "$HOME/perl-riscos-work"
$ cd "$HOME/perl-riscos-work"
$ # Build a native Perl copy in one directory, using the normal Perl build instructions.
$ # Put the source to be cross-compiled in another directory.
$ ls

The final ls output is host-specific. Checkpoint: you should be able to identify both the native build directory and the separate cross-build source directory before continuing. Do not use one directory for both jobs, or you may lose track of which miniperl is usable on the host.

2. Select the RISC OS hint file

Change into the source directory that will become the RISC OS build, then run Configure:

$ cd "$HOME/perl-riscos-work/perl-cross-source"
$ ./Configure

When Configure asks for the hint file, select the RISC OS hint file. The manual says that the default answers to the remaining questions are usually sufficient. Read each prompt rather than accepting defaults blindly, because your compiler paths and build layout may differ from the assumptions of the source tree.

For a non-interactive Configure run, the documented hint-file argument is:

$ ./Configure -Dhintfile=riscos

Checkpoint: Configure must complete its setup for the cross-build source. If it cannot find the compiler or REXEN, stop there and fix the toolchain or environment first. Re-running later build commands will not repair an incomplete configuration.

3. Build the cross-compiled miniperl

Start the first build target from the configured cross-build source:

$ make miniperl

The expected result is counter-intuitive: this should build miniperl and then fail when it tries to run that executable. The failure is part of the documented cross-compilation procedure. The binary targets RISC OS, so a normal host shell cannot execute it directly.

Checkpoint: distinguish this expected failure from an earlier compiler or configuration error. The useful question is whether the cross-compiled miniperl was produced before the attempt to run it. If the compiler itself fails, inspect that failure first. Do not skip straight to make with a missing or incomplete executable.

4. Replace miniperl with the native executable

Copy the miniperl executable from the native host build you prepared in step 1. Use it to replace the cross-compiled miniperl in the RISC OS source tree:

$ cp /path/to/native-build/miniperl /path/to/perl-cross-source/miniperl

Replace both paths with the real directories on your machine. This is the key hand-off: the rest of the build uses a small Perl interpreter that can run on the host while producing the RISC OS-targeted Perl build. The manual specifically instructs you to copy the native executable over the cross-compiled one.

Warning: verify the source and destination paths before pressing Enter. A mistaken destination can overwrite the wrong build artefact. If you copied the wrong file, restore the intended native miniperl from the native build and repeat the copy with explicit paths. Keep the native build until the cross-build is complete.

5. Complete the build

With the native miniperl in place, return to the cross-build source and run the ordinary build:

$ cd /path/to/perl-cross-source
$ make

This time, miniperl is available to run on the host, so it can complete the remaining build work for the RISC OS target. The manual does not promise a particular success message, output directory or final filename. Treat a non-zero exit status as a failed build and keep the compiler output for diagnosis.

Checkpoint: the command must finish with exit status zero before you copy or distribute any resulting binary:

$ printf 'build status: %s\n' "$?"
build status: 0

If the command fails after the replacement, confirm that the copied file is the native host executable and that you ran make in the same source tree configured in step 2. Also check that the toolchain and REXEN remain available. Do not assume that the expected make miniperl failure explains every later error.

6. Choose the safer alternative when appropriate

Cross-compiling Perl for RISC OS is complicated by design. The manual notes that a binary version of Perl is available from cp15.org, which may be preferable when you need a usable interpreter rather than a repeatable source build. Check that source and binary choice against your compatibility and provenance requirements before using it.

There is no service rollback in this workflow because the commands only operate in the build directories. To abandon the attempt, stop using the cross-build directory and retain or remove it according to your own source-retention policy. Do not delete the native build until you have confirmed that the cross-build no longer needs its miniperl.