Managing the build-server and build-spaces
Configuring the build-server
The utilities provided in the app-admin/buildserver-scripts use two configuration files, default versions of which will have already been installed. The first configuration file, and the only one of interest here is /etc/buildspaces which is used to provide configuration information relating to the build-spaces which we have created. As you can see from the example below the file is well documented with comments and therefore fairly self-explanatory.
Whilst the default values should be suitable if you have followed this guide exactly some minor modifications may be required. If you have installed the build-spaces under a different path you will need to modify the BUILDSPACEROOT entry. If you have installed additional or fewer build-spaces you will need to modify the BUILDSPACESXX and BUILDSPACES32 entries.
# Path to the directory containing the build-spaces
BUILDSPACEROOT="/mnt/buildspaces"
# List of build-spaces on the same architecture as the host
BUILDSPACESXX="x86-64bit-server x86-64bit-workstation"
# List of build-spaces requiring linux32 to be executed prior to chroot
BUILDSPACES32="x86-32bit-server x86-32bit-workstation"
# Path to the directory containing the repositories
REPOSROOT="/mnt/repositories"
# Gentoo rsync location and options
GENTOORSYNC="rsync.gentoo.org::gentoo-portage"
GENTOORSOPT="--archive --delete --quiet --timeout=180 --exclude=/distfiles --exclude=/local --exclude=/packages"
# Should we run auto-patch --sync when synchronising the live repository
# and if so which options we should pass
AUTOPATCHSYNC="no"
AUTOPATCHSYNCOPTS="--quiet --sync"
# Repository rsync options
REPORSOPT="--quiet --delete --archive --no-D --delete-during"
# Should we run auto-patch when synchronising a testing repository
# and if so which options we should pass
AUTOPATCHTEST="no"
AUTOPATCHTESTOPTS="--quiet --copy-files --apply-patches"
# Should we run rebuild-portage-caches inside the build-space when
# synchronising a testing repository.
AUTOREBUILD="yes"
The second configuration file is located at /etc/auto-patch-portage and is only used by the auto-patch-portage application when the Hacking Networked Solutions patch-set for Gentoo Linux is to be used. As both AUTOPATCHSYNC and AUTOPATCHTEST are disabled by default we shall not discuss them further here.
Configuring the build-spaces
The utilities provided in the app-admin/buildspace-scripts use a single configuration file, a default version of which will have already been installed. As before the default values should be suitable for most installations however the BUILDSPACE_NAME entry, highlighted below, should be modified in each build-space to match the name of the build-space as configured on the build-server. The KERNELS entry, also highlighted below, should be modified to reflect the kernel sources packages in use in the build-space.
# Name of the build space
BUILDSPACE_NAME="x86-64bit-server"
# Base path for logs
LOGPATH="/var/log/autobuild"
# List of configuration files to protect from updates.
CONFFILES="aliases bashrc buildspace clock hosts layman.cfg locale.gen make.conf resolv.conf ssmtp.conf"
# List of kernel sources which should not be automatically cleaned.
KERNELS="sys-kernel/gentoo-sources sys-kernel/xen-sources"
Synchronising the live repository
Usually when synchronising the portage tree one would use the emerge --sync command. As we are using a much more complicated arrangement for the portage tree than is common it is not surprising that the emerge application is incapable of synchronising such a layout. When we first installed the portage tree into the "live" repository we used the rsync application as we had nothing better. In the previous section we installed the build-server utilities which provided a more complete solution.
As you can see from the example below we can now use the sync-repositories application to synchronise the "live" repository and any patch-sets we have decided to use with a single command.
Synchronising the "live" portage tree...ok.
Synchronising the auto-patch patch-sets...ok.
Assuming that synchronisation worked as intended we can create a crontab entry to run the script daily at 6am so that we can start each day with a relatively up-to-date local copy of the portage tree and any patch-sets we are using in our "live" repository.
As you can see we have specified that we want any output sent to the root user. Feel free to modify the time that the script runs but please remember that it is considered rude to synchronise your tree more than once a day without good reason as the synchronisation process places a considerable load on the Gentoo mirrors.
PATH=/usr/local/sbin:/usr/bin:/bin
MAILTO=root
#Mins Hours Days Months DOTW Job
0 6 * * * sync-repositories --sync-live
Synchronising testing repositories
Once we have synchronised the "live" repository with the external mirrors, so that we have an up-to-date copy of the portage tree and any patch-sets we are using, we can synchronise the testing repositories so that they are using the up-to-date copy too. As you can see from the example below we have used the sync-repositories application again only this time we have used the --sync-test option. We have also used the special build-space name all to indicate that we want to update the testing repository for all the build-spaces we have configured. If we only wanted to synchronise a specific repository we could have specified the name of that repository instead of all.
Synchronising the "live" portage tree to the x86-64bit-server testing repository...ok.
Synchronising the "live" patch-sets to the x86-64bit-server testing repository...ok.
Synchronising the "live" overlays to the x86-64bit-server testing repository...ok.
Running auto-patch-portage on the x86-64bit-server testing repository...ok.
Running rebuild-portage-caches in the x86-64bit-server build-space...ok.
Synchronising the "live" portage tree to the x86-64bit-workstation testing repository...ok.
Synchronising the "live" patch-sets to the x86-64bit-workstation testing repository...ok.
Synchronising the "live" overlays to the x86-64bit-workstation testing repository...ok.
Running auto-patch-portage on the x86-64bit-workstation testing repository...ok.
Running rebuild-portage-caches in the x86-64bit-workstation build-space...ok.
Synchronising the "live" portage tree to the x86-32bit-server testing repository...ok.
Synchronising the "live" patch-sets to the x86-32bit-server testing repository...ok.
Synchronising the "live" overlays to the x86-32bit-server testing repository...ok.
Running auto-patch-portage on the x86-32bit-server testing repository...ok.
Running linux32 rebuild-portage-caches in the x86-32bit-server build-space...ok.
Synchronising the "live" portage tree to the x86-32bit-workstation testing repository...ok.
Synchronising the "live" patch-sets to the x86-32bit-workstation testing repository...ok.
Synchronising the "live" overlays to the x86-32bit-workstation testing repository...ok.
Running auto-patch-portage on the x86-32bit-workstation testing repository...ok.
Running linux32 rebuild-portage-caches in the x86-32bit-workstation build-space...ok.
If the synchronisation and cache updates worked as intended we can add an entry to crontab so that the update is performed every week, or as often as desired.
You can see from the example below that we have modified the original entry to synchronise the "live" repository so that it will now only run Monday to Saturday. On Sunday we also perform a synchronisation of the "live" repository before synchronising the testing repositories by using both the --sync-live and --sync-test all options.
PATH=/usr/local/sbin:/usr/bin:/bin
MAILTO=root
#Mins Hours Days Months DOTW Job
0 6 * * * sync-repositories --sync-live
0 6 * * mon-sat sync-repositories --sync-live
0 6 * * sun sync-repositories --sync-live --sync-test all
Building updated packages
When performing a manual update of a Gentoo Linux system a number of tasks must be performed which are not all as obvious as they may first appear. Some of these tasks are performed by the user when an error occurs or in response to a prompt displayed during execution of an ebuild, others are performed using separate applications and utilities once the update process is complete. When attempting to automate the build process it is important that these tasks are performed correctly every time so that potential problems are resolved before they lead to errors.
The steps required to build updated packages in a build-space are listed below:
- Perform a pretend update so that we know what will be modified
- Check that the space for distribution files is available
- Download any distribution files required by the update
- Build the updated binary packages
- Rebuild the system glibc library if the linux-headers version has changed
- Merge new configuration files
- Clean any orphaned dependencies
- Remove any redundant libraries
- Repair any libtool archives which were broken during the update
- Rebuild any binaries which were broken during the update
- Rebuild python packages using python-updater if required
- Rebuild perl packages using perl-cleaner if required
- Remove any redundant binary packages
In the previous section we installed the app-admin/buildspace-scripts package into of all the build-spaces. Now that we have synchronised the "live" and testing repositories we can use the update-buildspaces application to perform all of the above tasks on either a specific build-space, or all as shown below.
Updating the [native] x86-64bit-server build-space...ok.
Updating the [native] x86-64bit-workstation build-space...ok.
Updating the [32-bit] x86-32bit-server build-space...ok.
Updating the [32-bit] x86-32bit-workstation build-space...ok.
Should you wish to build updated packages for all build-spaces automatically this can be easily accomplished by modifying the cron entry as shown below.
PATH=/usr/local/sbin:/usr/bin:/bin
MAILTO=root
#Mins Hours Days Months DOTW Job
0 6 * * mon-sat sync-repositories --sync-live
0 6 * * sun sync-repositories --sync-live --sync-test all
0 6 * * sun sync-repositories --sync-live --sync-test all && echo && update-buildspaces all
Synchronising stable repositories
Once all the build-spaces have been successfully updated, and the packages thoroughly tested using a suitable test framework if desired, the test repositories can be synchronised to the stable repositories. The example below demonstrates how to synchronise all the updated test repositories to the stable repositories. As with the --sync-test command a space separated list of build-spaces may be specified or all may be used to synchronise all repositories.
The stable repositories can now be used by clients to install binary packages while the next generation of packages is built and tested in the build-spaces and testing repositories.