View source

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 [[Using GCCSDK|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 <tt>env</tt> directory contains a number of scripts that are frontends to common build tools such as <tt>configure</tt> (autoconf), <tt>make</tt> and <tt>install</tt>.
For now, we're going to assume they're installed in <tt>/home/riscos/env</tt>, but yours may be elsewhere.
(It is better to call the tools explicitly, not put them on your PATH).

In these examples <tt>$</tt> 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 [https://wiki.osdev.org/Target_Triplet '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 [[Source_repositories_overview|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. If you need to upgrade GCC, you can delete this and rebuild GCC.  Don't put anything else in here.
* '''env''', which is the RISC OS target environment with subdirectories ''include'', ''lib'', ''man'', etc -- roughly equivalent to the /usr directory on a native Linux system, but populated with RISC OS binaries you have built

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 knows 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|GCCSDK mailing list]] for advice.