Setting Up a Build Client
On every commit, we build all targets of Rockbox and present the build status in a build table
. This is done in a distributed fashion where build clients gets assigned a target at a time to complete and returns the results back.
For this to work as good as possible and to keep the total build time to a minimum, we use a set of build clients. The more clients, the shorter build times and the more appreciated it'll be by the developers.
Who can join?
Literally anyone can join. You don't need a monster machine. The buildmaster distributes builds according to each client's speed, so even relatively slow machines are able to contribute.
You also don't have to keep the client running all the time. The system dynamically adjusts to clients coming and going. So you can keep it running 24/7, or turn it on for a while every now and then. It's all up to you. Every little helps.
- One or more (preferably all) of the cross-compilers, a native gcc and SDL
- At least 5GB disk space available
- Preferrably 1Mbit/s or better network network uplink. We have servers doing fine with a 384kps upload link, but much lower will not be very useful.
- git, ccache, curl and zip installed
- Be sure to have the cross compilers, ccache and libsdl-dev installed and in the $PATH
- Check out (or copy) a clean rockbox repo to a new directory. Make sure the tree is clean, i.e. no modified files.
- Make sure that you can successfully build for all platforms you intend to add to your -archlist
- Download http://git.rockbox.org/?p=www.git;a=blob_plain;f=buildserver/rbclient.pl;h=4ae61f36d71c67a73948a770f1cb6845313d7ce0;hb=HEAD into it
- Download http://git.rockbox.org/?p=www.git;a=blob_plain;f=buildserver/runclient.sh;h=51c7a0f69de29aa68f90898c237115797f23ac0b;hb=HEAD into it
- Edit runclient.sh:
- Invent a personal (unique) name for -clientname=
- Set -username to your IRC nickname, so we know who runs the client.
- Make up any value for -password. It is not yet used.
- Parameter -archlist specifies which builds you can build, i.e. which compilers you have. It should be a comma separated list such as "arm,sh,m68k,mipsel,sdl,arm-eabi-gcc444".
- Start runclient.sh. If you want runclient to start automatically at reboot, you can set up a cronjob with the "@reboot" time specification.
- Subscribe to the rockbox-rbclient mailing list. (This is important, since it's the only way we can reach you.)
Why not distcc
distcc is a great and fun project, but unsuitable for use by us. Since distcc still preprocesses each file locally, hand over the file to the remote servers to get build and then gets the object file back, it requires slow
compiles and fast
networks to be really efficient.
In contrast we have relatively fast
compiles and a slow
network, to the extent that transfering the file over and getting an object file back is slower than simply compiling it locally. This is of course also due to the somewhat slow network between our build servers.
The build system is written by BjornStenberg
How it works
- The rbmaster.pl server runs on buildmaster.rockbox.org
- Each client maintains a constant connection to buildmaster, waiting for build commands.
- Every time a commit to the main source is done, the git server (git.rockbox.org) connects to buildmaster server and requests a new build.
- The buildmaster loads the list of targets ("builds") and starts distributing them to the connected clients.
- The past performance of every client is used to calculate its' speed.
- The sum of all client speeds is used to calculate a fastest possible build time.
- The builds are then allocated to the clients, giving each client as much work as he can do within the time.
- Clients without performance history (i.e. new clients) get a single small build, for benchmarking.
- When all builds have been handed out, and a client reports ready for more work, speculative building begins:
- The uncompleted builds are handed out again, so multiple clients are now building the same target.
- When a client completes a build, that same target is cancelled on all other clients building it.
- This means that as the end of the build round approaches, more and more builds are being cancelled. This is intentional.
If you want every nitty gritty detail, look at the source code to the build master script
Fun stuff to do with a client
Using the -commandhook option in recent clients, it's possible to run a script every time the server sends a command. This can e.g. be used to get notified whenever a build is started. See hook.sh
for an example script that shows current build status in the title of the terminal window, and that also talks to you to keep you informed (using the festival TTS engine).
Copyright © by the contributing authors.