Developer's guide to RISC OS builds

Developer documentation

» Developer’s guide to RISC OS builds

Other pages on this website have discussed how you would go about running a build that’s already been perfected, but what if you want to tweak it, or create a new one from scratch? That’s what this page is here to help you with.

What is a component?

Before we start, a quick word about the term component, which you’ll see used all over the place. Broadly speaking, a component is a program built for the target platform, usually a module or an application, although it can also be an executable file (usually a build tool) or a library. The kernel and HAL are two special-case components.

The term is applied slightly differently for source control and building purposes.

• For source control, a component is the group of files which form an individual repository in git, and which are jointly assigned a version number. You’ll find a VersionNum file (and sometimes a VersionASM file) in the root directory of what’s considered a component for source control purposes. VersionNum and VersionASM files are automatically maintained when you commit changes to the repository using the perl script srccommit.

• For building, a component is defined by the location of a Makefile. In rare cases, a single Makefile can be used to build multiple components – which one is determined by the COMPONENT variable passed into the Makefile on the command line (this is all managed by the build system, only the author of the Makefile need be concerned about it).

A example of the former of these is the USB system. RiscOS/Sources/HWSupport/USB/USBDriver contains the VersionNum file, and you’ll note that most of the git tags are of the form USBDriver-n_nn. But the Makefile is a level deeper than this, in RiscOS/Sources/HWSupport/USB/USBDriver/build.

If this seems complicated, don’t worry – the vast majority of components use neither of these tricks, and the source control component is the same thing as the build component.

Env files

The files in RiscOS/Env are a collection of Obey files; they are used to set up critical paths and system variables, and load support modules needed to perform a build. When you select an option from the “Environment” menu in !Builder, you’re actually running one of the Env files.

Much of the work is done by RiscOS/Env/!Common, but it is unlikely that this will need to be changed. Each of the other Env files set up a small number of system variables that define what is unique about the build. These system variables would otherwise end up being build-time options for multiple components, so having them set globally helps maintain consistency across the build.

• Locale: determines the language of resources files installed.
• Keyboard: which keyboard handlers (layouts) are built in – often “All” for desktop builds. A bit of an oddity in that it’s really only an option to the InternationalKeyboard module, but placing the option here enables a single Components file to be shared by variants of the same product aimed at different international markets.
• Machine: selects a variant file in Hdr:Machine which sets an assembler variable. Used to switch between different IOMD hardware variants, so now deprecated in favour of the HAL. Normally use “32” here; Tungsten was an exception among HAL machines, because it contains a partial implementation of IOMD for the podule bus.
• System: specifies general properties of the kernel (such as stack formats) for the benefit of modules. Generally deprecated, use “Ursula” if you’re creating a new Env file.
• UserIF: specifies a theme for resource files. Each embedded customer generally wants their own theme, ROOL currently only distributes a few distinct desktop themes, called “Morris4”, “RO400”, “Ursula” and “Iyonix”.
• Display: generally useful only for embedded products. Determines whether 50Hz (PAL) or 60Hz (NTSC) TV outputs are selected. Even some embedded products ignore this and read a setting from NVRAM.
• ImageSize: sets the size of the ROM image as a whole. All modules in a ROM image must fit within this size, and any spare space is padded out. Not relevant for disc builds.
• HALSize: sets the size of the HAL that’s in use. Without this information the HAL won’t know where the OS image is inside the ROM, and the OS image won’t know how large it should report itself as being. Not relevant for disc builds.
• Build: sets which Components file to use. See next section. Often of a similar if not identical name to the Env file.
• APCS: currently the procedure calling standard should be “APCS-32”.

Many of these are used in source code directly – for example, you’ll see widespread use of GET Hdr:APCS.<APCS> in assembler source files. However, you should generally not do this for Locale because it’s undesirable to fill the source tree with lots of duplicated resource files when typically only a small number of them need to be translated, especially for embedded products. So instead use LocalRes: to access non-themable language-specific resource files and LocalUserIFRes: to access themable language-specific resource files. These paths are both set up by !Common.

All of ROOL’s Env files are stored inside RiscOS/Env/ROOL for namespacing reasons.

Components files

The files in RiscOS/BuildSys/Components/ROOL are text files, the input to the srcbuild program which is the back-end to !Builder. They are essentially a recipe for a ROM build or disc build – it says which components need to be included, which libraries and header files are required by those components, and what build switches need to be applied to those components.

Because one Makefile can build multiple components, components are not referred to directly by path, but instead by a unique symbolic name. These names are looked up in the file RiscOS/BuildSys/ModuleDB, which provides not only the location of the Makefile, but information about which build phases should be applied to the component:

