NEXS - Build System

NEXS4 is based on OLPC XS v0.6. To apply our own customizations, we have created a set of scripts which modify the .iso file published by OLPC.

The build system requires Fedora 11 and a few build utilities. Root access is not required. The tony server is currently used for builds.

System setup

First, some required packages

yum install mock createrepo

Next, configure mock's Fedora 9 configurations to point at our local F9 mirror. This can be done by modifying /etc/mock/fedora-9-i386.cfg. For the fedora and updates-released repos, the mirrorlist lines should be commented out, and replaced with the appropriate baseurl line:

[fedora]
...
baseurl=http://mirror.olenepal.org/fedora/9/

[updates-released]
...
baseurl=http://mirror.olenepal.org/fedora/9-updates/

Building NEXS

Automated builds through Hudson

We have basically scripted the process described below in a hudson project. Hudson is our usual way of making a build - simply start the job from http://hudson.olenepal.org. The output will be available at http://dev.olenepal.org/NEXS/NEXS_4/

One-time build preparation

This needs to be done only once:

cd /root
hg clone http://hg.olenepal.org/NEXS-image-builder
cd NEXS-image-builder
hg clone http://hg.olenepal.org/NEXS_scripts

The NEXS-image-builder repo contains the scripts which modify the OLPC XS release. The NEXS_scripts repository, checked out underneath the NEXS-image-builder-repo as above, contains various scripts and customizations which appear inside the build. More details below.

Making a build manually

The build process is as simple as making sure you have the latest build scripts, then running build.sh from NEXS-image-builder:

cd /root/NEXS-image-builder
hg pull
hg update
pushd NEXS_scripts
hg pull
hg update
popd
./build.sh /path/to/output.iso

Technical details

Customizations on top of XS-0.6

• Fedora and Fez added (plus their dependencies, including MySQL, ImageMagick, Java, and more).
• dansguardian installed and configured
• iptables modified to push web traffic through dansguardian
• ssh admin account configured
• netsetup.sh added (makes WAN configuration easier)
• Squid web-cache enabled
• Wind-specific udev rules added, to ensure that WAN and LAN adapters have the right names
• usbmount triggers added to allow import/update of the content described above (Fedora, Fez, databases, etc.)

The above customizations are packaged at build time into a nexs-custom package, which is installed during the standard installation. Also, the kickstart script causes install.sh (from nexs-custom) to be executed on first boot, which performs many of the above system tweaks.

NEXS_scripts

The NEXS_scripts repository includes various customizations for the XS. It makes some customizations through just putting files in certain places, and others by installing a script to make customizations during first boot of the XS. The nexs-custom.spec file is the file that defines how the RPM is built.

See https://fedoraproject.org/wiki/How_to_create_an_RPM_package for good documentation on this process. After reading that, you should have an understanding that RPM packages own files/directories installed on the filesystem, and 2 packages should never own the same file/directory. So, for the customizations which are simply the creation of new files, the spec file can install those files to their appropriate locations in install and list them in %files (e.g. /etc/udev/rules.d/10-nexs-network.rules). For files that are owned by other packages (e.g. mysql config file), they should instead be installed into /usr/share/nexs-custom and installed by config.sh which runs on first boot.

The _make-rpm_ script can be invoked to generate a RPM from the nexs-custom.spec file. This invokes rpmbuild to make a source RPM, and then uses mock (http://fedoraproject.org/wiki/Projects/Mock) to build a binary RPM in a F9 chroot. Mock is needed because tony runs F11 and the target is F9, and any RPMs produced on F11 will not be recognised on F9 due to internal changes within the RPM format.

Self tests

The test code is installed by NEXS_scripts into /usr/share/nexs-custom/tests. It can be invoked by running /usr/share/nexs-custom/tests/selftest. It is made up of a few files:

• _selftest_: the main wrapper and core functionality
• _testlib_: a function library used to simplify test
• _testcode_: all the tests are written here

Each test must be started with a _new_test_ statement, with a description of the test as a first parameter. The test should then be executed, with test_pass_ being called if the test passed, and _test_fail_ being called upon failure. While it is necessary to always call test_pass on success, it is actually optional to call test_fail on failure -- if none of those 2 functions is called, then failure is assumed once the next _new_test_ statement is encountered, or at the end of the very last test.

NEXS-image-builder

build.sh file is what glues everything together.

• It creates a build directory within hudson's workspace (or under your home directory if not running through hudson) for temporary files used during the build
• It calls NEXS_scripts/make-rpm to create the nexs-custom RPM including most of OLEN's customizations.
• It downloads a hardcoded version of the OLPC school server from http://dev.olenepal.org/NEXS-build/. When a new school server is released upstream, the released .iso should be made available there, and build.sh updated to point to the new iso.
• It extracts the contents of that .iso into the build directory, so that modifications can be made.
• It removes some unneeded files which take up a lot of space
• It copies in a new kickstart file called nexs.ks from the NEXS-image-builder repo. The kickstart file is a series of instructions describing how to build the system. This kickstart file is based on the official OLPC XS kickstart file found at revisor/anaconda-f9.ks inside http://dev.laptop.org/git/projects/xs-livecd/ with only light modifications to automate the installation and add packages needed by NEXS

• The .iso already contains a big collection of RPMs, and now we add to that: it copys in the nexs-custom RPM generated above, as well as any other RPMs that we've put in the rpms/ directory of NEXS-image-builder. These are unofficial RPMs that are not in Fedora repositories (e.g. dansguardian).
• It downloads some packages from the official Fedora 9 repository (from our local mirror) and adds them to the packages collection. These are packages that are not part of the official XS but are needed by the customizations we are making. Any packages added here will only be downloaded, but to be installed they must also be listed in the kickstart file -- hence the list of packages that we have added to the kickstart file must be kept in sync with the list of packages listed on the yumdownloader line in build.sh. Example: Fez needs mysql, and mysql is an official Fedora 9 package, so mysql has been added to the kickstart file and to the yumdownloader line in build.sh
• It updates the repository data (using the standard Fedora createrepo tool) that describes the packages collection found in the .iso, because we have added some new RPMs
• It repackages everything up into an .iso and presents the result