Build system
Maintainers
1. Scott Ananian (c_scott)
2. Michael Stone (m_stone)
3. Chris Ball (cjb)
Build Branches
Frequently, we find ourselves needing to integrate complicated changes that cut across packages. To make this easier, we make it very easy to 'branch' a build in which the integration can be performed safely, without interfering with other work. If you are trying to perform a delicate piece of integration for which it would be helpful to have a separate build, please contact one of the build system maintainers.
We currently have five build branches arranged in an inheritance tree like so:
kernel <- xtest <- datastore <- sugar <- rainbow <- joyride.
Instructions for Use
Before getting started, you will need an account on dev.laptop.org (See Project_hosting).
To add a completely new piece of software (either a new activity or a new package) to a build, three steps are necessary.
1. Include a source code package (.xo or .src.rpm) and a binary package (.xo or .rpm) in your dropbox (which is located at ~/public_rpms/<build>/ on dev.laptop.org). You will need to create the folder, here is an example for joyride:
mkdir -p ~/public_rpms/joyride
Note: do not remove the .xpm's or .xo's from the public_rpms location, not even after they already showed up in an image: public_rpms is not a temporary place where the build systems grab them; it will grab them from that location every run.
2. Update the change log to describe the changes made by the packages you are introducing. We accumulate changelog entries for ~/public_rpms/<build>/ChangeLog and ~/public_rpms/<build>/*.changes, so you can use a separate .changes file for each major group of packages you maintain.
3. Where possible, it's best to add your package as a new dependency of an existing package, so that the reason for the inclusion of this package is clear. If this is not possible, file a bug in trac with component 'distro' and owner 'cscott' requesting that the new package or activity be added to the build.
To verify that a package (here Web-72.xo) has been picked up you can do the following:
First you can look in the repos/joyride if there was a Web-*.xo present. Another interesting file in the same directory is the ChangeLog which is the aggregate ChangeLog that describes all of the packages pulled in from every dropbox. It contains warnings emitted when some problem prevents your RPMs from being picked up. Finally, you can read the buildlog to check if Web-72.xo was installed.
- Bert made a script that aggregates changelogs as joyride-pkgs.html, which is useful for comparing build versions.
ChangeLog Format
The format of this ChangeLog is
<pkg-lines> (containing ".xo", ".rpm")
<detail-lines> (not containing the string ".xo", ".rpm", "--")
-- <signature> (-- is the line marker)
<pkg>
<pkg>.rpm
<detail>
-- <signature>
An example:
Etoys-61.xo etoys-2.2.1710-1.noarch.rpm etoys-2.2.1710-1.src.rpm * changed activity launch to match new Sugar * words in tiles separated by spaces not camelCase * adds "distance to" and "bearing to" tiles * better .pot sort order -- Bert Freudenberg <bert@freudenbergs.de> Tue, 16 Oct 2007 squeak-vm-3.9-12olpc1.i386.rpm squeak-vm-3.9-12olpc1.src.rpm * big merge with trunk * unicode key events * fixed dbus plugin -- Bert Freudenberg <bert@freudenbergs.de> Mon, 15 Oct 2007
Common Mistakes
If there are multiple authors of a single build-patch, you should list each person's contribution like so:
pkg.rpm * change -- author 1 pkg.rpm * change -- author 2
rather than like
pkg.rpm * change -- author 1 * change -- author 2
until we improve the ChangeLog parser.
Output from the Build System
The build system produces things:
1. An RPM repository, currently located under the repository root
2. The output of the build system is currently located under the streams root
Implementation Details
The build system we want to have consists of the following components:
/------\
| F7 yum |--------+
| repos | |
\------/ V
/--------\ +--------+ +----------+ +---------+ /------\
| upstream | | distro | | pkg build| |compose | | stable |
| src |-->| SCM |-->| system |-->| tools |-->| rainbow|
| repos | | (CVS) | | (Koji) | |(joyride)| | xtest |
\--------/ +--------+ +----------+ +---------+ \------/
^ ^ ^
/--------\ | | |
|patches |-----+ | + - - - - - - - + |
\--------/ | | dropbox | |
+----->| system |----+
/--------\ | | (public_rpms) |
| olpc | | + - - - - - - - +
| sources |-------+
| (GIT) |
\--------/
|-----------| |----------------------------| |-----------------------|
sources package maintenance package composition
CVS,GIT Koji, Mock, rpmbuild mash, pilgrim, ChangeLogs
The one we actually have is fairly similar but the package-construction step is done partially in Koji and partially by individual package maintainers using tools like Mock and rpmbuild.
Moving Forward
Bernie's build system workflow proposal
Source Code: Patches Welcome
Dropbox Mechanism
The dropbox mechanism is a way for people who don't have the resources to work through koji to supply us with activities and RPMs.
It is implemented in two pieces, one running on the dropbox-host and one running on the build-host. The dropbox-host simply provides an rsync daemon that will transfer packages to the builder on request.
The build-host uses the program 'collect-pkgs.py' to aggregate packages and change-entries into an RPM repository for composition by pilgrim.
Pilgrim
Pilgrim is composed of two large and two small scripts and many configuration files.
pilgrim # user-interface pilgrim-autobuild # implementation build-one # build the current branch make-repos # touch up yum repositories
The most important branch is "autobuild". This is where changes deemed suitable for all build branches should be merged.
The other branches - joyride, meshtest, xtest, and rainbow store branch-specific data like which yum repositories to compose into the image, which packages to pull, which activities to include, and so on.
These data are mostly recorded in
streams.d/olpc-branch.conf # a few important config variables streams.d/olpc-development-yum-install.conf # yum repositories to compose, package exclusions streams.d/olpc-development.stream # lists of packages and activities to install