How to build RISC OS
Whether you want to build the RISC OS printer stack, the disc-based software or a whole ROM image, the process is pretty much the same:
- download and install the build sources
- initialise your build directory
- select the correct environment
- start the build process
- check the build log for problems
Set up your build directory
Step 1. Download and extract the source code
The ROOL web site has a number of archives full of source code and other build components for producing a particular target. Here are some examples:
Disc - the RISC OS 5 disc image build, with boot sequence, applications, etc. IOMD - the ROM build for RiscPC- and A7000-type machines (those with the old IOMD chipset) OMAP - the ROM build for new OMAP (ARMv7) based machines (Beagle Board, Touch Book, etc.) Tungsten - the latest official, stable ROM build for the Iyonix TungstenDev - the latest beta Iyonix ROM (using head revisions of sources from CVS)
There are also archives containing (parts of) the RISC OS CVS repository but you can ignore these for the time being. There is documentation if you want to find out more about building RISC OS from CVS. See the Remote write access to the ROOL CVS repository page for more information. (Importantly, note the ’’checkout’’ script to get the right source for your target platform. A checkout of CVS HEAD won’t work)
Before you can do a build, you will need the RISC OS build tools. If you don’t already have it, this is available from the RISC OS Open site here. Unfortunately, this is a commercial product and it is not yet possible for RISC OS to be built using a free toolchain such as GCC. This is because the RISC OS source code and the toolchain were developed side-by-side so the former relies on a lot of unique features in the latter.
Assuming you already have the build tools installed on your RISC OS machine, you simply need to download the appropriate archive, e.g. the OMAP ROM build, decompress it and extract the contents. ROOL provide a RISC OS application called UnTarBZ2 which can be used to decompress and extract the archive contents. You can also decompress the archives (transform them from a .tar.bz2 into a .tar) using the bunzip2 tool on Linux or a tool such as 7-zip on Windows.
At this point, the build has been extracted into a directory on the RISC OS machine. In this document, we will assume that you’ve put it here:
ADFS::HardDisc4.$.RISCOS
and that you already have the RISC OS build tools installed here:
ADFS::HardDisc4.$.AcornC/C++
Your build directory which will contain some or all of the following subdirectories:
bsd - source code published under a BSD-like licence castle - source code published under the Castle shared source licence cddl - source code published under the CDDL licence gpl - source code published under a GPL licence mixed - source code published under multiple licences Prepare - a tool to initialise the build directory Products - contains 'Products' files (described later)
You are now just two simple steps away from being able to start the build process.
Step 2. Initialise the build directory
In the RISC OS filer, navigate into the “ADFS::HardDisc4.$.RISCOS.Prepare” directory and run (by double-clicking) the “!Run” file. This will launch the build initialisation process. You should follow the on-screen prompts and if you’re not sure of the correct answer to give to a question, just select “Yes”.
Step 3. Start the “Builder” application
The Builder application is a graphical user interface front end for the build process and is very useful (if not essential) if you want to build more than a single component in one go. The “Prepare” process will normally start Builder automatically, but if it doesn’t, you can find and run it from here:
ADFS::HardDisc4.$.RISCOS.Apps.!Builder
When it’s running, you will see the Builder icon on the iconbar. You will probably need to set up Builder so that it knows where your build tree is. This is pretty simple and just involves opening the menu over the Builder icon and selecting “Register build tree”. Drag the build directory (e.g. RISCOS in this case) to the registration window and click “Save”. Now you are ready to go…
Select a build environment
One single build tree may be used to build a number of different targets. To decide which one it will generate, you need to select an “environment”. There are quite a few to choose from, including:
ROOL.Disc ROOL.IOMD32 ROOL.OMAP3 ROOL.Tungsten
In the following example, we will build using the “OMAP3” environment, as this is the one for the OMAP ROM image, which is the source tree that we downloaded.
Note: a build directory may list all of these environments as being available, but the build for any other environment will likely fail, e.g. trying to build a Tungsten ROM image from the OMAP archive because the archive only contains source code for the components used for a very specific target in order to keep the size down. In theory, you could have a build directory which includes the source code to every RISC OS component, in which case most, if not all, of the environments could be selected and then their target built.
So to recap a few steps:
- Run !Builder and it will appear as an icon on your iconbar.
- The first time you run it, you will need to tell it where your build directory is.
- To do this, ADJUST (right) click on the iconbar icon.
- This opens the “Register build directories” window.
- Drag and drop your “RISCOS” build directory into the window.
- Click “Save”.
Now Buider is set up and will remember this information the next time you start it.
- SELECT click on the iconbar icon
- The “Build options” window will open with your build directory listed.
- Click on the menu icon or “Environment”.
- A menu of build environments should open, including “ROOL.OMAP3”.
- (If you don’t get this menu, you have registered the wrong directory as a build directory. Use the iconbar menu and re-register the correct directory.)
- Select the “ROOL.OMAP3” environment.
Start the build process
Once you have selected your build environment in the Builder window, you then need to select the build options for a particular build. In this example, you will want to select:
- “List”
- “Clean”
- “Clean all”
- “Export headers”
- “Export libraries”
- “Export resources”
- “Make ROM”
- “Install ROM”
- “Join ROM”
You can safely ignore the section of this window for “Version numbering”; it is very rare that you will ever want to use this section (if ever).
If you use !Builder on an ARMv7 Platform (e.g. Beagleboard, Pandaboard) you have to turn off Alignment exceptions before starting the build.
Now you can click on the “Build” icon and a task window should appear containing lots of output from the build process as it runs. There will also be lots of disc activity – don’t be surprised if a build such as this takes half an hour or more to complete. Some warnings may also appear in a throwback window.
! It is vital that you don’t change the currently selected directory (CSD) during the build process as this will cause things to fail to build correctly in strange ways. It is best to leave your machine alone while a build is in progress (although you don’t have to!).
Check the build log for problems
This is something of a black art. In the very simplest terms, if the thing you were building has popped out of the build (into “Images” for a ROM image or “Install” for disc-based software) then you’re most of the way there.
However, you should still look for significant warnings and errors in the log file. Most errors that matter will be prefixed by:
AMU: ***
so this is a good thing to search for. However, during the “Clean” and “Clean all” phases, there are lots of components which attempt to wipe object files and binaries that might not exist. This can lead to lots of:
AMU: *** Not found ***
errors. These can safely be ignored. Hopefully, all of these components will be fixed over time so that they no longer do this. The best advice is to ignore errors from these phases and search forward in the log from the start of the next phase, e.g.
Starting phase export_hdrs ...
Some of the most serious errors are:
AMU: Don't know how to make '...'
and:
AMU: *** exit (1) ***
then you know that some component has failed to build and there is something very wrong.
There’s another error (warning actually) which can lurk like a time bomb in your build. I can’t remember exactly what it says, but I think it’s something like this:
ARM Linker: (attribute difference = {32bit}).
This is basically saying that some of a C program is built 32-bit neutral and other bits aren’t. This can lead to things appearing to be fine until you are running the program and you hit the bit of code which might not be 32-bit on a 32-bit system. Bang!
It is beyond the scope of this document to explain how to fix a build when you do find these errors but RISC OS Open will do their best to ensure that all of the ‘standard’ builds work before they are released.
Further information
You’re probably wondering what is going on behind the scenes when you do a build. This is a quick overview of the underlying process so that you can create your own builds.
There is a central file called:
BuildSys.ModuleDB
this contains a list of every source component in the build and gives it an associated tag so that a given component can be built in a specific way by simply refering to the tag. For example, the “ModuleDB” might contain a couple of lines like:
UK ASM castle.RiscOS.Sources.Internat.Territory.Module Internat UK Italy ASM castle.RiscOS.Sources.Internat.Territory.Module Internat Italy
So if we want to build the UK territory module, we can simply refer to the “UK” tag. Using the “Italy” tag will build the Italian territory module from the same sources.
So where are these tags used? The tags required to build a particular product are listed in a “components” file. These are all stored in the following directory:
ADFS::HardDisc4.$.RISCOS.BuildSys.Components
You will see that there are already some components files in the “ROOL” subdirectory. You can treat these as a template if you want to create your own components file for a product. Note: you can pass build parameters to a component in this file, and you can list the same component several times with different parameters.
The “ROOL.Disc” components file lists the “DesktopBoot” tag twice:
DesktopBoot -options INSTDIR=<Install$Dir>.HardDisc4 COMPONENT=Boot DesktopBoot -options INSTDIR=<Install$Dir>.HardDisc4.Utilities COMPONENT=ResetBoot
in order to build different aspects of that component and put them into a different place in the resulting build.
Each components file needs to have a complementary “Env” file in the “Env” directory. This is an Obey file which sets certain environment variables so that the build system knows which components file you are wanting to build, where the root of your build directory is, etc.
Thus, you will find inside Env the following Obey files:
Env.ROOL.Browse Env.ROOL.BuildEnv Env.ROOL.Disc Env.ROOL.Printers
It is these Obey files that !Builder runs when you select an environment from its menu and that menu is built by scanning the “Env” directory when you have selected your build directory in the main window.
During the build process, all of the output which appears in the task window is also spooled into a text file. This file is placed into:
BuildSys.Logs
and has an unique name (which is adjusted each time you do a build so that older builds don’t get their logs overwritten straight away). The precise format of the log file name is actually quite complicated; suffice it to say, if you want to create your own product, you will probably need to speak to the team at RISC OS Open in order to get your product allocated.
How does all this tie in with CVS?
Just having your a list of components which are required to build your product inside BuildSys isn’t enough information for you to come back at a later point and build your product again. You also need to record the versions of every component.
(If you’re really worried about details, you also need to preserve your build tools so that you use the same version of the compiler, etc.)
This version information is stored in a textual file within the “Products” directory. This contains a file for each of the basic ROOL products, including:
Products/ROOL/BuildEnv Products/ROOL/Browse Products/ROOL/Disc Products/ROOL/Printers
Each of these files simply lists all of the components that are required to build that particular product, by referring to the location of the component in the cvs repository and the cvs tag which identifies the revision of that component.
A very simple example might look like:
rool/RiscOS/Sources/Programmer/BASIC BASIC-1_30 rool/RiscOS/Sources/Programmer/BASICTrans BASICTrans-1_03
Every time we accept a submission for a new version of a component and add it to the cvs repository, we will give that revision an unique tag so that these product files can refer to it.
When we build a tarball containing binaries (built components rather than sources) we will include the files which define the product so that you can see what versions of various components were included in the build.
What’s next?
Well, there are a million and one things that we could write about doing builds but rather than bore you to death with all that, we’ve put together a Build FAQ page which covers all of the most common questions.
But for those of you who really love being bored to death, there’s some additional information available on the Developer's guide to RISC OS builds page (covering exciting topics such as what a component or environment is) and the Builder page (for information about what all of Builder’s pretty buttons do).