WARNING: this documentation is not currently valid due to the binary build environment, which was published on the 19th May, being a first step towards the full build environment. As such the process described below probably doesn’t work at the moment… We will update this document when things change.
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:
In order to construct a complete build tree, you will need to download both sections of the sources and install them into your build directory. This is as simple as downloading a couple of tarballs from the ROOL site and extracting their contents in turn into the same directory.
For this document, we will assume that your build directory is called:
ADFS::HardDisc4.$.RISCOSThus, once you have downloaded the tarballs for both the RISC OS build environment, the complete Shared Source RISC OS sources and the complete Third Party RISC OS sources, you can extract them into your build directory which will then contain the following subdirectories:
Apps – some build-related applications BuildSys – data relating to and defining various builds Env – build environment setup scripts Export – this is where exported libraries and header files go Images – this is where built ROM images are placed Install – this is where built disc-based components are placed Library – some build-related binaries Modules – some build-related modules Sources – the root of the main source tree Tools – the root of some additional sources (for build tools) Utilities – the root of some additional sources (misc utilities)Finally, you will need a copy of the C++ Tools Suite which, if you don’t already have it, is available from the RISC OS Open site. A script is supplied in Library (called “InstallTools”) which will install various tools from your installed C++ Tools Suite into the build directory.
For example, the “Library” directory contains a subdirectory called “Acorn” and it is assumed by the build process that the “cc”, “c++”, “cfront”, “link” and “objasm” tools are located in here. As these are only available in the C++ Tools Suite, they need to be installed into “Library.Acorn” when you first set up your build directory.
Once you have all of these bits in place, you are ready to start building RISC OS.
To make things simple, ROOL have included a number of ‘products’ and their associated build environments in the tarballs. These include:
ROOL.BuildEnv ROOL.Disc ROOL.Printers ROOL.BrowseIn the following example, we will build the product called “BuildEnv” followed by the “Printers” product.
“BuildEnv” goes through all of the main components in the RISC OS sources and gets them to export their shared header files into the “Export” directory. It also builds all of the main shared libraries and exports them into the “Export” directory.
The “BuildEnv” product forms the basis of lots of other ROOL products because we don’t want to have to go through the time-consuming process of exporting all of these header files and building all of the shared libraries for every product so it’s useful to do it separately. Thus, other products need only build the specific things that they need beyond the standard “BuildEnv”.
However, if you’re writing your own product, you’d be wise to include all of the components which it needs to build so that it’s not dependent upon our BuildEnv product.
The “Printers” product builds the USB Printers stack, including the !Printers application itself, all of the supporting modules and some related applications. It assumes that you have already done a “BuildEnv” build (this helps keep the “Printers” build from taking too long).
The first thing we need to do when selecting our build environment is to run the application called:
ADFS::HardDisc4.$.RISCOS.Apps.!BuilderThis 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.
Now !Buider is set up and will remember this information the next time you load it.
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” and “Export libraries”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).
Now you can click on the “Build” icon. This should open a task window containing the build process as it progresses. There will be lots of disc activity and lots of things will be output to the task window. 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!).
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.
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.ModuleDBthis 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 Internat.Territory.Module Internat UK Italy ASM Internat.Territory.Module Internat ItalySo 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.ComponentsYou 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.PrintersIt 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.Logsand 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.
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 four basic ROOL products:
Products/ROOL/BuildEnv Products/ROOL/Browse Products/ROOL/Disc Products/ROOL/PrintersEach 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_03Every 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 verions of various components were included in the build.
Well, there are a million and one things that we could write about doing builds but we’re probably going to have to wait until there are sources released and people start doing builds. Then we’ll get a feeling for the most common questions and problems, at which point we will put a FAQ together.