Puritan

Puritan

Source code. README. Latest version: ui: bd0fefc0, compilation: e077d7a6. Puritan is a disk-image compiler which converts source material including packages, activities, and hacks into installable disk images. It consists of two pieces: a UI and a family of compilations (example). The compilations are simple Python programs which populate a filesystem with the materials you supply, then format it for distribution. The UI runs the compilations in a controlled environment created by Mock and configured according to the compilation's bootstrap and dependencies files.

Puritan was developed as a replacement for Pilgrim but was never officially adopted by OLPC. For details on the active OLPC build system, see Build system.

Principles

Puritan is based on several fundamental principles.

1. Tools should be usable for both decentralized and centralized patterns of development.
2. People **will** want to make unpackaged changes to their builds.
3. Caching matters.
4. Interactive development matters.
5. Build reproducibility matters.
6. Error-detection, handling, and cleanup matter.
7. People working on the OLPC build system will become accustomed to git and python.

Instructions

To use Puritan, you need to install dependencies and to check out and run a 'ui' and a 'compilation'.

 # NB: mock >= 0.9.7 is needed.
 # debian:
 sudo apt-get install mock git-core
 # fedora:
 sudo yum install mock git-core
 
 (git clone git://dev.laptop.org/users/mstone/puritan compilation; cd compilation; git checkout -b 767-$USER origin/767)
 git clone git://dev.laptop.org/users/mstone/puritan ui
 python ui/puritan/main.py   # read help
 sudo python2.5 ui/puritan/main.py -v ./compilation HEAD ./results build

Some puritan compilations now feature both 'download' operations:

 sudo python2.5 ui/puritan/main.py -v ./compilation HEAD ./results download

and 'interactive' error-handling:

 sudo python2.5  -v ./compilation HEAD ./results build -- -i

 git clone git://dev.laptop.org/users/mstone/puritan ui
 /usr/bin/python2.5 ui/puritan/main.py ./compilation HEAD ./results build

Configuration

Puritan's compilations are highly and easily configurable by means of small modifications to files and directories.

Choosing stages and products

Current compilations' main.py file contain a section like

 tasks = dict(
    build = [
        'bootstrap',
        ['make_chroot', 'install_pkgs', 'install_hacks'],
         'final_install',
         'produce_tree',
         'produce_jffs2',
         'produce_tar',
         'publish',
     ],
     download = ['make_chroot', 'download_pkgs'],
     run = ['run'],
 )

By adding and removing entries to this datastructure, builders may customize which compilation stages will be performed in response to a request to 'build' or to 'download' or to 'run' the compiler. (New subcommands can be added in the obvious fashion.)

Choosing package repos

Current compilations' bootstrap.py contains lines like

 smart(['channel', '-y', '--add', '8.2-fedora', 'type=rpm-md', 'baseurl=http://mock.laptop.org/repos/koji.dist-olpc3-testing/'])

which direct the smart package manager to pull packages from the yum-format RPM repository located at [1].

(The smart package manager is package- and repository-format agnostic and can process many common formats including apt-dpkg and yum-rpm.)

Choosing packages

Current compilations' package manifests are configured by means of the contents of the config/packages directory. In order to add or remove packages from the manifest, simply touch or remove the appropriately named files in this directory.

Caching

Puritan uses technologies which can be easily configured to use caches of data. Three ways to improve puritan's caching behavior include:

• Using mock buildroot caching to conserve bandwidth when preparing buildroots.
• Configuring smart to use an http caching proxy in the compilation's bootstrap.py file.
• Configuring smart to pull packages from a (manually generated) local package repository (rather than from the internet), also via bootstrap.py.

Notes

• with some uis and compilations, the last step may fail because /etc/mock/fedora-9-i386.cfg is not present in Debian's mock package 0.9.7-2
  • one workaround is to create it from http://teach.laptop.org/~mstone/fedora-9-i386.cfg.
• Mock and SElinux do not interact very well.
  • at least one workaround is discussed on the Fedora MockTricks] page.

Help Out

Finally, please help improve puritan by:

• Making puritan work on your platform - it's only dependencies are python2.5, git-core, and mock!
• Maintaining the devel_ext3 compilation
• Adding some reasonable package or buildroot caching system so that it runs faster without impairing build repeatability
• Improving the UI with commands for manipulating compilations, or for diffing builds, or for profiling compilations, or ...