The 19th May Release

The 19th May Release (Batch One)

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) have published the first batch of source code and a binary build environment (BBE) with which to build these sources.

NOTE: At present, both the build environment and sources which have been released are incomplete (from the point of view of building a full RISC OS ROM or disc image). As such, you should treat this document as your main guide to building RISC OS components over the How to build RISC OS guide for the time being (however, that is still a useful read).

ALSO NOTE: as we haven’t processed and released all of the RISC OS sources yet, there are certain components and header files which are not available in either the source archive(s) or build environment. As a result, some components will 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:

1. how do I get get everything installed?
2. how do I prepare the build environment?
3. how do I actually build something?
4. how can I submit my changes back to ROOL?
5. what do I do if I have problems?

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.

How do I get everything installed?

First things first, you will need to download the three archives from our downloads page called ‘bbe.tar.bz2’, ‘sources.tar.bz2’ and ‘patch-one.tar.bz2’ (we also released an archive called gpl.tar.bz2 but you don’t need to download this).

To extract the contents of these archives on a RISC OS machine, you will need a tool like bzip2. You can download this from a site such as riscos.info
(note: you want the second bzip2 download, version 1.0.2-2). 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 something like 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 SuSE 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).

Now you should have a directory called RiscOS which contains all of the dearchived sources (when you unpack the sources.tar archive) and another directory called RiscOS which contains the BBE (when you unpack the bbe.tar archive) plus another archive of patches (when you unpack the patch-one.tar archive).

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:

• Apps – some apps required for building
• BuildSys – bits required by the build system
• Env – scripts for setting up the environment
• Export – where headers and libraries export to
• Library – build tools
• Module – modules that may be needed during builds
• Sources – the source files

Make sure you merge the patch-one.tar archive contents over the combined BBE and sources directory – i.e. only merge it after merging the other two archives!

If you look inside the Sources directory, you should see various directories containing the sources to a number of RISC OS components:

• Apps
• Desktop
• FileSys
• HWSupport
• Internat
• Lib
• Networking
• Programmer
• SystemRes
• Utilities
• Video

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 info@riscosopen.org and we’ll advise you on how to buy them. Or, you can purchase your copy online here

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:

this only needs to be done once. However, you should run them both again if you are just installing the patch-one.tar archive over an existing build directory.

How do I set up the build environment?

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. At the moment, only the RiscOS.Env.ROOL.BuildEnv is useful for this.

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! :)

How do I build something?

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 One, there are 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:

• !Mk
• !MkClean
• !MkRom

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:

• Clean, MkClean – clean the component (delete any built parts of it, such as the binary itself and any object files) and strip any dynamic dependencies from the end of the makefile.
• Mk, Ram, MkRam – build a RAM-loadable component (as you might find inside your !System.Modules directory or in the Apps directory).
• Rom, MkRom – builds the object file(s) which are suitable for (static) linking into a ROM image. If there is no Mk or MkRam file in the component, this is often an indication that this file will also build the RAM-loadable version of the component.
• Export, MkExport, MkHdr, MkLibs – exports the headers and/or library objects from a component into the appropriate part of the RiscOS.Export directory.
• Install, MkInst, MkInstall – build the component and install it into a subdirectory within the RiscOS.Install directory.

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:

• Makefile – the main makefile. We also provide a selection of shared makefiles within the RiscOS.BuildSys.Makefiles directory. Newer RISC OS components use these shared makefiles and we’d encourage software authors to adopt and extend them as they can make a dramatic difference to the compexity of the makefiles within each component (compare BASIC’s makefile to that of DDEUtils or RiscOS.Sources.Lib.PRISMLib to RiscOS.Sources.Lib.Configure).
• Doc, Docs – some documentation relating to the component can often be found in a directory like this. Often, this is related to the development of new features to explain how the implementation works.
• s – ARM assembler source files.
• hdr – ARM assembler header files specific to the component (some may be exported by an export phase into the shared RiscOS.Export directory).
• c – C source files.
• h – C or C++ header files. As with assembler header files, some may be exported in an export phase into the RiscOS.Export directory.
• cmhg – special header file for the cmhg tool which defines the header and various other things for C modules.
• cpp – C++ source files.
• o, od, etc. – object files.
• rm – RAM-loadable relocatable module binaries are built into here.
• Abs – absolute (application) binaries are built into here.
• Resources – other resources (often split into different territories and platforms) are stored in here.

Returning to the example of building the BASIC module, you would do a sequence like this:

1. Run the !MkClean script
2. Load and make your changes to source files in side ‘s’
3. Build the BASIC module by running the !Mk script
4. Try out your changes by loading the module from within the rm directory
5. Repeat the editing and testing until you’re happy with the changes
6. Confirm that it builds from clean
7. Archive up the component (or the changed files)
8. Send them to ROOL along with change documentation for folding back into the source tree

How do I submit back to ROOL?

At the moment, you should to email an archive of your changes to code@riscosopen.org 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.

What if I have problems?

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