buildout tutorial. buildout howto. buildout review.

This post is a review, a tutorial, and a howto - for and about buildout - a software development tool for the python language.

This document aims to answer the question... "buildout? WTF?".

In short: buildout automates python project building. Buildout does everything needed to get your application in a state for running in its own sandbox.

Super quick start instructions for using buildout...

get the source from http://pypi.python.org/pypi/zc.buildout

Make a new directory for your project, then copy the bootstrap/bootstrap.py file out of the zc.buildout source into your new project directory

create a "buildout.cfg" file to go with the bootstrap.py file. Here is a simple one for your package called "YOURPACKAGENAME":

[buildout]
parts = test py
develop = .

[test]
recipe = zc.recipe.testrunner
eggs = YOURPACKAGENAME

Run "python bootstrap.py" in your empty project directory(with the buildout.cfg file in there).  This will get buildout locally into your sandbox ready to use - without touching the rest of your python installation.

Now you have a basic setup for "building out" your application.

What is buildout?

"The Buildout project provides support for creating applications, especially Python applications. It provides tools for assembling applications from multiple parts, Python or otherwise. An application may actually contain multiple programs, processes, and configuration settings."

Why should I care about buildout?

Automation of building your applications is what buildout is about.

To be able to build your application easily on multiple machines, you don't want to have to install and setup 38 different programs before you can build it.

Buildout keeps your project separate from the main python setup.  So it doesn't install things into the main python distribution.  This is good because it keeps separate applications mucking each other up.  It's also good so you don't need to have a root user account to install python modules.

Buildout can be extended through the use of recipes.  Recipes are like plugins, and they do all sorts of things.  You can see a list of buildout recipes on the python package index (pypi).

buildout can do lots of other things too - but these are the core concepts.

Where is buildout? Links to buildout pages.

The buildout url: http://pypi.python.org/pypi/zc.buildout

A buildout tutorial which seems better than the official documentation - but hard to find with search engines. It's written as a tutorial to give to people - not really to read online.

Plone buildout tutorial. - this one is specific to plone.

subversion repository for zc.buildout: http://svn.zope.org/zc.buildout/

Licence: The Zope Public License

http://www.ohloh.net/projects/compare?project_0=zc.buildout

buildout recipes on pypi

Disadvantages to buildout?

You become dependant on a few things. At least with buildout you become dependant on:

zc.buildout

setuptools

pypi.python.org website remaining up... it is fairly often down.

distutils - buildout requires a setup.py file.

Who uses buildout? How stable is it? How portable is it?

At the moment buildout is mostly used by zope, and other python web applications.

It's a fairly recent project - first released mid 2006. However it's a 3rd generation buildout system used by the zope corporation - so it's got a bunch of wisdom behind it.

Buildout seems to be stabilising... that is the amount of changes to it seems to be slowing down. There seems to be about 37 bugs in the buildout bug tracker as of writing(2008-05-01) - with 3 of the bugs marked fixed (at 2008-05-31 and still only 3 of the bugs marked fixed) - and a number of bugs under discussion.

Documentation isn't the best (which is one reason I'm writing this post) - but there is at least a main manual, and a tutorial.

There do seem to be quite a few doctest based tests that come with it - which is one form of documentation in itself - but more documentation about zc.buildout - rather than documentation for using zc.buildout. There is about 1400 lines of python in the tests, and about 3000 lines of non-python code in the doctests (usually description about what the tests are doing).

I'm not sure how portable buildout is. The last release (as of writing 1.0.1 (2008-04-02)), mentions windows fixes, and was the last release for 3 months. I know of people using it on linux(suse, debian), and mac osx based machines.  Update: a note in the comments says it works fine on windows.