Beginner's guide to ROM builds

Developer documentation

» Beginner’s guide to ROM builds

This page aims to be a step-by-step guide to help people who are unfamiliar with the ROM build system to build their first ROM image.

Requirements

• A basic knowledge of how to use RISC OS
• Access to a RISC OS machine (real or emulated) on which to perform the build. RISC OS 4 or above is recommended, RISC OS 3 machines will struggle.
• A copy of the ROOL C/C++ suite (also known as the DDE, “Desktop Development Environment”). This is a commercial product which can be purchased through the ROOL store. Owners of old copies of the DDE (Acorn or Castle branded) will need to upgrade.

Deciding what to build

RISC OS uses ROM images that are customised to different machine types. Use the table below to work out which “product” you need to use to build a ROM that’s suitable for a particular machine.

There is also a “Disc” product, for building the base hard disc image; see the notes at the bottom of this page for the extra steps necessary to build that.

Getting and building the source

1. Grab the source. You have two options for getting the source: To download one of the nightly source archives, or to fetch the absolute latest source from the git server.
   1. Downloading a source archive: The source archives are on this page. Note that the archives all have a “Dev” suffix, indicating that they contain sources for components which are still under development and may be unstable. Once you’ve downloaded it, you’ll want to use !UnTarBZ2 (also available from the above page) to extract it.
   2. Fetching source from git: This is best done from a Linux or Windows machine (native RISC OS git is still in its infancy). Read on for details of the procedure under Linux/Windows.
      1. Make sure you have a git client installed (this guide assumes command-line git)
      2. Find the item you’re interested in in the Products group on gitlab. Note that unlike the old CVS setup, there are no “Dev” products – each repository contains both the development and release/stable versions.
      3. Click on the item to open gitlab’s main page for that repository
      4. Click the ‘Clone’ button to reveal the URLs.
      5. Enter "git clone " into a terminal window, followed by the HTTPS URL, e.g.:

         $ git clone https://gitlab.riscosopen.org/Products/BCM2835.git

         This will clone the repository into a new folder (“BCM2835”). Note that if you have a gitlab account, you’ll probably want to use the SSH URL instead, as SSH is typically more convenient if you’re going to be pushing/submitting changes later on.
      6. Each ‘Product’ repository is just a collection of git submodules, so now we need to initialise and pull those:

         $ cd BCM2835
         $ git submodule update --init --remote

         (Note the use of the ‘—remote’ option to make sure each submodule is updated to point to the latest development code)
      7. If you don’t have a suitable network filesystem (e.g. Sunfish or Moonfish) that you can use to copy source files to/from your Linux and RISC OS machines, do: ‘tar -cjvf ./ro_source.tar.bz2 ./’ to pack the tree for transfer to RISC OS. It can be unzipped with the !Untarbz2 application found here)
2. Get the source tree ready for building.
   1. At a new location (i.e. on your RISC OS machine), run Apps.!Prepare to set up the build tree. This will copy a few folders around to where the build system needs them, along with installing copies of the C/C++ compiler binaries. Note that the C/C++ tools will have to have been seen by the filer beforehand.
   2. Register the source tree with !Builder.
      1. Run !Builder (located in the same Apps folder as !Prepare)
      2. Open !Builder’s icon bar menu and select “Register build tree”
      3. Drag the build directory (the directory containing the ‘Apps’ folder) to the registration window
      4. Click ‘save’. !Builder will remember the registered build trees between sessions, so this registration is a one-time step each time you set up a build tree in a new location.
3. Build the code!
   1. Note that it is advised that you only perform a build if the filer hasn’t seen the C/C++ tools. This is because some of the environment settings the C/C++ tools make conflict with those of the build system. Therefore if you’ve just set up a new build tree and ran the Prepare script, you will have to reboot before attempting to compile the code.
   2. Start up Builder and click the icon bar icon to bring up the main window
   3. Select your build tree and then the appropriate build environment. Note that even though the source you downloaded was for a specific machine type, Builder will list all the products that it knows how to build. It’s important that you select the right one for your build tree, e.g. ROOL.BCM2835 for building a Raspberry Pi ROM.
   4. For the first build, check ‘Export headers’, ‘Export libraries’, ‘Export resources’, ‘Make ROM’, ‘Install ROM’, and ‘Join ROM’. For subsequent builds using the same build tree you’ll usually only need ‘Make ROM’, ‘Install ROM’ and ‘Join ROM’. See the Builder page for more information about what these different options do.
   5. Hit ‘Build’ and hope everything is working right. It will take around three quarters of an hour for the code to build.
   6. If everything went OK, the ‘Images’ folder should contain a new ROM image with a name like ‘aUI800-00’. If not, panic.

Building custom ROMs

OS developers will often want to customise the ROM images they build, e.g. to enable debug output for particular modules, or to enable the debug serial terminal. Customising the ROM in this way is somewhat beyond the scope of this document, so please take any questions you have to the forums.

Building the hard disc image

Building the disc image differs from building a ROM image in two ways:

• Selection of build options: You’ll want to select ‘Export headers’, ‘Export libraries’, and ‘Install disc’
• Output directory: The disc image is output to the Install.HardDisc4 folder.

Note also that the disc image is created as a set of separate files, which should be installed by copying them to a blank hard disc/SD card under RISC OS. Additional tools are required if you want to create an image file which can be written to a disc by ‘dd’, Win32DiskImager, etc.

Fetching updated sources from git

If you’ve got an existing clone of a repository, in most cases you can just execute git pull && git submodule update --init --remote in order to fetch the latest changes from git. Creating a fresh clone of the repository every time you want to update is discouraged as it will consume a lot more of ROOL’s bandwidth than an incremental pull & update.

Submitting changes to git

Get in touch with ROOL, they can provide gitlab accounts to those who need it.

Further reading

• Builder wiki page
• Build FAQ wiki page
• How to build RISC OS wiki page
• Developer's guide to RISC OS builds wiki page
• Notes for building RISC OS on the A9Home wiki page