Showing changes from revision #1 to #2:
Added | Removed | Changed
NOTE: This page is under construction.
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.??? option from the iconbar menu.
If Each you look inside the???build directory folder allows of you your to build directory one then or you’ll more see several components products files . Each E.g. file the represents Tungsten a source different archive contains the files needed to build the ‘Tungsten’ product, i.e. an Iyonixbuild environment. The build enviornment represents the end product which is being built – e.g. the Tungsten file describes how to build an Iyonix ROM image, image. What a product is and the Disc file describes how to it build should the be HardDisc4 built image. is Different described build environments have different dependenices, in terms three of seperate which files: build tools and source components are required. Since all components files are held in the same folder inCVS, this means that even if you’ve only downloaded (or extracted) the Tungsten build tree you’ll still end up with components files for most of the other products. Attempting to use those other components files with your build tree is likely to result in failure due to the build tree lacking some or all of the required components.
h2(#get%20ready). Getting ready to perform a build
If Knowledge you’ve of registered a build tree with Builder then clicking select on the iconbar above icon three will types open the main window. At the top of file and their role in the window build you’ll system see is two important icons if to allow you want to select be the able build directory and environment. To get ready to perform understand a build, first select the build rest directory, of then this select document. the environment. Then move on to select thebuild stages and other options.
Each Note time that you even select though an each environment product Builder is will generally run designed a couple of scripts behind the scenes to configure only your work computer with ready one for environment performing file the and build one – component adding file, the source right downloaded build from tools to your Run$Path variable, setting the right compiler options for the required CPU CVS type, or etc. in This archive configuration form step will is typically vitally come important with if all you environment plan files on and using all the component numerous files, !Mk, due !MkSA, etc. scripts to build components individually. Without performing this step the code files may be compiled for all products being located in the wrong same folders within CPU CVS . type, Be be sure linked that against you only select an environment/component file that will work with the wrong sources libraries, that or are use in the your wrong build set directory! of C library headers.
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.
h2(#build%20stages). Build stages
Underneath Clicking on Builder’s iconbar icon will open the build main directory window. and And environment in selection the boxes ‘Build there 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. Builder will run through the different stages in a fixed order, and for each stage which is enabled it will perform the relevant actions for each component.
The Build stages are performed executed in the following order:
This stage simply causes Builder to output a list of each component in the components file, together with the build options for that component. So really it’s not something that you’re likely to find yourself using on a day-to-day basis.
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 export a header enumerating all the SWIs that the module provides).
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
h4(#link%20rom). This The stage Link 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 aROM stage image. Apart from theHAL, 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 are only of interest to ROOL and are best left alone by ordinary users!
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 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.
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. A taskwindow should open displaying the build log. The log will also be saved to the RiscOS.BuildSys.Logs folder.