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 ~/public_rpms/<build>/ChangeLog to describe the changes made by the packages you are introducing.

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. Finally, you can read the buildlog to check if Web-72.xo was installed.

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

Build system requirements

Build system meeting

Bernie's build system workflow proposal

Source Code: Patches Welcome

Dropbox Mechanism

source code

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

source code

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