Introduction

This page describes the life cycle of a Django project managed using zc.buildout. The files used for this document are available in the template module in Subversion.

This is preliminary documentation. I'm just starting to use this in practice so we will undoubtedly discover that some initial assumptions don't hold or are just plain incorrect. Eventually it should be trivial to add zc.buildout to an existing Django project.

Getting Started

To start a project, download bootstrap.py and save it to your project directory. bootstrap.py is a Python script which downloads zc.buildout itself, along with setuptools if necessary, and creates a wrapper script for the buildout command.

Bootstrapping zc.buildout

Run bootstrap.py with your choice of Python interpreter (2.4 or newer). The interpreter used to run bootstrap.py will be set as the default interpreter for all scripts generated by the buildout process.

Running bootstrap.py creates (among other things) a bin subdirectory, along with a buildout script. The buildout script reads the buildout configuration (named buildout.cfg by default) and assembles the software described in it. It can be run any time you update the dependencies of your project to retrieve eggs. Running buildout also checks for newer versions of dependencies (including zc.buildout and setuptools) and downloads them if possible.

Our first buildout

After running bootstrap.py (a one-time thing), we're ready to write our initial buildout configuration and run ./bin/buildout. Our initial configuration will do the only thing we can do at this point -- download Django and make create the django-admin script.

Our buildout.cfg will look something like this:

# Minimal Django Buildout
# http://code.google.com/p/django-buildout/
# 

[buildout]
bin-directory = ./bin
find-links = http://code.google.com/p/django-buildout/downloads/list
http://code.google.com/p/django-buildout/wiki/DjangoEggs

parts = django

[django]
recipe = zc.recipe.egg
eggs = Django==0.95 django_buildout

Since this is our first time running buildout, it is useful to examine the features of buildout.cfg used in the template.

As with Python code, # indicates a comment. Taking the file section-by-section, the [buildout] section is the only one whose name is fixed. This section contains information for our entire buildout. The bin-directory setting tells buildout where we want our scripts to be stored. The find-links setting tells buildout where to look (beside the Python Package Index) for packages. The parts setting is the most important: it tells buildout which "parts" make up our application. For some background on buildout terminology, see the buildout documentation.

In our case the file says that a single part will be installed -- django. The part names coorespond to other configuration section titles.

Looking at the django part definition, we see two parameters: recipe and eggs. Every part has a recipe which performs the actual functionality. The zc.recipe.egg recipe installs Python eggs and their dependencies. The eggs to install are specified by the eggs setting. You can specify multiple eggs, separated by spaces.

Run ./bin/buildout which will read the buildout configuration file and install Django (and any dependencies it might declare) in the eggs sub-directory. It will also create news script in bin, including django-admin. This version of django-admin has your preferred Python interpreter set, as well as code to add any Python eggs necessary to the PYTHONPATH before calling the actual Django code.

More Information:

• [http://cheeseshop.python.org/pypi/zc.buildout#configuration-file-syntax buildout.cfg

Starting the Django Project

It can be useful to store the source files for your project in the src sub-directory of your project. To start our new Django project, we'll create the src sub-directory and then run django-admin, just like you would normally do.

 $ mkdir src
 $ cd src
 $ ../bin/django-admin startproject myproject

At this point you your Django project started in the myproject directory. You'll also want to write a setup.py for the project. This will declare the dependencies for your project, and will allow zc.buildout to install them. The setup.py should go in the same directory as your buildout.cfg. A basic setup.py would look something like this:

# Minimal Django Buildout setup.py
# http://code.google.com/p/django-buildout/
# 

from setuptools import setup, find_packages

setup(
    name = "myproject",
    version = "0.1",
    packages = find_packages('src'),
    package_dir = {'':'src'},
    
    # scripts and dependencies
    dependency_links = [
        "http://code.google.com/p/django-buildout/downloads/list",
	"http://code.google.com/p/django-buildout/wiki/DjangoEggs"],

    install_requires = ['setuptools',
                        'Django==0.95',
			'django_buildout',
                        ],

    include_package_data = True,
    zip_safe = False,

    # author metadata
    author = 'Nathan R. Yergler',
    author_email = 'nathan@yergler.net',
    description = 'A simple Django app for demonstrating django-buildout.',
    url = 'http://code.google.com/p/django-buildout',

    )

You'll also want to add the following line to the [buildout] section of buildout.cfg:

develop = .

This tells zc.buildout to construct a develop-egg from the current directory. A develop-egg is a special "pointer" file that tells setuptools to treat a path on the filesystem (in this case probably src) as an egg. This allows you to continue developing your project without re-building it as an egg every time you make a change.

You can re-run ./bin/buildout now and it will process your setup.py and the new develop line in buildout.cfg. It will also update the django-admin script it creates to include your project on the Python path.

NOTE: The manage.py created in your project will not have its Python path configured correctly. The django-buildout egg generates a manage script for you (placed in the bin directory) that you can replace the provided manage.py with. Yes, this is a wart.

Declaring Dependencies

You can declare dependencies by adding them to the list of requirements in setup.py. Dependencies needed for execution should be added to the install_requires parameter. Dependencies needed to test your application can be specified in the test_requires parameter. For details on the setup() parameters and how to format package declarations, see the [http://peak.telecommunity.com/DevCenter/setuptools#declaring-dependencies setuptools documentation].

XXX needs example

Testing

XXX

Deployment

XXX When deploying with mod_python you can use django-buildout to generate the basic configuration for you.