wiki:Software/Tools/Buildout

Version 1 (modified by spascoe, 11 years ago) (diff)

--

ZcBuildout

Zc.buildout is a tool for downloading and assembling parts of Python applications, particularly parts composed of Python eggs. It takes radically different approach to egg installation than setuptools. It is well suited to deployment environments where you want strict control over which egg versions are being used and want reproducibility of installations.

Key Concepts

  1. A buildout is a description of a set of parts. We usually use it to refer to the directory in which this description sits and where the parts are assembled.
  2. A part is self explanitory -- a part of the Python application. Most commonly parts are collections of eggs.
  3. A recipe is a python component that assembles a part. Recipes are distributed as eggs and can be automatically downloaded by buildout. The most common recipe is zc.recipe.egg that assembles collections of eggs.

Quick References

Installation

If you already have setuptools installed you can install buildout with:

> easy_install zc.buildout

However, you don't need to do this. You can download the tarball from the documentation page and bootstrap the system as follows:

> tar zxf zc.buildout-1.1.1.tar.gz
> cd zc.buildout-1.1.1
> python bootstrap/bootstrap.py
Creating directory '/misc/humid1/spascoe/dist/zc.buildout/bin'.
Creating directory '/misc/humid1/spascoe/dist/zc.buildout/parts'.
Creating directory '/misc/humid1/spascoe/dist/zc.buildout/eggs'.
Creating directory '/misc/humid1/spascoe/dist/zc.buildout/develop-eggs'.
Generated script '/misc/humid1/spascoe/dist/zc.buildout/bin/buildout'.

The distribution directory then becomes your first buildout containing the buildout command in the bin directory.

Initialising a buildout

Once you have the buildout script installed you can create other buildout environments as follows:

> mkdir my_buildout ; cd my_buildout
> path/to/buildout init

Layout of a buildout

+-my_buildout
  +-buildout.cfg
  +-bin
  | +-buildout
  +-develop-eggs
  +-eggs
  +-parts

Examples

Trivial example

A simple test downloading 1 python-only egg.

buildout.cfg

[buildout]
parts = eg1

[eg1]
recipe = zc.recipe.egg
eggs = feedparser
interpreter = py

Installing CSML

buildout.cdf

[buildout]
parts = eg1 eg2

[eg1]
recipe = zc.recipe.egg
eggs = feedparser
interpreter = py

[eg2]
recipe = zc.recipe.egg
eggs =
  cdat_lite
  csml
find-links = http://ndg.nerc.ac.uk/dist

Installing Pylons

Buildout in Portals Project

BuildoutWalkthrough? shows how we used buildout to configure one of the Portals Project servers

Important things to remember

  • Use --newest and --offline options to reduce network access
  • Eggs are hard-baked into the scripts
  • Buildout is stricter than easy_install on setuptools features. It doesn't work with traditional distutils scripts, only console_scripts entry_points.
  • The generated interpreter bin/py is NOT an executable but a script. It makes a difference sometimes, e.g. SGE

Controlling egg versions

  1. You can state exact versions in the eggs option.
  2. You can add a versions option to [buildout] to separately record the versions of eggs. See  http://pypi.python.org/pypi/zc.buildout#id85