• ASM: typical assembler module, may be called with any build phase (clean, clean_all, export_hdrs, export_libs, resources, rom, install_rom, install or bbe)
• BAS: currently functionally equivalent to ASM, but used when the component is written in BASIC rather than assembler
• C: same as ASM except that rom_link phase is used instead of install_rom phase
• RES: only clean, clean_all, resources, install or bbe phases used – intended for components consisting of resources files which don’t need to be compiled or assembled, merely copied into ResourceFS (in the resources phase) or the disc image (install phase)
• EXP: only clean, clean_all, export_hdrs and export_libs phases used – intended for components that provide header files and/or libraries
• DATA: after the module chain, a ROM can include one or more binary blobs, typically at fixed addresses; these DATA components are called with the same build phases, but aren’t linked into the module chain
• BBE: use for pure BBE (“Binary Build Environment”) components such as RiscOS/Library – only ever called by BBE phase
• KERNEL: there must be exactly one of these in a main ROM build and none in an expansion ROM build – can have a specified position (for use with a HAL) and is not linked into the module chain
• HAL: may be zero or one of these in a main ROM and none in an expansion ROM – not linked into the module chain
• LOADER: expansion card loader – only one of these is allowed, and only in expansion ROMs

The ModuleDB also specifies subdirectories and filenames within RiscOS/Install to be used during ROM assembly to hold the relocated but unlinked modules. These are structured to overcome historic 10-character filename and 77-file-per-directory limits.

You will also note that it is possible for a component’s type to be overridden in the Components file. This is most often used to force only the export phases to be executed on a component which would otherwise generate a binary – typically when some other component needs SWI numbers or other definitions from the component’s public header file(s).

Products

The projects in the Products group are used to perform version control across a complete build. Each project is a git repository which contains many git submodules, where each submodule is used to pull in the source to a component. Compared to the approach of storing all the OS source code in a single git repository, using submodules provides a lot of flexibility, both in terms of which versions of components are used, and where the source for those components is stored.

Checking out products

The master branch of each product should be used for building the latest development version. If you want to checkout a stable build, you can do that by selecting the appropriate tag.

Note that when fetching a development build, you’ll need to pass the --remote option to git submodule update. This tells git to fetch the latest version of each submodule, not the version/commit that’s recorded in the parent project. E.g.:

git pull && git submodule update --init --remote

prodcommit

If you need to make changes to a Product (e.g. adding or removing a component), use the prodcommit script from Support/RepoTools. This will automatically generate a standard format log message for your commit.

This contrasts with the srccommit script that should normally be used for committing changes to components.

Products available

The code names used for Products files are not always immediately meaningful, so here’s a quick description of the ones currently hosted on ROOL’s site:

BCM2835 are used with the Broadcom chip for the Raspberry Pi educational platform.

BuildHost are for building (as much as possible of) the toolchain that is used to build RISC OS. It is assumed that the build machine is Iyonix class, though the binaries should be compatible with earlier machines. This is a disc build.

CTools is a product definition used by the Desktop Development Environment, though a number of components it calls out are closed source due to licence restrictions.

Disc is for building the HardDisc4 disc image, there’s also a cut down PlingSystem to support pre RISC OS 5 machines.

IOMDHAL is for building a 32-bit HAL-based ROM for IOMD-class desktop machines: A7000, A7000+ and Risc PC.

OMAP3 is for building an OMAP3 ROM image suitable for BeagleBoards and other OMAP3-based machines.

OMAP4 is for building an OMAP4 ROM image suitable for PandaBoards and other OMAP4-based machines.

Tungsten are for building a ROM for the Iyonix PC.

S3C and Batch1to6 are used for building various prototype targets, these are very much a work in progress.

BCM2835Pico and OMAP3Live and are specific products put together for one off special events.

Some hints and tips

For disc builds, you’d normally use build phases export_hdrs, export_libs and install. The install phase is labelled “Install disc” in !Builder.

For ROM builds, you’d normally use build phases export_hdrs, export_libs, resources, rom, install_rom and join.

In either case, you can often shorten the rebuild time by missing out one or more of the phases from the start of the process – the export phases aren’t needed if you haven’t changed any headers or libraries, and the resources phase isn’t needed if you haven’t changed any resources.

What next?

Now you’re familiar with the terminology we use, you should proceed to one of the following pages to learn more about the build system:

• How to build RISC OS – A step-by-step guide for setting up a build tree and performing a build
• Builder – Detailed information about what each option in !Builder does
• Git cheatsheet – More information about working with Git
• Build FAQ – For anything else not covered above