Repeatable buildouts: controlling eggs used
===========================================

One of the goals of zc.buildout is to provide enough control to make
buildouts repeatable.  It should be possible to check the buildout
configuration files for a project into a version control system and
later use the checked in files to get the same buildout, subject to
changes in the environment outside the buildout.

An advantage of using Python eggs is that depenencies of eggs used are
automatically determined and used.  The automatic inclusion of
depenent distributions is at odds with the goal of repeatable
buildouts.

To support repeatable buildouts, a versions section can be created
with options for each distribution name whos version is to be fixed.
The section can then be specified via the buildout versions option.

To see how this works, we'll create two versions of a recipe egg:

    >>> mkdir('recipe')
    >>> write('recipe', 'recipe.py',
    ... '''
    ... class Recipe:
    ...     def __init__(*a): pass
    ...     def install(self):
    ...         print 'recipe v1'
    ...         return ()
    ...     update = install
    ... ''')

    >>> write('recipe', 'setup.py',
    ... '''
    ... from setuptools import setup
    ... setup(name='spam', version='1', py_modules=['recipe'],
    ...       entry_points={'zc.buildout': ['default = recipe:Recipe']},
    ...       )
    ... ''')

    >>> write('recipe', 'README', '')

    >>> print system(buildout+' setup recipe bdist_egg'), # doctest: +ELLIPSIS
    Running setup script 'recipe/setup.py'.
    ...

    >>> rmdir('recipe', 'build')

    >>> write('recipe', 'recipe.py',
    ... '''
    ... class Recipe:
    ...     def __init__(*a): pass
    ...     def install(self):
    ...         print 'recipe v2'
    ...         return ()
    ...     update = install
    ... ''')

    >>> write('recipe', 'setup.py',
    ... '''
    ... from setuptools import setup
    ... setup(name='spam', version='2', py_modules=['recipe'],
    ...       entry_points={'zc.buildout': ['default = recipe:Recipe']},
    ...       )
    ... ''')


    >>> print system(buildout+' setup recipe bdist_egg'), # doctest: +ELLIPSIS
    Running setup script 'recipe/setup.py'.
    ...

and we'll configure a buildout to use it:

    >>> write('buildout.cfg',
    ... '''
    ... [buildout]
    ... parts = foo
    ... find-links = %s
    ...
    ... [foo]
    ... recipe = spam
    ... ''' % join('recipe', 'dist'))

If we run the buildout, it will use version 2:

    >>> print system(buildout),
    Getting distribution for 'spam'.
    Got spam 2.
    Installing foo.
    recipe v2

We can specify a versions section that lists our recipe and name it in
the buildout section:

    >>> write('buildout.cfg',
    ... '''
    ... [buildout]
    ... parts = foo
    ... find-links = %s
    ... versions = release-1
    ...
    ... [release-1]
    ... spam = 1
    ... eggs = 2.2
    ...
    ... [foo]
    ... recipe = spam
    ... ''' % join('recipe', 'dist'))

Here we created a release-1 section listing the version 1 for the spam
distribution.  We told the buildout to use it by specifying release-1
as in the versions option.

Now, if we run the buildout, we'll use version 1 of the spam recipe:

    >>> print system(buildout),
    Getting distribution for 'spam==1'.
    Got spam 1.
    Uninstalling foo.
    Installing foo.
    recipe v1

Running the buildout in verbose mode will help us get information
about versions used. If we run the buildout in verbose mode without
specifying a versions section:

    >>> print system(buildout+' buildout:versions= -v'), # doctest: +ELLIPSIS
    Installing 'zc.buildout', 'setuptools'.
    We have a develop egg: zc.buildout 1.0.0.
    We have the best distribution that satisfies 'setuptools'.
    Picked: setuptools = 0.6
    Installing 'spam'.
    We have the best distribution that satisfies 'spam'.
    Picked: spam = 2.
    Uninstalling foo.
    Installing foo.
    recipe v2

We'll get output that includes lines that tell us what versions
buildout chose a for us, like::

    zc.buildout.easy_install.picked: spam = 2

This allows us to discover versions that are picked dynamically, so
that we can fix them in a versions section.

If we run the buildout with the versions section:

    >>> print system(buildout+' -v'), # doctest: +ELLIPSIS
    Installing 'zc.buildout', 'setuptools'.
    We have a develop egg: zc.buildout 1.0.0.
    We have the best distribution that satisfies 'setuptools'.
    Picked: setuptools = 0.6
    Installing 'spam'.
    We have the distribution that satisfies 'spam==1'.
    Uninstalling foo.
    Installing foo.
    recipe v1

We won't get output for the spam distribution, which we didn't pick,
but we will get output for setuptools, which we didn't specify
versions for.

You can request buildout to generate an error if it picks any
versions:

    >>> write('buildout.cfg',
    ... '''
    ... [buildout]
    ... parts = foo
    ... find-links = %s
    ... versions = release-1
    ... allow-picked-versions = false
    ...
    ... [release-1]
    ... spam = 1
    ... eggs = 2.2
    ...
    ... [foo]
    ... recipe = spam
    ... ''' % join('recipe', 'dist'))