********************************
Buildout Egg-Installation Recipe
********************************
.. contents::
The egg-installation recipe installs eggs into a buildout eggs
directory. It also generates scripts in a buildout bin directory with
egg paths baked into them.
Change History
**************
2.0.7 (2018-07-02)
==================
- For the 2.0.6 change, we require zc.buildout 2.12.0. The `install_requires`
in `setup.py` now also says that.
2.0.6 (2018-07-02)
==================
- Added extra keyword argument ``allow_unknown_extras`` to support zc.buildout
2.12.0.
2.0.5 (2017-12-04)
==================
- Fixed #429: added sorting of working set by priority of different
type of paths (develop-eggs-directory, eggs-directory, other paths).
2.0.4 (2017-08-17)
==================
- Fixed #153: buildout should cache working set environments
[rafaelbco]
2.0.3 (2015-10-02)
==================
- Releasing zc.recipe.egg as a wheel in addition to only an sdist. No
functional changes.
[reinout]
2.0.2 (2015-07-01)
==================
- Fixed: In ``zc.recipe.egg#custom`` recipe's ``rpath`` support, don't
assume path elements are buildout-relative if they start with one of the
"special" tokens (e.g., ``$ORIGIN``). See:
https://github.com/buildout/buildout/issues/225.
[tseaver]
2.0.1 (2013-09-05)
==================
- Accomodated ``zc.buildout`` switch to post-merge ``setuptools``.
2.0.0 (2013-04-02)
==================
- Enabled 'prefer-final' option by default.
2.0.0a3 (2012-11-19)
====================
- Added support for Python 3.2 / 3.3.
- Added 'MANIFEST.in'.
- Support non-entry-point-based scripts.
- Honor exit codes from scripts (https://bugs.launchpad.net/bugs/697913).
2.0.0a2 (2012-05-03)
====================
- Always unzip installed eggs.
- Switched from using 'setuptools' to 'distribute'.
- Removed multi-python support.
1.3.2 (2010-08-23)
==================
- Bugfix for the change introduced in 1.3.1.
1.3.1 (2010-08-23)
==================
- Support recipes that are using zc.recipe.egg by passing in a dict, rather
than a zc.buildout.buildout.Options object as was expected/tested.
1.3.0 (2010-08-23)
==================
- Small further refactorings past 1.2.3b1 to be compatible with
zc.buildout 1.5.0.
1.2.3b1 (2010-04-29)
====================
- Refactored to be used with z3c.recipe.scripts and zc.buildout 1.5.0.
No new user-visible features.
1.2.2 (2009-03-18)
==================
- Fixed a dependency information. zc.buildout >1.2.0 is required.
1.2.1 (2009-03-18)
==================
- Refactored generation of relative egg paths to generate simpler code.
1.2.0 (2009-03-17)
==================
- Added the `dependent-scripts` option. When set to `true`, scripts will
be generated for all required eggs in addition to the eggs named
specifically. This idea came from two forks of this recipe,
`repoze.recipe.egg` and `pylons_sandbox`, but the option name is
spelled with a dash instead of underscore and it defaults to `false`.
- Added a relative-paths option. When true, egg paths in scripts are generated
relative to the script names.
1.1.0 (2008-07-19)
==================
- Refactored to work honor the new buildout-level unzip option.
1.1.0b1 (2008-06-27)
====================
- Added `environment` option to custom extension building options.
1.0.0 (2007-11-03)
==================
- No code changes from last beta, just some small package meta-data
improvements.
1.0.0b5 (2007-02-08)
====================
Feature Changes
---------------
- Added support for the buildout newest option.
1.0.0b4 (2007-01-17)
====================
Feature Changes
---------------
- Added initialization and arguments options to the scripts recipe.
- Added an eggs recipe that *just* installs eggs.
- Advertized the scripts recipe for creating scripts.
1.0.0b3 (2006-12-04)
====================
Feature Changes
---------------
- Added a develop recipe for creating develop eggs.
This is useful to:
- Specify custom extension building options,
- Specify a version of Python to use, and to
- Cause develop eggs to be created after other parts.
- The develop and build recipes now return the paths created, so that
created eggs or egg links are removed when a part is removed (or
changed).
1.0.0b2 (2006-10-16)
====================
Updated to work with (not get a warning from) zc.buildout 1.0.0b10.
1.0.0b1
=======
Updated to work with zc.buildout 1.0.0b3.
1.0.0a3
=======
- Extra path elements to be included in generated scripts can now be
set via the extra-paths option.
- No longer implicitly generate "py\_" scripts for each egg. There is
now an interpreter option to generate a script that, when run
without arguments, launches the Python interactive interpreter with
the path set based on a parts eggs and extra paths. If this script
is run with the name of a Python script and arguments, then the
given script is run with the path set.
- You can now specify explicit entry points. This is useful for use
with packages that don't declare their own entry points.
- Added Windows support.
- Now-longer implicitly generate "py\_" scripts for each egg. You can
now generate a script for launching a Python interpreter or for
running scripts based on the eggs defined for an egg part.
- You can now specify custom entry points for packages that don't
declare their entry points.
- You can now specify extra-paths to be included in generated scripts.
1.0.0a2
=======
Added a custom recipe for building custom eggs using custom distutils
build_ext arguments.
1.0.0a1
=======
Initial public version
Detailed Documentation
**********************
Installation of distributions as eggs
=====================================
The zc.recipe.egg:eggs recipe can be used to install various types if
distutils distributions as eggs. It takes a number of options:
eggs
A list of eggs to install given as one or more setuptools
requirement strings. Each string must be given on a separate
line.
find-links
A list of URLs, files, or directories to search for distributions.
index
The URL of an index server, or almost any other valid URL. :)
If not specified, the Python Package Index,
http://cheeseshop.python.org/pypi, is used. You can specify an
alternate index with this option. If you use the links option and
if the links point to the needed distributions, then the index can
be anything and will be largely ignored. In the examples, here,
we'll just point to an empty directory on our link server. This
will make our examples run a little bit faster.
We have a link server that has a number of distributions:
>>> print_(get(link_server), end='')
<html><body>
<a href="bigdemo-0.1-py2.3.egg">bigdemo-0.1-py2.3.egg</a><br>
<a href="demo-0.1-py2.3.egg">demo-0.1-py2.3.egg</a><br>
<a href="demo-0.2-py2.3.egg">demo-0.2-py2.3.egg</a><br>
<a href="demo-0.3-py2.3.egg">demo-0.3-py2.3.egg</a><br>
<a href="demo-0.4rc1-py2.3.egg">demo-0.4rc1-py2.3.egg</a><br>
<a href="demoneeded-1.0.zip">demoneeded-1.0.zip</a><br>
<a href="demoneeded-1.1.zip">demoneeded-1.1.zip</a><br>
<a href="demoneeded-1.2rc1.zip">demoneeded-1.2rc1.zip</a><br>
<a href="du_zipped-1.0-pyN.N.egg">du_zipped-1.0-pyN.N.egg</a><br>
<a href="extdemo-1.4.zip">extdemo-1.4.zip</a><br>
<a href="index/">index/</a><br>
<a href="mixedcase-0.5.zip">mixedcase-0.5.zip</a><br>
<a href="other-1.0-py2.3.egg">other-1.0-py2.3.egg</a><br>
</body></html>
We have a sample buildout. Let's update it's configuration file to
install the demo package.
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg:eggs
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server))
In this example, we limited ourselves to revisions before 0.3. We also
specified where to find distributions using the find-links option.
Let's run the buildout:
>>> import os
>>> print_(system(buildout), end='')
Installing demo.
Getting distribution for 'demo<0.3'.
Got demo 0.2.
Getting distribution for 'demoneeded'.
Got demoneeded 1.1.
Now, if we look at the buildout eggs directory:
>>> ls(sample_buildout, 'eggs')
d demo-0.2-py2.3.egg
d demoneeded-1.1-py2.3.egg
- setuptools-0.7-py2.3.egg
d zc.buildout-1.0-py2.3.egg
We see that we got an egg for demo that met the requirement, as well
as the egg for demoneeded, which demo requires. (We also see an egg
link for the recipe in the develop-eggs directory. This egg link was
actually created as part of the sample buildout setup. Normally, when
using the recipe, you'll get a regular egg installation.)
Script generation
-----------------
The demo egg defined a script, but we didn't get one installed:
>>> ls(sample_buildout, 'bin')
- buildout
If we want scripts provided by eggs to be installed, we should use the
scripts recipe:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg:scripts
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/demo'.
Now we also see the script defined by the demo script:
>>> ls(sample_buildout, 'bin')
- buildout
- demo
The scripts recipe defines some additional options:
entry-points
A list of entry-point identifiers of the form:
name=module:attrs
where name is a script name, module is a dotted name resolving to a
module name, and attrs is a dotted name resolving to a callable
object within a module.
This option is useful when working with distributions that don't
declare entry points, such as distributions not written to work
with setuptools.
Examples can be seen in the section "Specifying entry points" below.
scripts
Control which scripts are generated. The value should be a list of
zero or more tokens. Each token is either a name, or a name
followed by an '=' and a new name. Only the named scripts are
generated. If no tokens are given, then script generation is
disabled. If the option isn't given at all, then all scripts
defined by the named eggs will be generated.
dependent-scripts
If set to the string "true", scripts will be generated for all
required eggs in addition to the eggs specifically named.
interpreter
The name of a script to generate that allows access to a Python
interpreter that has the path set based on the eggs installed.
extra-paths
Extra paths to include in a generated script.
initialization
Specify some Python initialization code. This is very limited. In
particular, be aware that leading whitespace is stripped from the
code given.
arguments
Specify some arguments to be passed to entry points as Python source.
relative-paths
If set to true, then egg paths will be generated relative to the
script path. This allows a buildout to be moved without breaking
egg paths. This option can be set in either the script section or
in the buildout section.
Let's add an interpreter option:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... interpreter = py-demo
... """ % dict(server=link_server))
Note that we omitted the entry point name from the recipe
specification. We were able to do this because the scripts recipe is
the default entry point for the zc.recipe.egg egg.
>>> print_(system(buildout), end='')
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/demo'.
Generated interpreter '/sample-buildout/bin/py-demo'.
Now we also get a py-demo script for giving us a Python prompt with
the path for demo and any eggs it depends on included in sys.path.
This is useful for debugging and testing.
>>> ls(sample_buildout, 'bin')
- buildout
- demo
- py-demo
If we run the demo script, it prints out some minimal data:
>>> print_(system(join(sample_buildout, 'bin', 'demo')), end='')
2 1
The value it prints out happens to be some values defined in the
modules installed.
We can also run the py-demo script. Here we'll just print_(out)
the bits if the path added to reflect the eggs:
>>> print_(system(join(sample_buildout, 'bin', 'py-demo'),
... """import os, sys
... for p in sys.path:
... if 'demo' in p:
... _ = sys.stdout.write(os.path.basename(p)+'\\n')
...
... """).replace('>>> ', '').replace('... ', ''), end='')
... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
demo-0.2-py2.4.egg
demoneeded-1.1-py2.4.egg...
Egg updating
------------
The recipe normally gets the most recent distribution that satisfies the
specification. It won't do this is the buildout is either in
non-newest mode or in offline mode. To see how this works, we'll
remove the restriction on demo:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server))
and run the buildout in non-newest mode:
>>> print_(system(buildout+' -N'), end='')
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/demo'.
Note that we removed the eggs option, and the eggs defaulted to the
part name. Because we removed the eggs option, the demo was
reinstalled.
We'll also run the buildout in off-line mode:
>>> print_(system(buildout+' -o'), end='')
Updating demo.
We didn't get an update for demo:
>>> ls(sample_buildout, 'eggs')
d demo-0.2-py2.3.egg
d demoneeded-1.1-py2.3.egg
- setuptools-0.7-py2.3.egg
d zc.buildout-1.0-py2.3.egg
If we run the buildout on the default online and newest modes,
we'll get an update for demo:
>>> print_(system(buildout), end='')
Updating demo.
Getting distribution for 'demo'.
Got demo 0.3.
Generated script '/sample-buildout/bin/demo'.
Then we'll get a new demo egg:
>>> ls(sample_buildout, 'eggs')
d demo-0.2-py2.3.egg
d demo-0.3-py2.3.egg
d demoneeded-1.1-py2.3.egg
- setuptools-0.7-py2.4.egg
d zc.buildout-1.0-py2.4.egg
The script is updated too:
>>> print_(system(join(sample_buildout, 'bin', 'demo')), end='')
3 1
Controlling script generation
-----------------------------
You can control which scripts get generated using the scripts option.
For example, to suppress scripts, use the scripts option without any
arguments:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg
... find-links = %(server)s
... index = %(server)s/index
... scripts =
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Uninstalling demo.
Installing demo.
>>> ls(sample_buildout, 'bin')
- buildout
You can also control the name used for scripts:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg
... find-links = %(server)s
... index = %(server)s/index
... scripts = demo=foo
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/foo'.
>>> ls(sample_buildout, 'bin')
- buildout
- foo
Specifying extra script paths
-----------------------------
If we need to include extra paths in a script, we can use the
extra-paths option:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg
... find-links = %(server)s
... index = %(server)s/index
... scripts = demo=foo
... extra-paths =
... /foo/bar
... ${buildout:directory}/spam
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/foo'.
Let's look at the script that was generated:
>>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE
#!/usr/local/bin/python2.7
<BLANKLINE>
import sys
sys.path[0:0] = [
'/sample-buildout/eggs/demo-0.3-py2.4.egg',
'/sample-buildout/eggs/demoneeded-1.1-py2.4.egg',
'/foo/bar',
'/sample-buildout/spam',
]
<BLANKLINE>
import eggrecipedemo
<BLANKLINE>
if __name__ == '__main__':
sys.exit(eggrecipedemo.main())
Relative egg paths
------------------
If the relative-paths option is specified with a true value, then
paths will be generated relative to the script. This is useful when
you want to be able to move a buildout directory around without
breaking scripts.
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg
... find-links = %(server)s
... index = %(server)s/index
... scripts = demo=foo
... relative-paths = true
... extra-paths =
... /foo/bar
... ${buildout:directory}/spam
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/foo'.
Let's look at the script that was generated:
>>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE
#!/usr/local/bin/python2.7
<BLANKLINE>
import os
<BLANKLINE>
join = os.path.join
base = os.path.dirname(os.path.abspath(os.path.realpath(__file__)))
base = os.path.dirname(base)
<BLANKLINE>
import sys
sys.path[0:0] = [
join(base, 'eggs/demo-0.3-pyN.N.egg'),
join(base, 'eggs/demoneeded-1.1-pyN.N.egg'),
'/foo/bar',
join(base, 'spam'),
]
<BLANKLINE>
import eggrecipedemo
<BLANKLINE>
if __name__ == '__main__':
sys.exit(eggrecipedemo.main())
You can specify relative paths in the buildout section, rather than in
each individual script section:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
... relative-paths = true
...
... [demo]
... recipe = zc.recipe.egg
... find-links = %(server)s
... index = %(server)s/index
... scripts = demo=foo
... extra-paths =
... /foo/bar
... ${buildout:directory}/spam
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/foo'.
>>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE
#!/usr/local/bin/python2.7
<BLANKLINE>
import os
<BLANKLINE>
join = os.path.join
base = os.path.dirname(os.path.abspath(os.path.realpath(__file__)))
base = os.path.dirname(base)
<BLANKLINE>
import sys
sys.path[0:0] = [
join(base, 'eggs/demo-0.3-pyN.N.egg'),
join(base, 'eggs/demoneeded-1.1-pyN.N.egg'),
'/foo/bar',
join(base, 'spam'),
]
<BLANKLINE>
import eggrecipedemo
<BLANKLINE>
if __name__ == '__main__':
sys.exit(eggrecipedemo.main())
Specifying initialization code and arguments
-----------------------------------------------
Sometimes, we need to do more than just calling entry points. We can
use the initialization and arguments options to specify extra code
to be included in generated scripts:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg
... find-links = %(server)s
... index = %(server)s/index
... scripts = demo=foo
... extra-paths =
... /foo/bar
... ${buildout:directory}/spam
... initialization = a = (1, 2
... 3, 4)
... interpreter = py
... arguments = a, 2
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/foo'.
Generated interpreter '/sample-buildout/bin/py'.
>>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE
#!/usr/local/bin/python2.7
<BLANKLINE>
import sys
sys.path[0:0] = [
'/sample-buildout/eggs/demo-0.3-py2.4.egg',
'/sample-buildout/eggs/demoneeded-1.1-py2.4.egg',
'/foo/bar',
'/sample-buildout/spam',
]
<BLANKLINE>
a = (1, 2
3, 4)
<BLANKLINE>
import eggrecipedemo
<BLANKLINE>
if __name__ == '__main__':
sys.exit(eggrecipedemo.main(a, 2))
Here we see that the initialization code we specified was added after
setting the path. Note, as mentioned above, that leading whitespace
has been stripped. Similarly, the argument code we specified was
added in the entry point call (to main).
Our interpreter also has the initialization code:
>>> cat(sample_buildout, 'bin', 'py')
... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
#!/usr/local/bin/python2.7
<BLANKLINE>
import sys
<BLANKLINE>
sys.path[0:0] = [
'/sample-buildout/eggs/demo-0.3-py3.3.egg',
'/sample-buildout/eggs/demoneeded-1.1-py3.3.egg',
'/foo/bar',
'/sample-buildout/spam',
]
<BLANKLINE>
a = (1, 2
3, 4)
<BLANKLINE>
<BLANKLINE>
_interactive = True
...
Specifying entry points
-----------------------
Scripts can be generated for entry points declared explicitly. We can
declare entry points using the entry-points option:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = zc.recipe.egg
... find-links = %(server)s
... index = %(server)s/index
... extra-paths =
... /foo/bar
... ${buildout:directory}/spam
... entry-points = alt=eggrecipedemo:alt other=foo.bar:a.b.c
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/demo'.
Generated script '/sample-buildout/bin/alt'.
Generated script '/sample-buildout/bin/other'.
>>> ls(sample_buildout, 'bin')
- alt
- buildout
- demo
- other
>>> cat(sample_buildout, 'bin', 'other')
#!/usr/local/bin/python2.7
<BLANKLINE>
import sys
sys.path[0:0] = [
'/sample-buildout/eggs/demo-0.3-py2.4.egg',
'/sample-buildout/eggs/demoneeded-1.1-py2.4.egg',
'/foo/bar',
'/sample-buildout/spam',
]
<BLANKLINE>
import foo.bar
<BLANKLINE>
if __name__ == '__main__':
sys.exit(foo.bar.a.b.c())
Generating all scripts
----------------------
The `bigdemo` package doesn't have any scripts, but it requires the `demo`
package, which does have a script. Specify `dependent-scripts = true` to
generate all scripts in required packages:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = bigdemo
...
... [bigdemo]
... recipe = zc.recipe.egg
... find-links = %(server)s
... index = %(server)s/index
... dependent-scripts = true
... """ % dict(server=link_server))
>>> print_(system(buildout+' -N'), end='')
Uninstalling demo.
Installing bigdemo.
Getting distribution for 'bigdemo'.
Got bigdemo 0.1.
Generated script '/sample-buildout/bin/demo'.
Offline mode
------------
If the buildout offline option is set to "true", then no attempt will
be made to contact an index server:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
... offline = true
...
... [demo]
... recipe = zc.recipe.egg
... index = eek!
... scripts = demo=foo
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Uninstalling bigdemo.
Installing demo.
Generated script '/sample-buildout/bin/foo'.
Creating eggs with extensions needing custom build settings
=============================================================
Sometimes, It's necessary to provide extra control over how an egg is
created. This is commonly true for eggs with extension modules that
need to access libraries or include files.
The zc.recipe.egg:custom recipe can be used to define an egg with
custom build parameters. The currently defined parameters are:
include-dirs
A new-line separated list of directories to search for include
files.
library-dirs
A new-line separated list of directories to search for libraries
to link with.
rpath
A new-line separated list of directories to search for dynamic libraries
at run time.
define
A comma-separated list of names of C preprocessor variables to
define.
undef
A comma-separated list of names of C preprocessor variables to
undefine.
libraries
The name of an additional library to link with. Due to limitations
in distutils and despite the option name, only a single library
can be specified.
link-objects
The name of an link object to link against. Due to limitations
in distutils and despite the option name, only a single link object
can be specified.
debug
Compile/link with debugging information
force
Forcibly build everything (ignore file timestamps)
compiler
Specify the compiler type
swig
The path to the swig executable
swig-cpp
Make SWIG create C++ files (default is C)
swig-opts
List of SWIG command line options
In addition, the following options can be used to specify the egg:
egg
An specification for the egg to be created, to install given as a
setuptools requirement string. This defaults to the part name.
find-links
A list of URLs, files, or directories to search for distributions.
index
The URL of an index server, or almost any other valid URL. :)
If not specified, the Python Package Index,
http://cheeseshop.python.org/pypi, is used. You can specify an
alternate index with this option. If you use the links option and
if the links point to the needed distributions, then the index can
be anything and will be largely ignored. In the examples, here,
we'll just point to an empty directory on our link server. This
will make our examples run a little bit faster.
environment
The name of a section with additional environment variables. The
environment variables are set before the egg is built.
To illustrate this, we'll define a buildout that builds an egg for a
package that has a simple extension module::
#include <Python.h>
#include <extdemo.h>
static PyMethodDef methods[] = {};
PyMODINIT_FUNC
initextdemo(void)
{
PyObject *m;
m = Py_InitModule3("extdemo", methods, "");
#ifdef TWO
PyModule_AddObject(m, "val", PyInt_FromLong(2));
#else
PyModule_AddObject(m, "val", PyInt_FromLong(EXTDEMO));
#endif
}
The extension depends on a system-dependent include file, extdemo.h,
that defines a constant, EXTDEMO, that is exposed by the extension.
The extension module is available as a source distribution,
extdemo-1.4.tar.gz, on a distribution server.
We have a sample buildout that we'll add an include directory to with
the necessary include file:
>>> mkdir('include')
>>> write('include', 'extdemo.h',
... """
... #define EXTDEMO 42
... """)
We'll also update the buildout configuration file to define a part for
the egg:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = extdemo
...
... [extdemo]
... recipe = zc.recipe.egg:custom
... find-links = %(server)s
... index = %(server)s/index
... include-dirs = include
...
... """ % dict(server=link_server))
>>> print_(system(buildout), end='') # doctest: +ELLIPSIS
Installing extdemo...
We got the zip_safe warning because the source distribution we used
wasn't setuptools based and thus didn't set the option.
The egg is created in the develop-eggs directory *not* the eggs
directory because it depends on buildout-specific parameters and the
eggs directory can be shared across multiple buildouts.
>>> ls(sample_buildout, 'develop-eggs')
d extdemo-1.4-py2.4-unix-i686.egg
- zc.recipe.egg.egg-link
Note that no scripts or dependencies are installed. To install
dependencies or scripts for a custom egg, define another part and use
the zc.recipe.egg recipe, listing the custom egg as one of the eggs to
be installed. The zc.recipe.egg recipe will use the installed egg.
Let's define a script that uses out ext demo:
>>> mkdir('demo')
>>> write('demo', 'demo.py',
... """
... import extdemo, sys
... def print_(*args):
... sys.stdout.write(' '.join(map(str, args)) + '\\n')
... def main():
... print_(extdemo.val)
... """)
>>> write('demo', 'setup.py',
... """
... from setuptools import setup
... setup(name='demo')
... """)
>>> write('buildout.cfg',
... """
... [buildout]
... develop = demo
... parts = extdemo demo
...
... [extdemo]
... recipe = zc.recipe.egg:custom
... find-links = %(server)s
... index = %(server)s/index
... include-dirs = include
...
... [demo]
... recipe = zc.recipe.egg
... eggs = demo
... extdemo
... entry-points = demo=demo:main
... """ % dict(server=link_server))
>>> print_(system(buildout), end='')
Develop: '/sample-buildout/demo'
Updating extdemo.
Installing demo.
Generated script '/sample-buildout/bin/demo'...
When we run the script, we'll 42 printed:
>>> print_(system(join('bin', 'demo')), end='')
42
Updating
--------
The custom recipe will normally check for new source distributions
that meet the given specification. This can be suppressed using the
buildout non-newest and offline modes. We'll generate a new source
distribution for extdemo:
>>> update_extdemo()
If we run the buildout in non-newest or offline modes:
>>> print_(system(buildout+' -N'), end='')
Develop: '/sample-buildout/demo'
Updating extdemo.
Updating demo.
>>> print_(system(buildout+' -o'), end='')
Develop: '/sample-buildout/demo'
Updating extdemo.
Updating demo.
We won't get an update.
>>> ls(sample_buildout, 'develop-eggs')
- demo.egg-link
d extdemo-1.4-py2.4-unix-i686.egg
- zc.recipe.egg.egg-link
But if we run the buildout in the default on-line and newest modes, we
will. This time we also get the test-variable message again, because the new
version is imported:
>>> print_(system(buildout), end='') # doctest: +ELLIPSIS
Develop: '/sample-buildout/demo'
Updating extdemo.
zip_safe flag not set; analyzing archive contents...
Updating demo.
...
>>> ls(sample_buildout, 'develop-eggs')
- demo.egg-link
d extdemo-1.4-py2.4-linux-i686.egg
d extdemo-1.5-py2.4-linux-i686.egg
- zc.recipe.egg.egg-link
Controlling the version used
----------------------------
We can specify a specific version using the egg option:
>>> write('buildout.cfg',
... """
... [buildout]
... develop = demo
... parts = extdemo demo
...
... [extdemo]
... recipe = zc.recipe.egg:custom
... egg = extdemo ==1.4
... find-links = %(server)s
... index = %(server)s/index
... include-dirs = include
...
... [demo]
... recipe = zc.recipe.egg
... eggs = demo
... extdemo ==1.4
... entry-points = demo=demo:main
... """ % dict(server=link_server))
>>> print_(system(buildout+' -D'), end='') # doctest: +ELLIPSIS
Develop: '/sample-buildout/demo'
...
>>> ls(sample_buildout, 'develop-eggs')
- demo.egg-link
d extdemo-1.4-py2.4-linux-i686.egg
- zc.recipe.egg.egg-link
Controlling environment variables
+++++++++++++++++++++++++++++++++
To set additional environment variables, the `environment` option is used.
Let's create a recipe which prints out environment variables. We need this to
make sure the set environment variables are removed after the egg:custom
recipe was run.
>>> mkdir(sample_buildout, 'recipes')
>>> write(sample_buildout, 'recipes', 'environ.py',
... """
... import logging, os, zc.buildout
...
... class Environ:
...
... def __init__(self, buildout, name, options):
... self.name = name
...
... def install(self):
... logging.getLogger(self.name).info(
... 'test-variable left over: %s' % (
... 'test-variable' in os.environ))
... return []
...
... def update(self):
... self.install()
... """)
>>> write(sample_buildout, 'recipes', 'setup.py',
... """
... from setuptools import setup
...
... setup(
... name = "recipes",
... entry_points = {'zc.buildout': ['environ = environ:Environ']},
... )
... """)
Create our buildout:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... develop = recipes
... parts = extdemo checkenv
...
... [extdemo-env]
... test-variable = foo
...
... [extdemo]
... recipe = zc.recipe.egg:custom
... find-links = %(server)s
... index = %(server)s/index
... include-dirs = include
... environment = extdemo-env
...
... [checkenv]
... recipe = recipes:environ
...
... """ % dict(server=link_server))
>>> print_(system(buildout), end='') # doctest: +ELLIPSIS
Develop: '/sample-buildout/recipes'
Uninstalling demo.
Uninstalling extdemo.
Installing extdemo.
Have environment test-variable: foo
zip_safe flag not set; analyzing archive contents...
Installing checkenv.
...
The setup.py also printed out that we have set the environment `test-variable`
to foo. After the buildout the variable is reset to its original value (i.e.
removed).
When an environment variable has a value before zc.recipe.egg:custom is run,
the original value will be restored:
>>> import os
>>> os.environ['test-variable'] = 'bar'
>>> print_(system(buildout), end='')
Develop: '/sample-buildout/recipes'
Updating extdemo.
Updating checkenv.
checkenv: test-variable left over: True
>>> os.environ['test-variable']
'bar'
Sometimes it is required to prepend or append to an existing environment
variable, for instance for adding something to the PATH. Therefore all variables
are interpolated with os.environ before the're set:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... develop = recipes
... parts = extdemo checkenv
...
... [extdemo-env]
... test-variable = foo:%%(test-variable)s
...
... [extdemo]
... recipe = zc.recipe.egg:custom
... find-links = %(server)s
... index = %(server)s/index
... include-dirs = include
... environment = extdemo-env
...
... [checkenv]
... recipe = recipes:environ
...
... """ % dict(server=link_server))
>>> print_(system(buildout), end='') # doctest: +ELLIPSIS
Develop: '/sample-buildout/recipes'
Uninstalling extdemo.
Installing extdemo.
Have environment test-variable: foo:bar
zip_safe flag not set; analyzing archive contents...
Updating checkenv.
...
>>> os.environ['test-variable']
'bar'
>>> del os.environ['test-variable']
Create a clean buildout.cfg w/o the checkenv recipe, and delete the recipe:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... develop = recipes
... parts = extdemo
...
... [extdemo]
... recipe = zc.recipe.egg:custom
... find-links = %(server)s
... index = %(server)s/index
... include-dirs = include
...
... """ % dict(server=link_server))
>>> print_(system(buildout), end='') # doctest: +ELLIPSIS
Develop: '/sample-buildout/recipes'
Uninstalling checkenv.
Uninstalling extdemo.
Installing extdemo...
>>> rmdir(sample_buildout, 'recipes')
Controlling develop-egg generation
==================================
If you want to provide custom build options for a develop egg, you can
use the develop recipe. The recipe has the following options:
setup
The path to a setup script or directory containing a startup
script. This is required.
include-dirs
A new-line separated list of directories to search for include
files.
library-dirs
A new-line separated list of directories to search for libraries
to link with.
rpath
A new-line separated list of directories to search for dynamic libraries
at run time.
define
A comma-separated list of names of C preprocessor variables to
define.
undef
A comma-separated list of names of C preprocessor variables to
undefine.
libraries
The name of an additional library to link with. Due to limitations
in distutils and despite the option name, only a single library
can be specified.
link-objects
The name of an link object to link against. Due to limitations
in distutils and despite the option name, only a single link object
can be specified.
debug
Compile/link with debugging information
force
Forcibly build everything (ignore file timestamps)
compiler
Specify the compiler type
swig
The path to the swig executable
swig-cpp
Make SWIG create C++ files (default is C)
swig-opts
List of SWIG command line options
To illustrate this, we'll use a directory containing the extdemo
example from the earlier section:
>>> ls(extdemo)
- MANIFEST
- MANIFEST.in
- README
- extdemo.c
- setup.py
>>> write('buildout.cfg',
... """
... [buildout]
... develop = demo
... parts = extdemo demo
...
... [extdemo]
... setup = %(extdemo)s
... recipe = zc.recipe.egg:develop
... include-dirs = include
... define = TWO
...
... [demo]
... recipe = zc.recipe.egg
... eggs = demo
... extdemo
... entry-points = demo=demo:main
... """ % dict(extdemo=extdemo))
Note that we added a define option to cause the preprocessor variable
TWO to be defined. This will cause the module-variable, 'val', to be
set with a value of 2.
>>> print_(system(buildout), end='') # doctest: +ELLIPSIS
Develop: '/sample-buildout/demo'
Uninstalling extdemo.
Installing extdemo.
Installing demo.
...
Our develop-eggs now includes an egg link for extdemo:
>>> ls('develop-eggs')
- demo.egg-link
- extdemo.egg-link
- zc.recipe.egg.egg-link
and the extdemo now has a built extension:
>>> contents = os.listdir(extdemo)
>>> bool([f for f in contents if f.endswith('.so') or f.endswith('.pyd')])
True
Because develop eggs take precedence over non-develop eggs, the demo
script will use the new develop egg:
>>> print_(system(join('bin', 'demo')), end='')
2
Egg Recipe API for other Recipes
================================
It is common for recipes to accept a collection of egg specifications
and generate scripts based on the resulting working sets. The egg
recipe provides an API that other recipes can use.
A recipe can reuse the egg recipe, supporting the eggs, find-links,
index, and extra-paths options. This is done by creating an
egg recipe instance in a recipes's constructor. In the recipe's
install script, the egg-recipe instance's working_set method is used
to collect the requested eggs and working set.
To illustrate, we create a sample recipe that is a very thin layer
around the egg recipe:
>>> mkdir(sample_buildout, 'sample')
>>> write(sample_buildout, 'sample', 'sample.py',
... """
... import logging, os, sys
... import zc.recipe.egg
...
... def print_(*args):
... sys.stdout.write(' '.join(map(str, args)) + '\\n')
...
... class Sample:
...
... def __init__(self, buildout, name, options):
... self.egg = zc.recipe.egg.Scripts(buildout, name, options)
... self.name = name
... self.options = options
...
... def install(self):
... extras = self.options['extras'].split()
... requirements, ws = self.egg.working_set(extras)
... print_('Part:', self.name)
... print_('Egg requirements:')
... for r in requirements:
... print_(r)
... print_('Working set:')
... for d in ws:
... print_(d)
... print_('extra paths:', self.egg.extra_paths)
... return ()
...
... update = install
... """)
Here we instantiated the egg recipe in the constructor, saving it in
an attribute. This also initialized the options dictionary.
In our install method, we called the working_set method on the
instance we saved. The working_set method takes an optional sequence
of extra requirements to be included in the working set.
>>> write(sample_buildout, 'sample', 'setup.py',
... """
... from setuptools import setup
...
... setup(
... name = "sample",
... entry_points = {'zc.buildout': ['default = sample:Sample']},
... install_requires = 'zc.recipe.egg',
... )
... """)
>>> write(sample_buildout, 'sample', 'README.txt', " ")
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... develop = sample
... parts = sample-part
...
... [sample-part]
... recipe = sample
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)sindex
... extras = other
... """ % dict(server=link_server))
>>> import os
>>> os.chdir(sample_buildout)
>>> buildout = os.path.join(sample_buildout, 'bin', 'buildout')
>>> print_(system(buildout + ' -q'), end='')
Part: sample-part
Egg requirements:
demo<0.3
Working set:
demoneeded 1.1
other 1.0
demo 0.2
extra paths: []
We can see that the options were augmented with additional data
computed by the egg recipe by looking at .installed.cfg:
>>> cat(sample_buildout, '.installed.cfg')
[buildout]
installed_develop_eggs = /sample-buildout/develop-eggs/sample.egg-link
parts = sample-part
<BLANKLINE>
[sample-part]
__buildout_installed__ =
__buildout_signature__ = ...
_b = /sample-buildout/bin
_d = /sample-buildout/develop-eggs
_e = /sample-buildout/eggs
bin-directory = /sample-buildout/bin
develop-eggs-directory = /sample-buildout/develop-eggs
eggs = demo<0.3
eggs-directory = /sample-buildout/eggs
extras = other
find-links = http://localhost:27071/
index = http://localhost:27071/index
recipe = sample
If we use the extra-paths option:
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... develop = sample
... parts = sample-part
...
... [sample-part]
... recipe = sample
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)sindex
... extras = other
... extra-paths = /foo/bar
... /spam/eggs
... """ % dict(server=link_server))
Then we'll see that reflected in the extra_paths attribute in the egg
recipe instance:
>>> print_(system(buildout + ' -q'), end='')
Part: sample-part
Egg requirements:
demo<0.3
Working set:
demo 0.2
other 1.0
demoneeded 1.1
extra paths: ['/foo/bar', '/spam/eggs']
Working set caching
===================
Working sets are cached, to improve speed on buildouts with multiple similar
parts based on ``zc.recipe.egg``.
The egg-recipe instance's ``_working_set`` helper method is used to make
the caching easier. It does the same job as ``working_set()`` but with some
differences:
- The signature is different: all information needed to build the working set
is passed as parameters.
- The return value is simpler: only an instance of ``pkg_resources.WorkingSet``
is returned.
Here's an example:
>>> from zc.buildout import testing
>>> from zc.recipe.egg.egg import Eggs
>>> import os
>>> import pkg_resources
>>> recipe = Eggs(buildout=testing.Buildout(), name='fake-part', options={})
>>> eggs_dir = os.path.join(sample_buildout, 'eggs')
>>> develop_eggs_dir = os.path.join(sample_buildout, 'develop-eggs')
>>> testing.install_develop('zc.recipe.egg', develop_eggs_dir)
>>> ws = recipe._working_set(
... distributions=['zc.recipe.egg', 'demo<0.3'],
... eggs_dir=eggs_dir,
... develop_eggs_dir=develop_eggs_dir,
... index=link_server,
... )
Getting...
>>> isinstance(ws, pkg_resources.WorkingSet)
True
>>> sorted(dist.project_name for dist in ws)
['demo', 'demoneeded', 'setuptools', 'zc.buildout', 'zc.recipe.egg']
We'll monkey patch a method in the ``easy_install`` module in order to verify if
the cache is working:
>>> import zc.buildout.easy_install
>>> old_install = zc.buildout.easy_install.Installer.install
>>> def new_install(*args, **kwargs):
... print('Building working set.')
... return old_install(*args, **kwargs)
>>> zc.buildout.easy_install.Installer.install = new_install
Now we check if the caching is working by verifying if the same working set is
built only once.
>>> ws_args_1 = dict(
... distributions=['demo>=0.1'],
... eggs_dir=eggs_dir,
... develop_eggs_dir=develop_eggs_dir,
... offline=True,
... )
>>> ws_args_2 = dict(ws_args_1)
>>> ws_args_2['distributions'] = ['demoneeded']
>>> recipe._working_set(**ws_args_1)
Building working set.
<pkg_resources.WorkingSet object at ...>
>>> recipe._working_set(**ws_args_1)
<pkg_resources.WorkingSet object at ...>
>>> recipe._working_set(**ws_args_2)
Building working set.
<pkg_resources.WorkingSet object at ...>
>>> recipe._working_set(**ws_args_1)
<pkg_resources.WorkingSet object at ...>
>>> recipe._working_set(**ws_args_2)
<pkg_resources.WorkingSet object at ...>
Undo monkey patch:
>>> zc.buildout.easy_install.Installer.install = old_install
Since ``pkg_resources.WorkingSet`` instances are mutable, we must ensure that
``working_set()`` always returns a pristine copy. Otherwise callers would be
able to modify instances inside the cache.
Let's create a working set:
>>> ws = recipe._working_set(**ws_args_1)
>>> sorted(dist.project_name for dist in ws)
['demo', 'demoneeded']
Now we add a distribution to it:
>>> dist = pkg_resources.get_distribution('zc.recipe.egg')
>>> ws.add(dist)
>>> sorted(dist.project_name for dist in ws)
['demo', 'demoneeded', 'zc.recipe.egg']
Let's call the working_set function again and see if the result remains valid:
>>> ws = recipe._working_set(**ws_args_1)
>>> sorted(dist.project_name for dist in ws)
['demo', 'demoneeded']
Download
*********
Raw data
{
"_id": null,
"home_page": "http://cheeseshop.python.org/pypi/zc.recipe.egg",
"name": "zc.recipe.egg",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "development build",
"author": "Jim Fulton",
"author_email": "jim@zope.com",
"download_url": "https://files.pythonhosted.org/packages/7a/6f/c6871e8490a153c3b44ac43e4a6552d802561a12b4780c7ea088a7ec5ff0/zc.recipe.egg-2.0.7.tar.gz",
"platform": "",
"description": "********************************\nBuildout Egg-Installation Recipe\n********************************\n\n.. contents::\n\nThe egg-installation recipe installs eggs into a buildout eggs\ndirectory. It also generates scripts in a buildout bin directory with \negg paths baked into them.\n\n\nChange History\n**************\n\n2.0.7 (2018-07-02)\n==================\n\n- For the 2.0.6 change, we require zc.buildout 2.12.0. The `install_requires`\n in `setup.py` now also says that.\n\n\n2.0.6 (2018-07-02)\n==================\n\n- Added extra keyword argument ``allow_unknown_extras`` to support zc.buildout\n 2.12.0.\n\n\n2.0.5 (2017-12-04)\n==================\n\n- Fixed #429: added sorting of working set by priority of different\n type of paths (develop-eggs-directory, eggs-directory, other paths).\n\n\n2.0.4 (2017-08-17)\n==================\n\n- Fixed #153: buildout should cache working set environments\n [rafaelbco]\n\n\n2.0.3 (2015-10-02)\n==================\n\n- Releasing zc.recipe.egg as a wheel in addition to only an sdist. No\n functional changes.\n [reinout]\n\n2.0.2 (2015-07-01)\n==================\n\n- Fixed: In ``zc.recipe.egg#custom`` recipe's ``rpath`` support, don't\n assume path elements are buildout-relative if they start with one of the\n \"special\" tokens (e.g., ``$ORIGIN``). See:\n https://github.com/buildout/buildout/issues/225.\n [tseaver]\n\n2.0.1 (2013-09-05)\n==================\n\n- Accomodated ``zc.buildout`` switch to post-merge ``setuptools``.\n\n2.0.0 (2013-04-02)\n==================\n\n- Enabled 'prefer-final' option by default.\n\n2.0.0a3 (2012-11-19)\n====================\n\n- Added support for Python 3.2 / 3.3.\n\n- Added 'MANIFEST.in'.\n\n- Support non-entry-point-based scripts.\n\n- Honor exit codes from scripts (https://bugs.launchpad.net/bugs/697913).\n\n2.0.0a2 (2012-05-03)\n====================\n\n- Always unzip installed eggs.\n\n- Switched from using 'setuptools' to 'distribute'.\n\n- Removed multi-python support.\n\n1.3.2 (2010-08-23)\n==================\n\n- Bugfix for the change introduced in 1.3.1.\n\n1.3.1 (2010-08-23)\n==================\n\n- Support recipes that are using zc.recipe.egg by passing in a dict, rather\n than a zc.buildout.buildout.Options object as was expected/tested.\n\n1.3.0 (2010-08-23)\n==================\n\n- Small further refactorings past 1.2.3b1 to be compatible with\n zc.buildout 1.5.0.\n\n1.2.3b1 (2010-04-29)\n====================\n\n- Refactored to be used with z3c.recipe.scripts and zc.buildout 1.5.0.\n No new user-visible features.\n\n1.2.2 (2009-03-18)\n==================\n\n- Fixed a dependency information. zc.buildout >1.2.0 is required.\n\n1.2.1 (2009-03-18)\n==================\n\n- Refactored generation of relative egg paths to generate simpler code.\n\n1.2.0 (2009-03-17)\n==================\n\n- Added the `dependent-scripts` option. When set to `true`, scripts will\n be generated for all required eggs in addition to the eggs named\n specifically. This idea came from two forks of this recipe,\n `repoze.recipe.egg` and `pylons_sandbox`, but the option name is\n spelled with a dash instead of underscore and it defaults to `false`.\n\n- Added a relative-paths option. When true, egg paths in scripts are generated\n relative to the script names.\n\n1.1.0 (2008-07-19)\n==================\n\n- Refactored to work honor the new buildout-level unzip option.\n\n\n1.1.0b1 (2008-06-27)\n====================\n\n- Added `environment` option to custom extension building options.\n\n1.0.0 (2007-11-03)\n==================\n\n- No code changes from last beta, just some small package meta-data\n improvements.\n\n1.0.0b5 (2007-02-08)\n====================\n\nFeature Changes\n---------------\n\n- Added support for the buildout newest option.\n\n1.0.0b4 (2007-01-17)\n====================\n\nFeature Changes\n---------------\n\n- Added initialization and arguments options to the scripts recipe.\n\n- Added an eggs recipe that *just* installs eggs.\n\n- Advertized the scripts recipe for creating scripts.\n\n1.0.0b3 (2006-12-04)\n====================\n\nFeature Changes\n---------------\n\n- Added a develop recipe for creating develop eggs.\n\n This is useful to:\n\n - Specify custom extension building options,\n\n - Specify a version of Python to use, and to\n\n - Cause develop eggs to be created after other parts.\n\n- The develop and build recipes now return the paths created, so that\n created eggs or egg links are removed when a part is removed (or\n changed).\n\n\n1.0.0b2 (2006-10-16)\n====================\n\nUpdated to work with (not get a warning from) zc.buildout 1.0.0b10.\n\n1.0.0b1\n=======\n\nUpdated to work with zc.buildout 1.0.0b3.\n\n1.0.0a3\n=======\n\n- Extra path elements to be included in generated scripts can now be\n set via the extra-paths option.\n\n- No longer implicitly generate \"py\\_\" scripts for each egg. There is\n now an interpreter option to generate a script that, when run\n without arguments, launches the Python interactive interpreter with\n the path set based on a parts eggs and extra paths. If this script\n is run with the name of a Python script and arguments, then the\n given script is run with the path set.\n\n- You can now specify explicit entry points. This is useful for use\n with packages that don't declare their own entry points.\n\n- Added Windows support.\n\n- Now-longer implicitly generate \"py\\_\" scripts for each egg. You can\n now generate a script for launching a Python interpreter or for\n running scripts based on the eggs defined for an egg part.\n\n- You can now specify custom entry points for packages that don't\n declare their entry points.\n\n- You can now specify extra-paths to be included in generated scripts.\n\n\n1.0.0a2\n=======\n\nAdded a custom recipe for building custom eggs using custom distutils\nbuild_ext arguments.\n\n1.0.0a1\n=======\n\nInitial public version\n\nDetailed Documentation\n**********************\n\nInstallation of distributions as eggs\n=====================================\n\nThe zc.recipe.egg:eggs recipe can be used to install various types if\ndistutils distributions as eggs. It takes a number of options:\n\neggs\n A list of eggs to install given as one or more setuptools\n requirement strings. Each string must be given on a separate\n line.\n\nfind-links\n A list of URLs, files, or directories to search for distributions.\n\nindex\n The URL of an index server, or almost any other valid URL. :)\n\n If not specified, the Python Package Index,\n http://cheeseshop.python.org/pypi, is used. You can specify an\n alternate index with this option. If you use the links option and\n if the links point to the needed distributions, then the index can\n be anything and will be largely ignored. In the examples, here,\n we'll just point to an empty directory on our link server. This\n will make our examples run a little bit faster.\n\nWe have a link server that has a number of distributions:\n\n >>> print_(get(link_server), end='')\n <html><body>\n <a href=\"bigdemo-0.1-py2.3.egg\">bigdemo-0.1-py2.3.egg</a><br>\n <a href=\"demo-0.1-py2.3.egg\">demo-0.1-py2.3.egg</a><br>\n <a href=\"demo-0.2-py2.3.egg\">demo-0.2-py2.3.egg</a><br>\n <a href=\"demo-0.3-py2.3.egg\">demo-0.3-py2.3.egg</a><br>\n <a href=\"demo-0.4rc1-py2.3.egg\">demo-0.4rc1-py2.3.egg</a><br>\n <a href=\"demoneeded-1.0.zip\">demoneeded-1.0.zip</a><br>\n <a href=\"demoneeded-1.1.zip\">demoneeded-1.1.zip</a><br>\n <a href=\"demoneeded-1.2rc1.zip\">demoneeded-1.2rc1.zip</a><br>\n <a href=\"du_zipped-1.0-pyN.N.egg\">du_zipped-1.0-pyN.N.egg</a><br>\n <a href=\"extdemo-1.4.zip\">extdemo-1.4.zip</a><br>\n <a href=\"index/\">index/</a><br>\n <a href=\"mixedcase-0.5.zip\">mixedcase-0.5.zip</a><br>\n <a href=\"other-1.0-py2.3.egg\">other-1.0-py2.3.egg</a><br>\n </body></html>\n\nWe have a sample buildout. Let's update it's configuration file to\ninstall the demo package.\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg:eggs\n ... eggs = demo<0.3\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... \"\"\" % dict(server=link_server))\n\nIn this example, we limited ourselves to revisions before 0.3. We also\nspecified where to find distributions using the find-links option.\n\nLet's run the buildout:\n\n >>> import os\n >>> print_(system(buildout), end='')\n Installing demo.\n Getting distribution for 'demo<0.3'.\n Got demo 0.2.\n Getting distribution for 'demoneeded'.\n Got demoneeded 1.1.\n\nNow, if we look at the buildout eggs directory:\n\n >>> ls(sample_buildout, 'eggs')\n d demo-0.2-py2.3.egg\n d demoneeded-1.1-py2.3.egg\n - setuptools-0.7-py2.3.egg\n d zc.buildout-1.0-py2.3.egg\n\nWe see that we got an egg for demo that met the requirement, as well\nas the egg for demoneeded, which demo requires. (We also see an egg\nlink for the recipe in the develop-eggs directory. This egg link was\nactually created as part of the sample buildout setup. Normally, when\nusing the recipe, you'll get a regular egg installation.)\n\nScript generation\n-----------------\n\nThe demo egg defined a script, but we didn't get one installed:\n\n >>> ls(sample_buildout, 'bin')\n - buildout\n\nIf we want scripts provided by eggs to be installed, we should use the\nscripts recipe:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg:scripts\n ... eggs = demo<0.3\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='')\n Uninstalling demo.\n Installing demo.\n Generated script '/sample-buildout/bin/demo'.\n\nNow we also see the script defined by the demo script:\n\n >>> ls(sample_buildout, 'bin')\n - buildout\n - demo\n\nThe scripts recipe defines some additional options:\n\nentry-points\n A list of entry-point identifiers of the form:\n\n name=module:attrs\n\n where name is a script name, module is a dotted name resolving to a\n module name, and attrs is a dotted name resolving to a callable\n object within a module.\n\n This option is useful when working with distributions that don't\n declare entry points, such as distributions not written to work\n with setuptools.\n\n Examples can be seen in the section \"Specifying entry points\" below.\n\nscripts\n Control which scripts are generated. The value should be a list of\n zero or more tokens. Each token is either a name, or a name\n followed by an '=' and a new name. Only the named scripts are\n generated. If no tokens are given, then script generation is\n disabled. If the option isn't given at all, then all scripts\n defined by the named eggs will be generated.\n\ndependent-scripts\n If set to the string \"true\", scripts will be generated for all\n required eggs in addition to the eggs specifically named.\n\ninterpreter\n The name of a script to generate that allows access to a Python\n interpreter that has the path set based on the eggs installed.\n\nextra-paths\n Extra paths to include in a generated script.\n\ninitialization\n Specify some Python initialization code. This is very limited. In\n particular, be aware that leading whitespace is stripped from the\n code given.\n\narguments\n Specify some arguments to be passed to entry points as Python source.\n\nrelative-paths\n If set to true, then egg paths will be generated relative to the\n script path. This allows a buildout to be moved without breaking\n egg paths. This option can be set in either the script section or\n in the buildout section.\n\nLet's add an interpreter option:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... eggs = demo<0.3\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... interpreter = py-demo\n ... \"\"\" % dict(server=link_server))\n\nNote that we omitted the entry point name from the recipe\nspecification. We were able to do this because the scripts recipe is\nthe default entry point for the zc.recipe.egg egg.\n\n >>> print_(system(buildout), end='')\n Uninstalling demo.\n Installing demo.\n Generated script '/sample-buildout/bin/demo'.\n Generated interpreter '/sample-buildout/bin/py-demo'.\n\nNow we also get a py-demo script for giving us a Python prompt with\nthe path for demo and any eggs it depends on included in sys.path.\nThis is useful for debugging and testing.\n\n >>> ls(sample_buildout, 'bin')\n - buildout\n - demo\n - py-demo\n\nIf we run the demo script, it prints out some minimal data:\n\n >>> print_(system(join(sample_buildout, 'bin', 'demo')), end='')\n 2 1\n\nThe value it prints out happens to be some values defined in the\nmodules installed.\n\nWe can also run the py-demo script. Here we'll just print_(out)\nthe bits if the path added to reflect the eggs:\n\n >>> print_(system(join(sample_buildout, 'bin', 'py-demo'),\n ... \"\"\"import os, sys\n ... for p in sys.path:\n ... if 'demo' in p:\n ... _ = sys.stdout.write(os.path.basename(p)+'\\\\n')\n ...\n ... \"\"\").replace('>>> ', '').replace('... ', ''), end='')\n ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE\n demo-0.2-py2.4.egg\n demoneeded-1.1-py2.4.egg...\n\nEgg updating\n------------\n\nThe recipe normally gets the most recent distribution that satisfies the\nspecification. It won't do this is the buildout is either in\nnon-newest mode or in offline mode. To see how this works, we'll\nremove the restriction on demo:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... \"\"\" % dict(server=link_server))\n\nand run the buildout in non-newest mode:\n\n >>> print_(system(buildout+' -N'), end='')\n Uninstalling demo.\n Installing demo.\n Generated script '/sample-buildout/bin/demo'.\n\nNote that we removed the eggs option, and the eggs defaulted to the\npart name. Because we removed the eggs option, the demo was\nreinstalled.\n\nWe'll also run the buildout in off-line mode:\n\n >>> print_(system(buildout+' -o'), end='')\n Updating demo.\n\nWe didn't get an update for demo:\n\n >>> ls(sample_buildout, 'eggs')\n d demo-0.2-py2.3.egg\n d demoneeded-1.1-py2.3.egg\n - setuptools-0.7-py2.3.egg\n d zc.buildout-1.0-py2.3.egg\n\nIf we run the buildout on the default online and newest modes,\nwe'll get an update for demo:\n\n >>> print_(system(buildout), end='')\n Updating demo.\n Getting distribution for 'demo'.\n Got demo 0.3.\n Generated script '/sample-buildout/bin/demo'.\n\nThen we'll get a new demo egg:\n\n >>> ls(sample_buildout, 'eggs')\n d demo-0.2-py2.3.egg\n d demo-0.3-py2.3.egg\n d demoneeded-1.1-py2.3.egg\n - setuptools-0.7-py2.4.egg\n d zc.buildout-1.0-py2.4.egg\n\nThe script is updated too:\n\n >>> print_(system(join(sample_buildout, 'bin', 'demo')), end='')\n 3 1\n\nControlling script generation\n-----------------------------\n\nYou can control which scripts get generated using the scripts option.\nFor example, to suppress scripts, use the scripts option without any\narguments:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... scripts =\n ... \"\"\" % dict(server=link_server))\n\n\n >>> print_(system(buildout), end='')\n Uninstalling demo.\n Installing demo.\n\n >>> ls(sample_buildout, 'bin')\n - buildout\n\nYou can also control the name used for scripts:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... scripts = demo=foo\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='')\n Uninstalling demo.\n Installing demo.\n Generated script '/sample-buildout/bin/foo'.\n\n >>> ls(sample_buildout, 'bin')\n - buildout\n - foo\n\nSpecifying extra script paths\n-----------------------------\n\nIf we need to include extra paths in a script, we can use the\nextra-paths option:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... scripts = demo=foo\n ... extra-paths =\n ... /foo/bar\n ... ${buildout:directory}/spam\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='')\n Uninstalling demo.\n Installing demo.\n Generated script '/sample-buildout/bin/foo'.\n\nLet's look at the script that was generated:\n\n >>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE\n #!/usr/local/bin/python2.7\n <BLANKLINE>\n import sys\n sys.path[0:0] = [\n '/sample-buildout/eggs/demo-0.3-py2.4.egg',\n '/sample-buildout/eggs/demoneeded-1.1-py2.4.egg',\n '/foo/bar',\n '/sample-buildout/spam',\n ]\n <BLANKLINE>\n import eggrecipedemo\n <BLANKLINE>\n if __name__ == '__main__':\n sys.exit(eggrecipedemo.main())\n\nRelative egg paths\n------------------\n\nIf the relative-paths option is specified with a true value, then\npaths will be generated relative to the script. This is useful when\nyou want to be able to move a buildout directory around without\nbreaking scripts.\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... scripts = demo=foo\n ... relative-paths = true\n ... extra-paths =\n ... /foo/bar\n ... ${buildout:directory}/spam\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='')\n Uninstalling demo.\n Installing demo.\n Generated script '/sample-buildout/bin/foo'.\n\nLet's look at the script that was generated:\n\n >>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE\n #!/usr/local/bin/python2.7\n <BLANKLINE>\n import os\n <BLANKLINE>\n join = os.path.join\n base = os.path.dirname(os.path.abspath(os.path.realpath(__file__)))\n base = os.path.dirname(base)\n <BLANKLINE>\n import sys\n sys.path[0:0] = [\n join(base, 'eggs/demo-0.3-pyN.N.egg'),\n join(base, 'eggs/demoneeded-1.1-pyN.N.egg'),\n '/foo/bar',\n join(base, 'spam'),\n ]\n <BLANKLINE>\n import eggrecipedemo\n <BLANKLINE>\n if __name__ == '__main__':\n sys.exit(eggrecipedemo.main())\n\nYou can specify relative paths in the buildout section, rather than in\neach individual script section:\n\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ... relative-paths = true\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... scripts = demo=foo\n ... extra-paths =\n ... /foo/bar\n ... ${buildout:directory}/spam\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='')\n Uninstalling demo.\n Installing demo.\n Generated script '/sample-buildout/bin/foo'.\n\n >>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE\n #!/usr/local/bin/python2.7\n <BLANKLINE>\n import os\n <BLANKLINE>\n join = os.path.join\n base = os.path.dirname(os.path.abspath(os.path.realpath(__file__)))\n base = os.path.dirname(base)\n <BLANKLINE>\n import sys\n sys.path[0:0] = [\n join(base, 'eggs/demo-0.3-pyN.N.egg'),\n join(base, 'eggs/demoneeded-1.1-pyN.N.egg'),\n '/foo/bar',\n join(base, 'spam'),\n ]\n <BLANKLINE>\n import eggrecipedemo\n <BLANKLINE>\n if __name__ == '__main__':\n sys.exit(eggrecipedemo.main())\n\nSpecifying initialization code and arguments\n-----------------------------------------------\n\nSometimes, we need to do more than just calling entry points. We can\nuse the initialization and arguments options to specify extra code\nto be included in generated scripts:\n\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... scripts = demo=foo\n ... extra-paths =\n ... /foo/bar\n ... ${buildout:directory}/spam\n ... initialization = a = (1, 2\n ... 3, 4)\n ... interpreter = py\n ... arguments = a, 2\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='')\n Uninstalling demo.\n Installing demo.\n Generated script '/sample-buildout/bin/foo'.\n Generated interpreter '/sample-buildout/bin/py'.\n\n >>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE\n #!/usr/local/bin/python2.7\n <BLANKLINE>\n import sys\n sys.path[0:0] = [\n '/sample-buildout/eggs/demo-0.3-py2.4.egg',\n '/sample-buildout/eggs/demoneeded-1.1-py2.4.egg',\n '/foo/bar',\n '/sample-buildout/spam',\n ]\n <BLANKLINE>\n a = (1, 2\n 3, 4)\n <BLANKLINE>\n import eggrecipedemo\n <BLANKLINE>\n if __name__ == '__main__':\n sys.exit(eggrecipedemo.main(a, 2))\n\nHere we see that the initialization code we specified was added after\nsetting the path. Note, as mentioned above, that leading whitespace\nhas been stripped. Similarly, the argument code we specified was\nadded in the entry point call (to main).\n\nOur interpreter also has the initialization code:\n\n >>> cat(sample_buildout, 'bin', 'py')\n ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS\n #!/usr/local/bin/python2.7\n <BLANKLINE>\n import sys\n <BLANKLINE>\n sys.path[0:0] = [\n '/sample-buildout/eggs/demo-0.3-py3.3.egg',\n '/sample-buildout/eggs/demoneeded-1.1-py3.3.egg',\n '/foo/bar',\n '/sample-buildout/spam',\n ]\n <BLANKLINE>\n a = (1, 2\n 3, 4)\n <BLANKLINE>\n <BLANKLINE>\n _interactive = True\n ...\n\nSpecifying entry points\n-----------------------\n\nScripts can be generated for entry points declared explicitly. We can\ndeclare entry points using the entry-points option:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... extra-paths =\n ... /foo/bar\n ... ${buildout:directory}/spam\n ... entry-points = alt=eggrecipedemo:alt other=foo.bar:a.b.c\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='')\n Uninstalling demo.\n Installing demo.\n Generated script '/sample-buildout/bin/demo'.\n Generated script '/sample-buildout/bin/alt'.\n Generated script '/sample-buildout/bin/other'.\n\n >>> ls(sample_buildout, 'bin')\n - alt\n - buildout\n - demo\n - other\n\n >>> cat(sample_buildout, 'bin', 'other')\n #!/usr/local/bin/python2.7\n <BLANKLINE>\n import sys\n sys.path[0:0] = [\n '/sample-buildout/eggs/demo-0.3-py2.4.egg',\n '/sample-buildout/eggs/demoneeded-1.1-py2.4.egg',\n '/foo/bar',\n '/sample-buildout/spam',\n ]\n <BLANKLINE>\n import foo.bar\n <BLANKLINE>\n if __name__ == '__main__':\n sys.exit(foo.bar.a.b.c())\n\nGenerating all scripts\n----------------------\n\nThe `bigdemo` package doesn't have any scripts, but it requires the `demo`\npackage, which does have a script. Specify `dependent-scripts = true` to\ngenerate all scripts in required packages:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = bigdemo\n ...\n ... [bigdemo]\n ... recipe = zc.recipe.egg\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... dependent-scripts = true\n ... \"\"\" % dict(server=link_server))\n >>> print_(system(buildout+' -N'), end='')\n Uninstalling demo.\n Installing bigdemo.\n Getting distribution for 'bigdemo'.\n Got bigdemo 0.1.\n Generated script '/sample-buildout/bin/demo'.\n\nOffline mode\n------------\n\nIf the buildout offline option is set to \"true\", then no attempt will\nbe made to contact an index server:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = demo\n ... offline = true\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... index = eek!\n ... scripts = demo=foo\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='')\n Uninstalling bigdemo.\n Installing demo.\n Generated script '/sample-buildout/bin/foo'.\n\nCreating eggs with extensions needing custom build settings\n=============================================================\n\nSometimes, It's necessary to provide extra control over how an egg is\ncreated. This is commonly true for eggs with extension modules that\nneed to access libraries or include files.\n\nThe zc.recipe.egg:custom recipe can be used to define an egg with\ncustom build parameters. The currently defined parameters are:\n\ninclude-dirs\n A new-line separated list of directories to search for include\n files.\n\nlibrary-dirs\n A new-line separated list of directories to search for libraries\n to link with.\n\nrpath\n A new-line separated list of directories to search for dynamic libraries\n at run time.\n\ndefine\n A comma-separated list of names of C preprocessor variables to\n define.\n\nundef\n A comma-separated list of names of C preprocessor variables to\n undefine.\n\nlibraries\n The name of an additional library to link with. Due to limitations\n in distutils and despite the option name, only a single library\n can be specified.\n\nlink-objects\n The name of an link object to link against. Due to limitations\n in distutils and despite the option name, only a single link object\n can be specified.\n\ndebug\n Compile/link with debugging information\n\nforce\n Forcibly build everything (ignore file timestamps)\n\ncompiler\n Specify the compiler type\n\nswig\n The path to the swig executable\n\nswig-cpp\n Make SWIG create C++ files (default is C)\n\nswig-opts\n List of SWIG command line options\n\nIn addition, the following options can be used to specify the egg:\n\negg\n An specification for the egg to be created, to install given as a\n setuptools requirement string. This defaults to the part name.\n\nfind-links\n A list of URLs, files, or directories to search for distributions.\n\nindex\n The URL of an index server, or almost any other valid URL. :)\n\n If not specified, the Python Package Index,\n http://cheeseshop.python.org/pypi, is used. You can specify an\n alternate index with this option. If you use the links option and\n if the links point to the needed distributions, then the index can\n be anything and will be largely ignored. In the examples, here,\n we'll just point to an empty directory on our link server. This\n will make our examples run a little bit faster.\n\nenvironment\n The name of a section with additional environment variables. The\n environment variables are set before the egg is built.\n\nTo illustrate this, we'll define a buildout that builds an egg for a\npackage that has a simple extension module::\n\n #include <Python.h>\n #include <extdemo.h>\n\n static PyMethodDef methods[] = {};\n\n PyMODINIT_FUNC\n initextdemo(void)\n {\n PyObject *m;\n m = Py_InitModule3(\"extdemo\", methods, \"\");\n #ifdef TWO\n PyModule_AddObject(m, \"val\", PyInt_FromLong(2));\n #else\n PyModule_AddObject(m, \"val\", PyInt_FromLong(EXTDEMO));\n #endif\n }\n\nThe extension depends on a system-dependent include file, extdemo.h,\nthat defines a constant, EXTDEMO, that is exposed by the extension.\n\nThe extension module is available as a source distribution,\nextdemo-1.4.tar.gz, on a distribution server.\n\nWe have a sample buildout that we'll add an include directory to with\nthe necessary include file:\n\n >>> mkdir('include')\n >>> write('include', 'extdemo.h',\n ... \"\"\"\n ... #define EXTDEMO 42\n ... \"\"\")\n\nWe'll also update the buildout configuration file to define a part for\nthe egg:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... parts = extdemo\n ...\n ... [extdemo]\n ... recipe = zc.recipe.egg:custom\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... include-dirs = include\n ...\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='') # doctest: +ELLIPSIS\n Installing extdemo...\n\nWe got the zip_safe warning because the source distribution we used\nwasn't setuptools based and thus didn't set the option.\n\nThe egg is created in the develop-eggs directory *not* the eggs\ndirectory because it depends on buildout-specific parameters and the\neggs directory can be shared across multiple buildouts.\n\n >>> ls(sample_buildout, 'develop-eggs')\n d extdemo-1.4-py2.4-unix-i686.egg\n - zc.recipe.egg.egg-link\n\nNote that no scripts or dependencies are installed. To install\ndependencies or scripts for a custom egg, define another part and use\nthe zc.recipe.egg recipe, listing the custom egg as one of the eggs to\nbe installed. The zc.recipe.egg recipe will use the installed egg.\n\nLet's define a script that uses out ext demo:\n\n >>> mkdir('demo')\n >>> write('demo', 'demo.py',\n ... \"\"\"\n ... import extdemo, sys\n ... def print_(*args):\n ... sys.stdout.write(' '.join(map(str, args)) + '\\\\n')\n ... def main():\n ... print_(extdemo.val)\n ... \"\"\")\n\n >>> write('demo', 'setup.py',\n ... \"\"\"\n ... from setuptools import setup\n ... setup(name='demo')\n ... \"\"\")\n\n\n >>> write('buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... develop = demo\n ... parts = extdemo demo\n ...\n ... [extdemo]\n ... recipe = zc.recipe.egg:custom\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... include-dirs = include\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... eggs = demo\n ... extdemo\n ... entry-points = demo=demo:main\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout), end='')\n Develop: '/sample-buildout/demo'\n Updating extdemo.\n Installing demo.\n Generated script '/sample-buildout/bin/demo'...\n\nWhen we run the script, we'll 42 printed:\n\n >>> print_(system(join('bin', 'demo')), end='')\n 42\n\nUpdating\n--------\n\nThe custom recipe will normally check for new source distributions\nthat meet the given specification. This can be suppressed using the\nbuildout non-newest and offline modes. We'll generate a new source\ndistribution for extdemo:\n\n >>> update_extdemo()\n\nIf we run the buildout in non-newest or offline modes:\n\n >>> print_(system(buildout+' -N'), end='')\n Develop: '/sample-buildout/demo'\n Updating extdemo.\n Updating demo.\n\n >>> print_(system(buildout+' -o'), end='')\n Develop: '/sample-buildout/demo'\n Updating extdemo.\n Updating demo.\n\nWe won't get an update.\n\n >>> ls(sample_buildout, 'develop-eggs')\n - demo.egg-link\n d extdemo-1.4-py2.4-unix-i686.egg\n - zc.recipe.egg.egg-link\n\nBut if we run the buildout in the default on-line and newest modes, we\nwill. This time we also get the test-variable message again, because the new\nversion is imported:\n\n >>> print_(system(buildout), end='') # doctest: +ELLIPSIS\n Develop: '/sample-buildout/demo'\n Updating extdemo.\n zip_safe flag not set; analyzing archive contents...\n Updating demo.\n ...\n\n >>> ls(sample_buildout, 'develop-eggs')\n - demo.egg-link\n d extdemo-1.4-py2.4-linux-i686.egg\n d extdemo-1.5-py2.4-linux-i686.egg\n - zc.recipe.egg.egg-link\n\nControlling the version used\n----------------------------\n\nWe can specify a specific version using the egg option:\n\n >>> write('buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... develop = demo\n ... parts = extdemo demo\n ...\n ... [extdemo]\n ... recipe = zc.recipe.egg:custom\n ... egg = extdemo ==1.4\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... include-dirs = include\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... eggs = demo\n ... extdemo ==1.4\n ... entry-points = demo=demo:main\n ... \"\"\" % dict(server=link_server))\n\n >>> print_(system(buildout+' -D'), end='') # doctest: +ELLIPSIS\n Develop: '/sample-buildout/demo'\n ...\n\n >>> ls(sample_buildout, 'develop-eggs')\n - demo.egg-link\n d extdemo-1.4-py2.4-linux-i686.egg\n - zc.recipe.egg.egg-link\n\n\nControlling environment variables\n+++++++++++++++++++++++++++++++++\n\nTo set additional environment variables, the `environment` option is used.\n\nLet's create a recipe which prints out environment variables. We need this to\nmake sure the set environment variables are removed after the egg:custom\nrecipe was run.\n\n >>> mkdir(sample_buildout, 'recipes')\n >>> write(sample_buildout, 'recipes', 'environ.py',\n ... \"\"\"\n ... import logging, os, zc.buildout\n ...\n ... class Environ:\n ...\n ... def __init__(self, buildout, name, options):\n ... self.name = name\n ...\n ... def install(self):\n ... logging.getLogger(self.name).info(\n ... 'test-variable left over: %s' % (\n ... 'test-variable' in os.environ))\n ... return []\n ...\n ... def update(self):\n ... self.install()\n ... \"\"\")\n >>> write(sample_buildout, 'recipes', 'setup.py',\n ... \"\"\"\n ... from setuptools import setup\n ...\n ... setup(\n ... name = \"recipes\",\n ... entry_points = {'zc.buildout': ['environ = environ:Environ']},\n ... )\n ... \"\"\")\n\n\nCreate our buildout:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... develop = recipes\n ... parts = extdemo checkenv\n ...\n ... [extdemo-env]\n ... test-variable = foo\n ...\n ... [extdemo]\n ... recipe = zc.recipe.egg:custom\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... include-dirs = include\n ... environment = extdemo-env\n ...\n ... [checkenv]\n ... recipe = recipes:environ\n ...\n ... \"\"\" % dict(server=link_server))\n >>> print_(system(buildout), end='') # doctest: +ELLIPSIS\n Develop: '/sample-buildout/recipes'\n Uninstalling demo.\n Uninstalling extdemo.\n Installing extdemo.\n Have environment test-variable: foo\n zip_safe flag not set; analyzing archive contents...\n Installing checkenv.\n ...\n\n\nThe setup.py also printed out that we have set the environment `test-variable`\nto foo. After the buildout the variable is reset to its original value (i.e.\nremoved).\n\nWhen an environment variable has a value before zc.recipe.egg:custom is run,\nthe original value will be restored:\n\n >>> import os\n >>> os.environ['test-variable'] = 'bar'\n >>> print_(system(buildout), end='')\n Develop: '/sample-buildout/recipes'\n Updating extdemo.\n Updating checkenv.\n checkenv: test-variable left over: True\n\n >>> os.environ['test-variable']\n 'bar'\n\n\nSometimes it is required to prepend or append to an existing environment\nvariable, for instance for adding something to the PATH. Therefore all variables\nare interpolated with os.environ before the're set:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... develop = recipes\n ... parts = extdemo checkenv\n ...\n ... [extdemo-env]\n ... test-variable = foo:%%(test-variable)s\n ...\n ... [extdemo]\n ... recipe = zc.recipe.egg:custom\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... include-dirs = include\n ... environment = extdemo-env\n ...\n ... [checkenv]\n ... recipe = recipes:environ\n ...\n ... \"\"\" % dict(server=link_server))\n >>> print_(system(buildout), end='') # doctest: +ELLIPSIS\n Develop: '/sample-buildout/recipes'\n Uninstalling extdemo.\n Installing extdemo.\n Have environment test-variable: foo:bar\n zip_safe flag not set; analyzing archive contents...\n Updating checkenv.\n ...\n\n >>> os.environ['test-variable']\n 'bar'\n >>> del os.environ['test-variable']\n\n\nCreate a clean buildout.cfg w/o the checkenv recipe, and delete the recipe:\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... develop = recipes\n ... parts = extdemo\n ...\n ... [extdemo]\n ... recipe = zc.recipe.egg:custom\n ... find-links = %(server)s\n ... index = %(server)s/index\n ... include-dirs = include\n ...\n ... \"\"\" % dict(server=link_server))\n >>> print_(system(buildout), end='') # doctest: +ELLIPSIS\n Develop: '/sample-buildout/recipes'\n Uninstalling checkenv.\n Uninstalling extdemo.\n Installing extdemo...\n\n >>> rmdir(sample_buildout, 'recipes')\n\n\nControlling develop-egg generation\n==================================\n\nIf you want to provide custom build options for a develop egg, you can\nuse the develop recipe. The recipe has the following options:\n\nsetup\n The path to a setup script or directory containing a startup\n script. This is required.\n\ninclude-dirs\n A new-line separated list of directories to search for include\n files.\n\nlibrary-dirs\n A new-line separated list of directories to search for libraries\n to link with.\n\nrpath\n A new-line separated list of directories to search for dynamic libraries\n at run time.\n\ndefine\n A comma-separated list of names of C preprocessor variables to\n define.\n\nundef\n A comma-separated list of names of C preprocessor variables to\n undefine.\n\nlibraries\n The name of an additional library to link with. Due to limitations\n in distutils and despite the option name, only a single library\n can be specified.\n\nlink-objects\n The name of an link object to link against. Due to limitations\n in distutils and despite the option name, only a single link object\n can be specified.\n\ndebug\n Compile/link with debugging information\n\nforce\n Forcibly build everything (ignore file timestamps)\n\ncompiler\n Specify the compiler type\n\nswig\n The path to the swig executable\n\nswig-cpp\n Make SWIG create C++ files (default is C)\n\nswig-opts\n List of SWIG command line options\n\nTo illustrate this, we'll use a directory containing the extdemo\nexample from the earlier section:\n\n >>> ls(extdemo)\n - MANIFEST\n - MANIFEST.in\n - README\n - extdemo.c\n - setup.py\n\n >>> write('buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... develop = demo\n ... parts = extdemo demo\n ...\n ... [extdemo]\n ... setup = %(extdemo)s\n ... recipe = zc.recipe.egg:develop\n ... include-dirs = include\n ... define = TWO\n ...\n ... [demo]\n ... recipe = zc.recipe.egg\n ... eggs = demo\n ... extdemo\n ... entry-points = demo=demo:main\n ... \"\"\" % dict(extdemo=extdemo))\n\nNote that we added a define option to cause the preprocessor variable\nTWO to be defined. This will cause the module-variable, 'val', to be\nset with a value of 2.\n\n >>> print_(system(buildout), end='') # doctest: +ELLIPSIS\n Develop: '/sample-buildout/demo'\n Uninstalling extdemo.\n Installing extdemo.\n Installing demo.\n ...\n\nOur develop-eggs now includes an egg link for extdemo:\n\n >>> ls('develop-eggs')\n - demo.egg-link\n - extdemo.egg-link\n - zc.recipe.egg.egg-link\n\nand the extdemo now has a built extension:\n\n >>> contents = os.listdir(extdemo)\n >>> bool([f for f in contents if f.endswith('.so') or f.endswith('.pyd')])\n True\n\nBecause develop eggs take precedence over non-develop eggs, the demo\nscript will use the new develop egg:\n\n >>> print_(system(join('bin', 'demo')), end='')\n 2\n\nEgg Recipe API for other Recipes\n================================\n\nIt is common for recipes to accept a collection of egg specifications\nand generate scripts based on the resulting working sets. The egg\nrecipe provides an API that other recipes can use.\n\nA recipe can reuse the egg recipe, supporting the eggs, find-links,\nindex, and extra-paths options. This is done by creating an\negg recipe instance in a recipes's constructor. In the recipe's\ninstall script, the egg-recipe instance's working_set method is used\nto collect the requested eggs and working set.\n\nTo illustrate, we create a sample recipe that is a very thin layer\naround the egg recipe:\n\n >>> mkdir(sample_buildout, 'sample')\n >>> write(sample_buildout, 'sample', 'sample.py', \n ... \"\"\"\n ... import logging, os, sys\n ... import zc.recipe.egg\n ...\n ... def print_(*args):\n ... sys.stdout.write(' '.join(map(str, args)) + '\\\\n')\n ...\n ... class Sample:\n ...\n ... def __init__(self, buildout, name, options):\n ... self.egg = zc.recipe.egg.Scripts(buildout, name, options)\n ... self.name = name\n ... self.options = options\n ...\n ... def install(self):\n ... extras = self.options['extras'].split()\n ... requirements, ws = self.egg.working_set(extras)\n ... print_('Part:', self.name)\n ... print_('Egg requirements:')\n ... for r in requirements:\n ... print_(r)\n ... print_('Working set:')\n ... for d in ws:\n ... print_(d)\n ... print_('extra paths:', self.egg.extra_paths)\n ... return ()\n ...\n ... update = install\n ... \"\"\")\n\nHere we instantiated the egg recipe in the constructor, saving it in\nan attribute. This also initialized the options dictionary.\n\nIn our install method, we called the working_set method on the\ninstance we saved. The working_set method takes an optional sequence\nof extra requirements to be included in the working set.\n\n >>> write(sample_buildout, 'sample', 'setup.py',\n ... \"\"\"\n ... from setuptools import setup\n ... \n ... setup(\n ... name = \"sample\",\n ... entry_points = {'zc.buildout': ['default = sample:Sample']},\n ... install_requires = 'zc.recipe.egg',\n ... )\n ... \"\"\")\n\n\n >>> write(sample_buildout, 'sample', 'README.txt', \" \")\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... develop = sample\n ... parts = sample-part\n ...\n ... [sample-part]\n ... recipe = sample\n ... eggs = demo<0.3\n ... find-links = %(server)s\n ... index = %(server)sindex\n ... extras = other\n ... \"\"\" % dict(server=link_server))\n\n >>> import os\n >>> os.chdir(sample_buildout)\n >>> buildout = os.path.join(sample_buildout, 'bin', 'buildout')\n >>> print_(system(buildout + ' -q'), end='')\n Part: sample-part\n Egg requirements:\n demo<0.3\n Working set:\n demoneeded 1.1\n other 1.0\n demo 0.2\n extra paths: []\n\nWe can see that the options were augmented with additional data\ncomputed by the egg recipe by looking at .installed.cfg:\n\n >>> cat(sample_buildout, '.installed.cfg')\n [buildout]\n installed_develop_eggs = /sample-buildout/develop-eggs/sample.egg-link\n parts = sample-part\n <BLANKLINE>\n [sample-part]\n __buildout_installed__ = \n __buildout_signature__ = ...\n _b = /sample-buildout/bin\n _d = /sample-buildout/develop-eggs\n _e = /sample-buildout/eggs\n bin-directory = /sample-buildout/bin\n develop-eggs-directory = /sample-buildout/develop-eggs\n eggs = demo<0.3\n eggs-directory = /sample-buildout/eggs\n extras = other\n find-links = http://localhost:27071/\n index = http://localhost:27071/index\n recipe = sample\n\nIf we use the extra-paths option:\n\n\n >>> write(sample_buildout, 'buildout.cfg',\n ... \"\"\"\n ... [buildout]\n ... develop = sample\n ... parts = sample-part\n ...\n ... [sample-part]\n ... recipe = sample\n ... eggs = demo<0.3\n ... find-links = %(server)s\n ... index = %(server)sindex\n ... extras = other\n ... extra-paths = /foo/bar\n ... /spam/eggs\n ... \"\"\" % dict(server=link_server))\n\nThen we'll see that reflected in the extra_paths attribute in the egg\nrecipe instance:\n\n >>> print_(system(buildout + ' -q'), end='')\n Part: sample-part\n Egg requirements:\n demo<0.3\n Working set:\n demo 0.2\n other 1.0\n demoneeded 1.1\n extra paths: ['/foo/bar', '/spam/eggs']\n\n\nWorking set caching\n===================\n\nWorking sets are cached, to improve speed on buildouts with multiple similar\nparts based on ``zc.recipe.egg``.\n\nThe egg-recipe instance's ``_working_set`` helper method is used to make\nthe caching easier. It does the same job as ``working_set()`` but with some\ndifferences:\n\n- The signature is different: all information needed to build the working set\n is passed as parameters.\n- The return value is simpler: only an instance of ``pkg_resources.WorkingSet``\n is returned.\n\nHere's an example:\n\n >>> from zc.buildout import testing\n >>> from zc.recipe.egg.egg import Eggs\n >>> import os\n >>> import pkg_resources\n >>> recipe = Eggs(buildout=testing.Buildout(), name='fake-part', options={})\n >>> eggs_dir = os.path.join(sample_buildout, 'eggs')\n >>> develop_eggs_dir = os.path.join(sample_buildout, 'develop-eggs')\n >>> testing.install_develop('zc.recipe.egg', develop_eggs_dir)\n >>> ws = recipe._working_set(\n ... distributions=['zc.recipe.egg', 'demo<0.3'],\n ... eggs_dir=eggs_dir,\n ... develop_eggs_dir=develop_eggs_dir,\n ... index=link_server,\n ... )\n Getting...\n >>> isinstance(ws, pkg_resources.WorkingSet)\n True\n >>> sorted(dist.project_name for dist in ws)\n ['demo', 'demoneeded', 'setuptools', 'zc.buildout', 'zc.recipe.egg']\n\nWe'll monkey patch a method in the ``easy_install`` module in order to verify if\nthe cache is working:\n\n >>> import zc.buildout.easy_install\n >>> old_install = zc.buildout.easy_install.Installer.install\n >>> def new_install(*args, **kwargs):\n ... print('Building working set.')\n ... return old_install(*args, **kwargs)\n >>> zc.buildout.easy_install.Installer.install = new_install\n\nNow we check if the caching is working by verifying if the same working set is\nbuilt only once.\n\n >>> ws_args_1 = dict(\n ... distributions=['demo>=0.1'],\n ... eggs_dir=eggs_dir,\n ... develop_eggs_dir=develop_eggs_dir,\n ... offline=True,\n ... )\n >>> ws_args_2 = dict(ws_args_1)\n >>> ws_args_2['distributions'] = ['demoneeded']\n >>> recipe._working_set(**ws_args_1)\n Building working set.\n <pkg_resources.WorkingSet object at ...>\n >>> recipe._working_set(**ws_args_1)\n <pkg_resources.WorkingSet object at ...>\n >>> recipe._working_set(**ws_args_2)\n Building working set.\n <pkg_resources.WorkingSet object at ...>\n >>> recipe._working_set(**ws_args_1)\n <pkg_resources.WorkingSet object at ...>\n >>> recipe._working_set(**ws_args_2)\n <pkg_resources.WorkingSet object at ...>\n\nUndo monkey patch:\n\n >>> zc.buildout.easy_install.Installer.install = old_install\n\nSince ``pkg_resources.WorkingSet`` instances are mutable, we must ensure that\n``working_set()`` always returns a pristine copy. Otherwise callers would be\nable to modify instances inside the cache.\n\nLet's create a working set:\n\n >>> ws = recipe._working_set(**ws_args_1)\n >>> sorted(dist.project_name for dist in ws)\n ['demo', 'demoneeded']\n\nNow we add a distribution to it:\n\n >>> dist = pkg_resources.get_distribution('zc.recipe.egg')\n >>> ws.add(dist)\n >>> sorted(dist.project_name for dist in ws)\n ['demo', 'demoneeded', 'zc.recipe.egg']\n\nLet's call the working_set function again and see if the result remains valid:\n\n >>> ws = recipe._working_set(**ws_args_1)\n >>> sorted(dist.project_name for dist in ws)\n ['demo', 'demoneeded']\n\nDownload\n*********",
"bugtrack_url": null,
"license": "ZPL 2.1",
"summary": "Recipe for installing Python package distributions as eggs",
"version": "2.0.7",
"project_urls": {
"Homepage": "http://cheeseshop.python.org/pypi/zc.recipe.egg"
},
"split_keywords": [
"development",
"build"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7a6fc6871e8490a153c3b44ac43e4a6552d802561a12b4780c7ea088a7ec5ff0",
"md5": "b0d432087849dbe24a94edebbba29fe6",
"sha256": "b89eb00979614e3584bb4e8431172b2345d00b983a04ebf00a401fb695f4e6d3"
},
"downloads": -1,
"filename": "zc.recipe.egg-2.0.7.tar.gz",
"has_sig": false,
"md5_digest": "b0d432087849dbe24a94edebbba29fe6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 39384,
"upload_time": "2018-07-02T11:39:25",
"upload_time_iso_8601": "2018-07-02T11:39:25.724663Z",
"url": "https://files.pythonhosted.org/packages/7a/6f/c6871e8490a153c3b44ac43e4a6552d802561a12b4780c7ea088a7ec5ff0/zc.recipe.egg-2.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2018-07-02 11:39:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "zc.recipe.egg"
}
JSON