Using zc.buildout to run setup scripts

======================================

zc buildout has a convenience command for running setup scripts.  Why?

There are two reasons.  If a setup script doesn't import setuptools,

you can't use any setuptools-provided commands, like bdist_egg.  When

buildout runs a setup script, it arranges to import setuptools before

running the script so setuptools-provided commands are available.

If you use a squeaky-clean Python to do your development, the setup

script that would import setuptools because setuptools isn't in the

path.  Because buildout requires setuptools and knows where it has

installed a setuptools egg, it adds the setuptools egg to the Python

path before running the script.  To run a setup script, use the

buildout setup command, passing the name of a script or a directory

containing a setup script and arguments to the script.  Let's look at

an example:

    >>> mkdir('test')

    >>> cd('test')

    >>> write('setup.py',

    ... '''

    ... from distutils.core import setup

    ... setup(name='sample')

    ... ''')

We've created a super simple (stupid) setup script.  Note that it

doesn't import setuptools.  Let's try running it to create an egg.

We'll use the buildout script from our sample buildout:

    >>> print system(buildout+' setup'),

    ... # doctest: +NORMALIZE_WHITESPACE

    Error: The setup command requires the path to a setup script or

    directory containing a setup script, and its arguments.

Oops, we forgot to give the name of the setup script:

    >>> print system(buildout+' setup setup.py bdist_egg'),

    ... # doctest: +ELLIPSIS

    Running setup script 'setup.py'.

    ...

    >>> ls('dist')

    -  sample-0.0.0-py2.5.egg

Note that we can specify a directory name.  This is often shorter and

preferred by the lazy :)

    >>> print system(buildout+' setup . bdist_egg'), # doctest: +ELLIPSIS

    Running setup script './setup.py'.

    ...