Cross-compiling software with GCCSDK

GCCSDK is a cross-compiling toolkit for RISC OS. Cross-compiling means that we can build software on one platform (eg Linux) that will run on another (RISC OS).

Introduction

Often, there are two tasks in moving a piece of software from one platform to another: building the software, and porting the software. The two are interlinked, but the first step is taking the source files (for instance in C or C++) and compiling them for RISC OS. This may show up problems with lacking functionality which we'll have to implement. Once the program is built, the task of porting can begin. GCCSDK provides functionality so that some command line and some X11, SDL and Qt programs can be built and run unmodified on RISC OS. However other programs may require modification, for example writing a Desktop interface or connecting to printer drivers - this will require additional code.

Why cross-compile? In general, the step of building the software is not very interesting. The software already builds in a Unix environment on (for example) Linux, and we would ideally just use the identical setup to build for RISC OS. Unfortunately, the RISC OS build environment is sufficiently different - filenames, different command line tools, different scripting languages and process model - that it's rare to be able to run an identical build on RISC OS. The programmer then has two choices: either write their own build system specifically for RISC OS, or run the existing build system on Unix and cross-compile.

The latter is usually much less work. Additionally, using Unix as a build system allows the use of fast machines (eg multicore desktops and servers with SSDs) rather than slower RISC OS platforms.

Philosophy

GCCSDK's philosophy is to put the intelligence into the toolkit, rather than implementing the porting changes necessary in the codebase of the program being ported. Often, we get source code of programs to port from upstream projects which are rapidly developing. Once the toolkit knows how to translate particular features to RISC OS, we can easily rebuild the latest version of the upstream software without any further modifications. This substantially reduces the work of keeping ported software up to date and bringing across new features.

Indeed, a separate feature of GCCSDK, the autobuilder, takes this a step further. It will look for source code for a package from the Internet -- for example the Debian repositories. It will download, unpack, apply any local RISC OS patches, and try to build the software. If successful, it will then generate zip archives which can be unpacked on a RISC OS machine, but which are also suitable for download by the PackMan packaging system. Putting a package in the autobuilder allows the latest version to be built with a single step.

Installing GCCSDK

Please see the GCCSDK installation instructions for details of how to build the toolkit on a Unix system (Windows and MacOS may work but are less well tested).

Cross-compiling a package

GCCSDK understands a number of standard Unix build systems. We'll consider a number of examples. Once installed, the GCCSDK installation's env directory contains a number of scripts that are frontends to common build tools such as autoconf, make and install. For now, we're going to assume they're installed in /home/riscos/env, but yours may be elsewhere. (It is better to call the tools explicitly, not put them on your PATH).

In these examples $ is the Unix shell prompt - it is followed by commands you type.

Minimal shell script build

A few programs have a very simple build system, which is barely more than a shell script -- eg build-me.sh:

 #!/bin/sh
 gcc -o hello hello.c

ro-path is a script that redirects calls to host tools like gcc to ones that build for RISC OS. For instance:

$ /home/riscos/env/ro-path ./build-me.sh

runs the same script, but 'gcc' is now the cross-compiler. It will thus produce RISC OS executables rather than Linux ones.

Makefile build

More complex programs often use make, for example the instructions may say:

$ make
$ make install

ro-make will call make with appropriate RISC OS adjustments - ie the above turns into:

$ /home/riscos/env/ro-make
$ /home/riscos/env/ro-make install

autoconf

GNU autoconf is a common build system which aims to smooth out differences between (primariiy Unix) systems. For example, it will allow the same program to build on Linux, MacOS and FreeBSD even those arrange their systems in different ways. A typical autoconf build process is:

$ ./configure --some-build-options --with-some-feature
$ make
$ make install

ro-config will run the ./configure script with RISC OS adjustments, viz:

$ /home/riscos/env/ro-config --some-build-options --with-some-feature
$ /home/riscos/env/ro-make
$ /home/riscos/env/ro-make install

Raw compilers

Sometimes you want access to the raw compilers, preprocessor, etc without using the porting scripts. These are also available as:

/home/riscos/env/arm-unknown-riscos-gcc
/home/riscos/env/arm-unknown-riscos-g++
/home/riscos/env/arm-unknown-riscos-cpp

(the Unix convention is for cross compilers to be referred by a 'target triplet' of machine-vendor-operatingsystem which allows multiple sets of tools to coexist)

Other build systems

Many other build systems exist. Some may be amenable to prefixing with ro-path before running them. Others generate Makefiles which can then be executed with ro-make. You may have to experiment with what is suitable for your project. The Autobuilder source tree may provide insights into how other packages handle this.

Paths and libraries

The GCCSDK install consists of two trees:

cross, which is the cross compiler itself and associated libraries env, which is the target environment.

When you run ro-make install, the built files will be installed into env, as if they were being installed on the RISC OS machine. While, in general, it is better to package up the files to create an installable archive (either via PackMan or manually), this can be useful for libraries which you may need to build with. For instance, a graphics program may first need libjpeg building and installing (the autobuilder will do this for you, but other libraries you may have to do yourself). It will install into env, and so the ro-config step of the graphics program will find the library there.

Help

If you get stuck, please contact the GCCSDK mailing list for advice.