On the 19th May 2007, Castle Technology Ltd published the license document for the release into the public domain of the RISC OS sources. In support of this, RISC OS Open (ROOL) published the first batch of source code and a binary build environment (BBE) with which to build these sources, followed on the the 20th October 2007 by a second batch and a new BBE which supercedes the original. A third batch of sources was released on the 22nd February 2008 and a fourth on the 26th April 2008.
On the 18th of October 2008, ROOL released Batch Five. This greatly increases the number of components available for both disc and ROM builds – in fact, there are only a handful of modules missing when compared to a full IYONIX RISC OS 5 ROM image.
Our How to build RISC OS guide is the ideal reading material for performing both ROM and disc builds, as it describes the !Builder application which is used for building multiple components in one go (such as all the modules that link into a ROM image).
The documentation below is still an important read for developers as it describes installation and use of the sources and tools as well as how to build components individually.
NOTE: as we haven’t processed and released all of the RISC OS sources yet, there may still be certain components and header files which are not available in either the source archive(s) or build environment. As a result, some components might currently fail to build, usually with an error stating that something within the Export directory could not be found. As we move further through the process of releasing sources, this should become less and less of a problem.
As a developer or if you’re just curious, your first questions will probably be:
This page will attempt to guide you through the answers to these questions. As more sources are released, the answers will probably change so if you run into problems, take a look back here because this page may have been updated.
First things first, you will need to download the source code archives from our downloads page, including the Binary Build Environment
sources-1234.tar.bz2 and @sources-5.tar.bz2.
To extract the contents of these archives on a RISC OS machine, you will need a tool like bzip2. It used to be possible to download this from a site such as riscos.info.
You should install the bzip2 tool somewhere on your run path, for example by copying it into !Boot.Library.
Extract the tar file from the bzipped archive using the a command like:
<notextile>*</notextile>bzip2 -d bbe/tar/bz2
This should decompress the archive and leave you with a tar file. The contents should be unpacked using a tool such as SparkFS. There are various settings which you need to have set up correctly to untar these files but that should be covered in the SparkFS documentation.
(Basically, we created the archives on a Linux machine onto which we had put the files using Sunfish. This means that the files might have a ,xxx suffix which indicates the filetype. Various untar tools for RISC OS might handle this correctly, but others might not.)
If you decompress and untar the archives on a Linux/UNIX system, you should have no problems copying them over onto your RISC OS machine using something like NFS (e.g. Sunfish).
Each archive contains a top-level directory called
RiscOS. In the source code archives, the
RiscOS directory contains source code (as you might expect), whereas in the BBE archive the
RiscOS directory contains all of the elements of the BBE. These can be combined, or simply unpacked into the same directory in order to ensure that the sources reside within the BBE, e.g. the
RiscOS directory will contain something like:
If you look inside the Sources directory, you should see various directories containing the sources to a number of RISC OS components:
Finally, you need to install the main build tools and header files from your C/C++ installation into the build. These are a commercial product so if you do not own a recent copy of these tools, drop an email to firstname.lastname@example.org and we’ll advise you on how to buy them.
Assuming you have the C/C++ tools installed on your RISC OS machine (you will have a directory somewhere called AcornC/CC++) we have provided a couple of scripts which do the installation for you.
Make sure your machine has “seen” the AcornC/CC++ installation (run the !SetPaths application within that directory) and then run both of our scripts:RiscOS/Library/InstallTools RiscOS/Export/InstallCLib
This only needs to be done once. If you later delete the contents of the
Export directory in order to fully clean out all exported components, you must run the
InstallCLib script again.
Before you build something, you need to ensure that the desktop environment is suitable for your build process.
One thing we have found which helps is to ensure that image filing systems like StrongHelp and SparkFS are not running as this can cause problems if files such as StrongHelp manuals or zip archives are involved in the building of a given component. Most of the time, you will not need to do this but if you see things like *copy operations failing, this might be the reason.
Another thing which helps is to avoid having thing doing periodic disc activity during building a component (e.g. fetching email) especially if that activity includes setting the currently selected directory (CSD).
So, on to setting up your environment. This is mainly a case of ensuring that the computer has ‘seen’ some applications which are required by the build process and setting up some system variables to tell it where tools and header files, etc. are.
Open the directory RiscOS/Apps and double click in the !perl application. This will help you to avoid problems if you have a newer version of !perl installed on your machine.
Next, run one of the ‘Env’ scripts to run for setting up all of the rest of the build environment. Any one of
RiscOS.Env.ROOL.BatchThree will do if you’re just going to build an individual component using its !Mk file, however when you choose between them from the menu in !Builder, you’re also choosing which set of components you wish to build.
Over time, we will provide more Env files. They are useful for specifying what the target architecture you are building for is, e.g. Iyonix, RiscPC, etc. and 26-bit vs 32-bit. That sort of thing.
At this point, you should be able to actually build things!
There is an application called RiscOS.Apps.!Builder. This is a front end for the build process and is very useful for builds which involve more than one component. However, as of Batch Three, there are still no structured builds included so the only way to build components is individually.
To do this, you should navigate your way into the component in question. I’ll use the BASIC module as an example. Navigate your way (using the Filer) into RiscOS.Sources.Programmer.BASIC.
You will see some task obey files:
Pretty much every RISC OS component will have a similar set of task obey script in its root directory (sometimes they don’t have a leading ! in the filename, but that doesn’t mean anything significant). These are used to build the components for certain phases of the build process. In general, the scripts you will find will be one of these:
For our example of building BASIC, you are only really interested in !MkClean and !Mk. Normally, you would clean a component before starting work on it then iteratively make changes to the source, build the component to test it, make more changes, build it again, etc. until you are happy with your changes.
At the point where you are satisfied that your changes work as they should and don’t break anything else, you would normally rebuild the component from clean just to check you’ve not broken its build process. If all went well, you’d be ready to submit your changes (along with documentation for those changes).
Note: unless a problem is very minor, we will not accept submissions of modified RISC OS sources back into the main ROOL repository if we find that they don’t build. This isn’t because we’re being cruel – it’s just that we won’t have time to spend fixing everyone else’s code. You should also try to avoid making any changes which introduce new compiler warnings into the build process (ideally, we’d like to have everything build without any warnings but we’re not anywhere close to that at the moment).
As for the layout of the average component, you will normally find that they are organised something like this:
Returning to the example of building the BASIC module, you would do a sequence like this:
At the moment, you should to email an archive of your changes to email@example.com along with a change log (example format given below). Sometime soon, we will get an FTP service running on the riscosopen.org domain where you can drop an archive of your changes, which includes the change log documentation. Keep an eye on the announcements page of our site for more info.
Every update for a component should include information which will be useful not only in explaining the change, but the reasons for the change, any impact that it is expected the change will make and how the change was tested.
Here’s an example which has been lifted from the logs for the BASIC module:
Summary: Fixed bug spotted on csa.programmer in BASIC CASE statements. Detail: The expression evaluation in the BASIC WHEN statement had an omission where it could skip past a syntax error without generating any error. For example, "WHEN (R%>>25) AND 1)=1 : do something" would not return an error because the expression is complete and evaluated upto the "AND 1". Once this is found to not match the condition of the CASE, BASIC searches forwards for the next ",", "WHEN", "OTHERWISE" or "ENDCASE", skipping over the ")=1" part. I've changed this so that, after the expression is evaluated and found to not match, BASIC already checks to see if the next char is a ",". If not, we check for a ":" or CR before scanning forwards. Any other char is a syntax error. Admin: Tested on Iyonix RO504.
That is exactly the sort of information which should be included in your submissions (preferably also in that format). Ideally, include that in the email to us and as a file called “log/txt” in the root of the source archive which you are submitting.
If you are submitting a new component to be added into the RISC OS sources, it is vitally important to include information about what the component is actually for! From our work opening up the sources, we’ve been constantly frustrated by coming across components which we’ve got no idea what they actually do so we’ve no idea whether or not we actually need them.
Your first port of call should be our site here at www.riscosopen.org (either the documentation in our Wiki, Forums or the Bug tracker). Try to see if anyone else out there has had the same or similar problems because we may have already answered the question.
Next, there may also be information available from the wiki at riscos.info which could help you.
If you’re still stuck, try posting to the forum to see if anyone else can help. If that doesn’t get you anywhere, you should add a bug report to our bug tracker.
Don’t forget, this documentation lives within a wiki which you can also edit. If you find something which is clearly wrong, undocumented or could just be documented better, don’t be afraid to edit or add pages yourself!
We hope this crash course in building RISC OS components helps.
— The ROOL team