README.txt 6.69 KB
Newer Older
1 2 3
Installation of distributions as eggs
=====================================

4
The zc.recipe.egg recipe can be used to install various types if
5 6
distutils distributions as eggs.  It takes a number of options:

7 8 9 10
eggs
    A list of eggs to install given as one ore more setuptools
    requirement strings.  Each string must be given on a separate
    line.
11

12
find-links
13 14
   A list of URLs, files, or directories to search for distributions.

15 16 17 18 19 20 21 22 23 24 25
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.

26 27 28 29 30 31 32 33 34 35 36 37
python
   The name of a section to get the Python executable from.
   If not specified, then the buildout python option is used.  The
   Python executable is found in the executable option of the named
   section. 

unzip
   The value of this option must be either true or false. If the value
   is true, then the installed egg will be unzipped. Note that this is
   only effective when an egg is installed.  If a zipped egg already 
   exists in the eggs directory, it will not be unzipped.

38 39 40 41 42 43 44 45
scripts
   Control which scripts are generated.  The value should be a list of
   zero or more tokens.  Each tokem 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.

46

47 48 49 50 51 52 53 54 55 56 57 58 59
We have a link server that has a number of eggs:

    >>> print get(link_server),
    <html><body>
    <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="demoneeded-1.0-py2.3.egg">demoneeded-1.0-py2.3.egg</a><br>
    <a href="demoneeded-1.1-py2.3.egg">demoneeded-1.1-py2.3.egg</a><br>
    <a href="index/">index/</a><br>
    <a href="other-1.0-py2.3.egg">other-1.0-py2.3.egg</a><br>
    </body></html>

60 61 62 63 64 65 66 67 68 69 70

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
71
    ... eggs = demo<0.3
72 73 74
    ... find-links = %(server)s
    ... index = %(server)s/index
    ... """ % dict(server=link_server))
75 76

In this example, we limited ourself to revisions before 0.3. We also
77
specified where to find distributions using the find-links option.
78 79 80 81 82

Let's run the buildout:

    >>> import os
    >>> os.chdir(sample_buildout)
83 84
    >>> buildout = os.path.join(sample_buildout, 'bin', 'buildout')
    >>> print system(buildout),
85 86 87 88 89
    
Now, if we look at the buildout eggs directory:

    >>> ls(sample_buildout, 'eggs')
    -  demo-0.2-py2.3.egg
90
    -  demoneeded-1.1-py2.3.egg
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122

We see that we got an egg for demo that met the requirement, as well
as the egg for demoneeded, wich demo requires.  (We also see an egg
link for the recipe.  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.)

The demo egg also defined a script and we see that the script was
installed as well:

    >>> ls(sample_buildout, 'bin')
    -  buildout
    -  demo
    -  py_demo

Here, in addition to the buildout script, we see the demo script,
demo, and we see a script, py_demo, 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 testing.

If we run the demo script, it prints out some minimal data:

    >>> print system(os.path.join(sample_buildout, 'bin', 'demo')),
    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(os.path.join(sample_buildout, 'bin', 'py_demo'),
123
    ... """for p in sys.path[:2]:
124 125 126 127 128 129 130 131
    ...        print p
    ... """).replace('>>> ', '').replace('... ', ''),
    ... # doctest: +ELLIPSIS
    <BLANKLINE>
    /tmp/tmpcy8MvGbuildout-tests/eggs/demo-0.2-py2.3.egg
    /tmp/tmpcy8MvGbuildout-tests/eggs/demoneeded-1.0-py2.3.egg
    <BLANKLINE>

Jim Fulton's avatar
Jim Fulton committed
132
The recipe gets the most recent distribution that satisfies the
133
specification. For example, We remove the restriction on demo:
Jim Fulton's avatar
Jim Fulton committed
134 135 136 137 138 139 140 141

    >>> write(sample_buildout, 'buildout.cfg',
    ... """
    ... [buildout]
    ... parts = demo
    ...
    ... [demo]
    ... recipe = zc.recipe.egg
142 143
    ... find-links = %(server)s
    ... index = %(server)s/index
144
    ... unzip = true
145
    ... """ % dict(server=link_server))
Jim Fulton's avatar
Jim Fulton committed
146

147 148
We also used the unzip uption to request a directory, rather than
a zip file.
Jim Fulton's avatar
Jim Fulton committed
149

150
    >>> print system(buildout),
Jim Fulton's avatar
Jim Fulton committed
151 152 153 154 155

Then we'll get a new demo egg:

    >>> ls(sample_buildout, 'eggs')
    -  demo-0.2-py2.3.egg
156
    d  demo-0.3-py2.3.egg
157
    d  demoneeded-1.0-py2.3.egg
Jim Fulton's avatar
Jim Fulton committed
158

159
Note that we removed the eggs option, and the eggs
160 161
defaulted to the part name.

Jim Fulton's avatar
Jim Fulton committed
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
The script is updated too:

    >>> print system(os.path.join(sample_buildout, 'bin', 'demo')),
    3 1

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
179 180
    ... find-links = %(server)s
    ... index = %(server)s/index
Jim Fulton's avatar
Jim Fulton committed
181
    ... scripts =
182
    ... """ % dict(server=link_server))
Jim Fulton's avatar
Jim Fulton committed
183 184


185
    >>> print system(buildout),
Jim Fulton's avatar
Jim Fulton committed
186 187 188 189 190 191 192 193 194 195 196 197 198

    >>> 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
199 200
    ... find-links = %(server)s
    ... index = %(server)s/index
Jim Fulton's avatar
Jim Fulton committed
201
    ... scripts = demo=foo
202
    ... """ % dict(server=link_server))
Jim Fulton's avatar
Jim Fulton committed
203

204
    >>> print system(buildout),
Jim Fulton's avatar
Jim Fulton committed
205 206 207 208

    >>> ls(sample_buildout, 'bin')
    -  buildout
    -  foo
209

210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
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),