Make sure the bootstrap script actually works::
>>> import os, sys
>>> from os.path import dirname, join
>>> import zc.buildout
>>> bootstrap_py = join(
... dirname(
... dirname(
... dirname(
... dirname(zc.buildout.__file__)
... )
... )
... ),
... 'bootstrap', 'bootstrap.py')
>>> sample_buildout = tmpdir('sample')
>>> os.chdir(sample_buildout)
>>> write('buildout.cfg',
... '''
... [buildout]
... parts =
... ''')
>>> write('bootstrap.py', open(bootstrap_py).read())
>>> print 'X'; print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py'); print 'X' # doctest: +ELLIPSIS
X...
Creating directory '/sample/bin'.
Creating directory '/sample/parts'.
Creating directory '/sample/eggs'.
Creating directory '/sample/develop-eggs'.
Generated script '/sample/bin/buildout'.
...
>>> ls(sample_buildout)
d bin
- bootstrap.py
- buildout.cfg
d develop-eggs
d eggs
d parts
>>> ls(sample_buildout, 'bin')
- buildout
>>> print 'X'; ls(sample_buildout, 'eggs') # doctest: +ELLIPSIS
X...
d zc.buildout-...egg
The buildout script it has generated is a new-style script, using a
customized site.py.
>>> buildout_script = join(sample_buildout, 'bin', 'buildout')
>>> if sys.platform.startswith('win'):
... buildout_script += '-script.py'
>>> print open(buildout_script).read() # doctest: +ELLIPSIS
#...
<BLANKLINE>
import sys
sys.path[0:0] = [
'/sample/parts/buildout',
]
<BLANKLINE>
<BLANKLINE>
import os
path = sys.path[0]
if os.environ.get('PYTHONPATH'):
path = os.pathsep.join([path, os.environ['PYTHONPATH']])
os.environ['BUILDOUT_ORIGINAL_PYTHONPATH'] = os.environ.get('PYTHONPATH', '')
os.environ['PYTHONPATH'] = path
import site # imports custom buildout-generated site.py
<BLANKLINE>
import zc.buildout.buildout
<BLANKLINE>
if __name__ == '__main__':
zc.buildout.buildout.main()
<BLANKLINE>
The bootstrap process prefers final versions of zc.buildout, so it has
selected the (generated-locally) 99.99 egg rather than the also-available
100.0b1 egg. We can see that in the buildout script's site.py.
>>> buildout_site_py = join(
... sample_buildout, 'parts', 'buildout', 'site.py')
>>> print open(buildout_site_py).read() # doctest: +ELLIPSIS
"...
buildout_paths = [
'/sample/eggs/setuptools-...egg',
'/sample/eggs/zc.buildout-99.99-pyN.N.egg'
]
...
If you want to accept early releases of zc.buildout, you either need to
specify an explicit version (using --version here and specifying the
version in the buildout configuration file using the
``buildout-version`` option or the ``versions`` option) or specify that you
accept early releases by using ``--accept-buildout-test-releases`` on the
bootstrap script.
Here's an example.
>>> ignored = system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py --accept-buildout-test-releases')
>>> print open(buildout_site_py).read() # doctest: +ELLIPSIS
"...
buildout_paths = [
'/sample/eggs/setuptools-...egg',
'/sample/eggs/zc.buildout-100.0b1-pyN.N.egg'
]
...
Notice we are now using zc.buildout 100.0b1, a non-final release.
The buildout script remembers the decision to accept early releases, and
alerts the user.
>>> print system(join('bin', 'buildout')),
... # doctest: +NORMALIZE_WHITESPACE
NOTE: Accepting early releases of build system packages. Rerun bootstrap
without --accept-buildout-test-releases (-t) to return to default
behavior.
This is accomplished within the script itself.
>>> print open(buildout_script).read() # doctest: +ELLIPSIS
#...
sys.argv.insert(1, 'buildout:accept-buildout-test-releases=true')
print ('NOTE: Accepting early releases of build system packages. Rerun '
'bootstrap without --accept-buildout-test-releases (-t) to return to '
'default behavior.')
...
As the note says, to undo, you just need to re-run bootstrap without
--accept-buildout-test-releases.
>>> ignored = system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py')
>>> print open(buildout_site_py).read() # doctest: +ELLIPSIS
"...
buildout_paths = [
'/sample/eggs/setuptools-...egg',
'/sample/eggs/zc.buildout-99.99-pyN.N.egg'
]
...
>>> ('buildout:accept-buildout-test-releases=true' in
... open(buildout_script).read())
False
Now we will try the `--version` option, which lets you define a version for
`zc.buildout`. If not provided, bootstrap will look for the latest one.
Let's try with an unknown version::
>>> print 'XX'; print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py --version UNKNOWN'); print 'X' # doctest: +ELLIPSIS
...
X...
No local packages or download links found for zc.buildout==UNKNOWN...
...
Now let's try with `1.1.2`, which happens to exist::
>>> print 'X'; print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py --version 1.1.2'); print 'X'
...
X
Generated script '/sample/bin/buildout'.
<BLANKLINE>
X
Versions older than 1.5.0 put their egg dependencies in the ``buildout`` script.
Let's make sure it was generated as we expect::
>>> print open(buildout_script).read() # doctest: +ELLIPSIS
#...
<BLANKLINE>
import sys
sys.path[0:0] = [
'/sample/eggs/setuptools-...egg',
'/sample/eggs/zc.buildout-1.1.2...egg',
]
<BLANKLINE>
import zc.buildout.buildout
<BLANKLINE>
if __name__ == '__main__':
zc.buildout.buildout.main()
<BLANKLINE>
Let's try with `1.2.1`::
>>> print 'X'; print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py --version 1.2.1'); print 'X' # doctest: +ELLIPSIS
...
X
Generated script '/sample/bin/buildout'.
<BLANKLINE>
X
Let's make sure the generated ``buildout`` script uses it::
>>> print open(buildout_script).read() # doctest: +ELLIPSIS
#...
<BLANKLINE>
import sys
sys.path[0:0] = [
'/sample/eggs/setuptools-...egg',
'/sample/eggs/zc.buildout-1.2.1...egg',
]
<BLANKLINE>
import zc.buildout.buildout
<BLANKLINE>
if __name__ == '__main__':
zc.buildout.buildout.main()
<BLANKLINE>
``zc.buildout`` now can also run with `Distribute` with the `--distribute`
option::
>>> print 'X'; print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py --distribute'); print 'X' # doctest: +ELLIPSIS
...
X
...
Generated script '/sample/bin/buildout'...
X
Let's make sure the generated ``site.py`` uses it::
>>> print open(buildout_site_py).read() # doctest: +ELLIPSIS
"...
buildout_paths = [
'/sample/eggs/distribute-...egg',
'/sample/eggs/zc.buildout-99.99-pyN.N.egg'
]
...
Make sure both options can be used together::
>>> print 'X'; print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py --distribute --version 1.2.1'); print 'X'
... # doctest: +ELLIPSIS
...
X
...
Generated script '/sample/bin/buildout'...
X
Let's make sure the old-style generated ``buildout`` script uses
``Distribute`` *and* ``zc.buildout-1.2.1``::
>>> print open(buildout_script).read() # doctest: +ELLIPSIS
#...
<BLANKLINE>
import sys
sys.path[0:0] = [
'/sample/eggs/distribute-...egg',
'/sample/eggs/zc.buildout-1.2.1...egg',
]
<BLANKLINE>
import zc.buildout.buildout
<BLANKLINE>
if __name__ == '__main__':
zc.buildout.buildout.main()
<BLANKLINE>
Last, the -c option needs to work on bootstrap.py::
>>> conf_file = os.path.join(sample_buildout, 'other.cfg')
>>> f = open(conf_file, 'w')
>>> f.write('[buildout]\nparts=\n\n')
>>> f.close()
>>> print 'X'; print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py -c %s --distribute' % conf_file); print 'X' # doctest: +ELLIPSIS
...
X
...
Generated script '/sample/bin/buildout'...
X
You can specify a location of ez_setup.py or distribute_setup, so you
can rely on a local or remote location. We'll write our own ez_setup.py
that we will also use to test some other bootstrap options.
>>> write('ez_setup.py', '''\
... def use_setuptools(**kwargs):
... import sys, pprint
... pprint.pprint(kwargs, width=40)
... sys.exit()
... ''')
>>> print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py --setup-source=./ez_setup.py')
... # doctest: +ELLIPSIS
{'download_delay': 0,
'to_dir': '...'}
<BLANKLINE>
You can also pass a download-cache, and a place in which eggs should be stored
(they are normally stored in a temporary directory).
>>> print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py --setup-source=./ez_setup.py '+
... '--download-base=./download-cache --eggs=eggs')
... # doctest: +ELLIPSIS
{'download_base': '/sample/download-cache/',
'download_delay': 0,
'to_dir': '/sample/eggs'}
<BLANKLINE>
Here's the entire help text.
>>> print system(
... zc.buildout.easy_install._safe_arg(sys.executable)+' '+
... 'bootstrap.py --help'),
... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
Usage: [DESIRED PYTHON FOR BUILDOUT] bootstrap.py [options]
<BLANKLINE>
Bootstraps a buildout-based project.
<BLANKLINE>
Simply run this script in a directory containing a buildout.cfg, using the
Python that you want bin/buildout to use.
<BLANKLINE>
Note that by using --setup-source and --download-base to point to
local resources, you can keep this script from going over the network.
<BLANKLINE>
<BLANKLINE>
Options:
-h, --help show this help message and exit
-v VERSION, --version=VERSION
use a specific zc.buildout version
-d, --distribute Use Distribute rather than Setuptools.
--setup-source=SETUP_SOURCE
Specify a URL or file location for the setup file. If
you use Setuptools, this will default to
http://peak.telecommunity.com/dist/ez_setup.py; if you
use Distribute, this will default to http://python-
distribute.org/distribute_setup.py.
--download-base=DOWNLOAD_BASE
Specify a URL or directory for downloading zc.buildout
and either Setuptools or Distribute. Defaults to PyPI.
--eggs=EGGS Specify a directory for storing eggs. Defaults to a
temporary directory that is deleted when the bootstrap
script completes.
-t, --accept-buildout-test-releases
Normally, if you do not specify a --version, the
bootstrap script and buildout gets the newest *final*
versions of zc.buildout and its recipes and extensions
for you. If you use this flag, bootstrap and buildout
will get the newest releases even if they are alphas
or betas.
-c CONFIG_FILE Specify the path to the buildout configuration file to
be used.