Showing changes from revision #3 to #4:
Added | Removed | Changed
!Builder is the program that’s at the heart of the RISC OS build system. Whether you’re building a ROM image, a hard disc image, a collection of standalone programs, or even the build tools themselves, you’ll be doing it with the help of Builder.
h2(#build%20directories). Build directories
All builds occur inside a build directory. The build directory contains all the source files, all the build tools, all the intermediate files, and all the final output files. The first time you run Builder a window will pop up asking you to register the initial build directory. Whether you’ve fetched your source code from CVS or extracted it from an archive, the build directory is always the “RiscOS” folder – so drag that folder into the window to register it with Builder. Note that currently Builder can only work with ‘merged’ folders – i.e. the contents of the “castle”, “bsd”, “mixed”, “gpl”, etc. folders must have been merged together into one single “RiscOS” folder.
If you want to change the location of your build directory or register additional directories, you can do so by selecting the “Register build tree” option from the iconbar menu.
Each build directory allows you to build one or more products. E.g. the Tungsten source archive contains the files needed to build the ‘Tungsten’ product, i.e. an Iyonix ROM image. What a product is and how it should be built is described in three seperate files:
Knowledge of the above three types of file and their role in the build system is important if you want to be able to understand the rest of this document.
Note that even though each product is generally designed to only work with one environment file and one component file, source downloaded from CVS or in archive form will typically come with all environment files and all component files, due to the files for all products being located in the same folders within CVS. Be sure that you only select an environment/component file that will work with the sources that are in your build directory!
An additional fact about the environment files is that each environment file actually explicitly specifies which components file to use. This allows the same set of components to be built with differing environment options, e.g. in order to build localised ROM images for different countries. Each environment file would set the Locale system variable to a different setting, but all of the files would reference the same components file, so that the ROM images contain the same set of modules.
For more information about products, environments, and components, see the Developer's guide to RISC OS builds page.
h2(#build%20stages). Build stages
Clicking on Builder’s iconbar icon will open the main window. And in the ‘Build options’ section of this window are a number of check boxes for selecting the different build stages. It’s important to know what each stage does and when it must be used.
Build stages are executed in the following order:
This stage simply causes Builder to output a list of each component in the components file, together with the components build options. This may not seem like a very useful feature to you or me, but it was an important feature at some point in time!
For each component in the components file, Builder will invoke AMU on the component’s makefile and ‘build’ the ‘clean’ target. As you can probably guess, this has the effect of cleaning the source folder for each component. This will typically delete all the object files, cmhg-generated header files, and linked output files. It will also delete the contents of RiscOS.Sources.Internat.Messages.Resources (a folder that’s used as a staging area for the contents of ResourceFS)
However, the Clean phase doesn’t clean everything, hence the presence of the ‘Clean All’ stage…
h4(#clean%20all). The ‘Clean All’ stage
For each component in the components file, Builder will invoke AMU on the component’s makefile and ‘build’ the ‘clean_all’ target. This is very similar to the ‘clean’ target, but cleans extra stuff which clean_all does not. For example it will strip the dynamic dependencies from the makefiles.
TODO – Document any other things which clean_all does.
Even though this is the ‘Clean All’ stage. there are still parts of the build tree that don’t get cleaned. E.g. the Export folder and the Install folder are left in tact (more on the purpose of these folders later).
h4(#export%20headers). The ‘Export headers’ stage
This stage causes Builder to build the ‘export’ target of each makefile, with PHASE=hdrs. Or in laymans terms, it populates the RiscOS.Export folder with all the shared headers that the other components rely upon. The main source of headers is the HdrSrc component (located in RiscOS.Sources.Programmer.HdrSrc), but many other components will provide headers too (e.g. each module will typically have a header listing all its SWI numbers and reason codes).
h4(#export%20libraries). The ‘Export libraries’ stage
This stage causes Builder to build the ‘export’ target of each makefile, with PHASE=libs. Or in laymans terms, it builds all the static libraries that the other components rely upon. For example many C modules use the callx library to make it easier to use callbacks.
After each library is built, it will be copied to the RiscOS.Export.<APCS>.Lib folder, ready for linking with other components.
h4(#export%20resources). The ‘Export resources’ stage
This stage causes Builder to build the ‘resources’ target of each makefile. For components which store files in ResourceFS, this causes those files to be copied into the RiscOS.Sources.Internat.Messages.Resources folder, ready for being built into the locale-specific Messages module.
h4(#make%20rom). The ‘Make ROM’ stage
This stage causes Builder to build the ‘rom’ target of each makefile. This will compile, but not link, each component that is destined to be placed in a ROM image. Apart from the HAL, all the components which get built during this stage will be modules.
h4(#install%20rom). The ‘Install ROM’ stage
This stage causes Builder to build the ‘rom_link’ target of each makefile. For assembler modules and the HAL, this simply involves copying the module into the ‘Install’ folder, ready for placing into a ROM image. For C modules this will involve performing a partial static linking of the module with the Shared C Library; although the module won’t be physically linked to the library, it will have been patched such that the module will only function if both the module and the Shared C Library are at the correct locations within the ROM image. Builder keeps a running total of how much ROM image space each module has used, and uses this to tell each component where its final resting place will be.
At the end of the stage, Builder will print out a table listing each module and its intended location within the ROM image.
h4(#join%20rom). The ‘Join ROM’ stage
This stage uses the ‘romlinker’ tool to link the contents of the RiscOS.Install folder into a ROM image, with the items linked in the order denoted in the components file. For the most part this linking process just involves concatenating the files together, but romlinker also performs some important additional functions:
If the link operation succeeded then the finished ROM image will be placed in the RiscOS.Images folder.
This stage causes Builder to build the ‘bbe’ target of each makefile.
TODO – What does this do?
h4(#install disc). The ‘Install disc’ stage
This stage causes Builder to build the ‘install’ target of each makefile. For the HardDisc4 disc image, this will build each disc-based component and copy it into the RiscOS.Install.HardDisc4 folder. For the build tools (BuildHost product) this will build each build tool and copy it into the appropriate location within the live build tree. Other products (e.g. CTools, Printers) install their files to differing locations.
h2(#other%20options). Other options
The other options available in Builder’s main window aren’t very significant any more, and are best left alone.
If you’ve registered a build directory with Builder then clicking select on the iconbar icon will open the main window. The first thing you’ll want to do is to make sure the right build directory and environment are selected. Select the build directory first and then the build environment second, as the contents of the environment list is dependent upon which build directory you have selected.
Selecting an environment will cause Builder to run the corresponding environment file, thus setting up your machine so that it’s ready for the build. This configuration step is vitally important, even if you plan on using the numerous !Mk, !MkSA, etc. scripts to build components individually. Without selecting an environment in Builder (or running the corresponding Env file manually) the code may be compiled for the wrong CPU type, be linked against the wrong libraries, or use the wrong set of header files, etc.
Once you’ve got the right build directory and environment selected, you’re ready to select which build stages you want to run. Generally speaking:
Once you’ve selected the right options, simply hit the ‘Build’ button and wait for the build to complete. While the build is in progress a taskwindow should open displaying the build log. The log also gets saved to the RiscOS.BuildSys.Logs folder, should you need to refer to it later on.
Although you can use the computer while the build is in progress, make sure that you don’t do anything that will cause the currently selected directory (CSD) to change, otherwise the build will most likely break, sometimes in subtle ways that don’t result in the build failing with an error message.
h2(#see%20also). See also
Here are some other pages containing information about the RISC OS build system: