--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/eggs/zc.buildout-1.5.2-py2.6.egg/zc/buildout/repeatable.txt	Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,180 @@
+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'))