source: TI12-security/trunk/NDGSecurity/python/buildout/ndgsecurity/eggs/zc.buildout-1.2.1-py2.5.egg/EGG-INFO/PKG-INFO @ 7081

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg-security/TI12-security/trunk/NDGSecurity/python/buildout/ndgsecurity/eggs/zc.buildout-1.2.1-py2.5.egg/EGG-INFO/PKG-INFO@7081
Revision 7081, 205.3 KB checked in by pjkersha, 11 years ago (diff)
  • Property svn:keywords set to Id
Line 
1Metadata-Version: 1.0
2Name: zc.buildout
3Version: 1.2.1
4Summary: System for managing development buildouts
5Home-page: http://www.python.org/pypi/zc.buildout
6Author: Jim Fulton
7Author-email: jim@zope.com
8License: ZPL 2.1
9Description: ********
10        Buildout
11        ********
12       
13        .. contents::
14       
15        The Buildout project provides support for creating applications,
16        especially Python applications.  It provides tools for assembling
17        applications from multiple parts, Python or otherwise.  An application
18        may actually contain multiple programs, processes, and configuration
19        settings.
20       
21        The word "buildout" refers to a description of a set of parts and the
22        software to create and assemble them.  It is often used informally to
23        refer to an installed system based on a buildout definition.  For
24        example, if we are creating an application named "Foo", then "the Foo
25        buildout" is the collection of configuration and application-specific
26        software that allows an instance of the application to be created.  We
27        may refer to such an instance of the application informally as "a Foo
28        buildout".
29       
30        To get a feel for some of the things you might use buildouts for, see
31        the `Buildout examples`_.
32       
33        To lean more about using buildouts, see `Detailed Documentation`_.
34       
35        Recipes
36        *******
37       
38        Existing recipes include:
39       
40        `zc.recipe.egg <http://pypi.python.org/pypi/zc.recipe.egg>`_
41        The egg recipe installes one or more eggs, with their
42        dependencies.  It installs their console-script entry points with
43        the needed eggs included in their paths.
44       
45        `zc.recipe.testrunner <http://pypi.python.org/pypi/zc.recipe.testrunner>`_
46        The testrunner egg creates a test runner script for one or
47        more eggs.
48       
49        `zc.recipe.zope3checkout <http://pypi.python.org/pypi/zc.recipe.zope3checkout>`_
50        The zope3checkout recipe installs a Zope 3 checkout into a
51        buildout.
52       
53        `zc.recipe.zope3instance <http://pypi.python.org/pypi/zc.recipe.zope3instance>`_
54        The zope3instance recipe sets up a Zope 3 instance.
55       
56        `zc.recipe.filestorage <http://pypi.python.org/pypi/zc.recipe.filestorage>`_
57        The filestorage recipe sets up a ZODB file storage for use in a
58        Zope 3 instance created by the zope3instance recipe.
59       
60        Buildout examples
61        *****************
62       
63        Here are a few examples of what you can do with buildouts.  We'll
64        present these as a set of use cases.
65       
66        Try out an egg
67        ==============
68       
69        Sometimes you want to try an egg (or eggs) that someone has released.
70        You'd like to get a Python interpreter that lets you try things
71        interactively or run sample scripts without having to do path
72        manipulations.  If you can and don't mind modifying your Python
73        installation, you could use easy_install, otherwise, you could create
74        a directory somewhere and create a buildout.cfg file in that directory
75        containing::
76       
77        [buildout]
78        parts = mypython
79       
80        [mypython]
81        recipe = zc.recipe.egg
82        interpreter = mypython
83        eggs = theegg
84       
85        where theegg is the name of the egg you want to try out.
86       
87        Run buildout in this directory.  It will create a bin subdirectory
88        that includes a mypython script.  If you run mypython without any
89        arguments you'll get an interactive interpreter with the egg in the
90        path. If you run it with a script and script arguments, the script
91        will run with the egg in its path.  Of course, you can specify as many
92        eggs as you want in the eggs option.
93       
94        If the egg provides any scripts (console_scripts entry points), those
95        will be installed in your bin directory too.
96       
97        Work on a package
98        =================
99       
100        I often work on packages that are managed separately.  They don't have
101        scripts to be installed, but I want to be able to run their tests
102        using the `zope.testing test runner
103        <http://www.python.org/pypi/zope.testing>`_.  In this kind of
104        application, the program to be installed is the test runner.  A good
105        example of this is `zc.ngi <http://svn.zope.org/zc.ngi/trunk/>`_.
106       
107        Here I have a subversion project for the zc.ngi package.  The software
108        is in the src directory.  The configuration file is very simple::
109       
110        [buildout]
111        develop = .
112        parts = test
113       
114        [test]
115        recipe = zc.recipe.testrunner
116        eggs = zc.ngi
117       
118        I use the develop option to create a develop egg based on the current
119        directory.  I request a test script named "test" using the
120        zc.recipe.testrunner recipe.  In the section for the test script, I
121        specify that I want to run the tests in the zc.ngi package.
122       
123        When I check out this project into a new sandbox, I run bootstrap.py
124        to get setuptools and zc.buildout and to create bin/buildout.  I run
125        bin/buildout, which installs the test script, bin/test, which I can
126        then use to run the tests.
127       
128        This is probably the most common type of buildout.
129       
130        The `zc.buildout project <http://svn.zope.org/zc.buildout/trunk>`_
131        is a slightly more complex example of this type of buildout.
132       
133        Install egg-based scripts
134        =========================
135       
136        A variation of the `Try out an egg`_ use case is to install scripts
137        into your ~/bin directory (on Unix, of course).  My ~/bin directory is
138        a buildout with a configuration file that looks like::
139       
140       
141        [buildout]
142        parts = foo bar
143        bin-directory = .
144       
145        [foo]
146        ...
147       
148        where foo and bar are packages with scripts that I want available.  As
149        I need new scripts, I can add additional sections.  The bin-directory
150        option specified that scripts should be installed into the current
151        directory.
152       
153        Multi-program multi-machine systems
154        ===================================
155       
156        Using an older prototype version of the buildout, we've build a number
157        of systems involving multiple programs, databases, and machines.  One
158        typical example consists of:
159       
160        - Multiple Zope instances
161       
162        - Multiple ZEO servers
163       
164        - An LDAP server
165       
166        - Cache-invalidation and Mail delivery servers
167       
168        - Dozens of add-on packages
169       
170        - Multiple test runners
171       
172        - Multiple deployment modes, including dev, stage, and prod,
173        with prod deployment over multiple servers
174       
175        Parts installed include:
176       
177        - Application software installs, including Zope, ZEO and LDAP
178        software
179       
180        - Add-on packages
181       
182        - Bundles of configuration that define Zope, ZEO and LDAP instances
183       
184        - Utility scripts such as test runners, server-control
185        scripts, cron jobs.
186       
187        Questions and Bug Reporting
188        ***************************
189       
190        Please send questions and comments to the
191        `distutils SIG mailing list <mailto://distutils-sig@python.org>`_.
192       
193        Report bugs using the `zc.buildout Launchpad Bug Tracker
194        <https://launchpad.net/products/zc.buildout/+bugs>`_.
195       
196       
197        Detailed Documentation
198        **********************
199       
200        Buildouts
201        =========
202       
203        The word "buildout" refers to a description of a set of parts and the
204        software to create and assemble them.  It is often used informally to
205        refer to an installed system based on a buildout definition.  For
206        example, if we are creating an application named "Foo", then "the Foo
207        buildout" is the collection of configuration and application-specific
208        software that allows an instance of the application to be created.  We
209        may refer to such an instance of the application informally as "a Foo
210        buildout".
211       
212        This document describes how to define buildouts using buildout
213        configuration files and recipes.  There are three ways to set up the
214        buildout software and create a buildout instance:
215       
216        1. Install the zc.buildout egg with easy_install and use the buildout
217        script installed in a Python scripts area.
218       
219        2. Use the buildout bootstrap script to create a buildout that
220        includes both the setuptools and zc.buildout eggs.  This allows you
221        to use the buildout software without modifying a Python install.
222        The buildout script is installed into your buildout local scripts
223        area.
224       
225        3. Use a buildout command from an already installed buildout to
226        bootstrap a new buildout.  (See the section on bootstraping later
227        in this document.)
228       
229        Often, a software project will be managed in a software repository,
230        such as a subversion repository, that includes some software source
231        directories, buildout configuration files, and a copy of the buildout
232        bootstrap script.  To work on the project, one would check out the
233        project from the repository and run the bootstrap script which
234        installs setuptools and zc.buildout into the checkout as well as any
235        parts defined.
236       
237        We have a sample buildout that we created using the bootstrap command
238        of an existing buildout (method 3 above).  It has the absolute minimum
239        information.  We have bin, develop-eggs, eggs and parts directories,
240        and a configuration file:
241       
242        >>> ls(sample_buildout)
243        d  bin
244        -  buildout.cfg
245        d  develop-eggs
246        d  eggs
247        d  parts
248       
249        The bin directory contains scripts.
250       
251        >>> ls(sample_buildout, 'bin')
252        -  buildout
253       
254        >>> ls(sample_buildout, 'eggs')
255        -  setuptools-0.6-py2.4.egg
256        -  zc.buildout-1.0-py2.4.egg
257       
258        The develop-eggs and parts directories are initially empty:
259       
260        >>> ls(sample_buildout, 'develop-eggs')
261        >>> ls(sample_buildout, 'parts')
262       
263        The develop-eggs directory holds egg links for software being
264        developed in the buildout.  We separate develop-eggs and other eggs to
265        allow eggs directories to be shared across multiple buildouts.  For
266        example, a common developer technique is to define a common eggs
267        directory in their home that all non-develop eggs are stored in.  This
268        allows larger buildouts to be set up much more quickly and saves disk
269        space.
270       
271        The parts directory provides an area where recipes can install
272        part data.  For example, if we built a custom Python, we would
273        install it in the part directory.  Part data is stored in a
274        sub-directory of the parts directory with the same name as the part.
275       
276        Buildouts are defined using configuration files.  These are in the
277        format defined by the Python ConfigParser module, with extensions
278        that we'll describe later.  By default, when a buildout is run, it
279        looks for the file buildout.cfg in the directory where the buildout is
280        run.
281       
282        The minimal configuration file has a buildout section that defines no
283        parts:
284       
285        >>> cat(sample_buildout, 'buildout.cfg')
286        [buildout]
287        parts =
288       
289        A part is simply something to be created by a buildout.  It can be
290        almost anything, such as a Python package, a program, a directory, or
291        even a configuration file.
292       
293        Recipes
294        -------
295       
296        A part is created by a recipe.  Recipes are always installed as Python
297        eggs. They can be downloaded from a package server, such as the
298        Python Package Index, or they can be developed as part of a project
299        using a "develop" egg.
300       
301        A develop egg is a special kind of egg that gets installed as an "egg
302        link" that contains the name of a source directory.  Develop eggs
303        don't have to be packaged for distribution to be used and can be
304        modified in place, which is especially useful while they are being
305        developed.
306       
307        Let's create a recipe as part of the sample project.  We'll create a
308        recipe for creating directories.  First, we'll create a recipes source
309        directory for our local recipes:
310       
311        >>> mkdir(sample_buildout, 'recipes')
312       
313        and then we'll create a source file for our mkdir recipe:
314       
315        >>> write(sample_buildout, 'recipes', 'mkdir.py',
316        ... """
317        ... import logging, os, zc.buildout
318        ...
319        ... class Mkdir:
320        ...
321        ...     def __init__(self, buildout, name, options):
322        ...         self.name, self.options = name, options
323        ...         options['path'] = os.path.join(
324        ...                               buildout['buildout']['directory'],
325        ...                               options['path'],
326        ...                               )
327        ...         if not os.path.isdir(os.path.dirname(options['path'])):
328        ...             logging.getLogger(self.name).error(
329        ...                 'Cannot create %s. %s is not a directory.',
330        ...                 options['path'], os.path.dirname(options['path']))
331        ...             raise zc.buildout.UserError('Invalid Path')
332        ...
333        ...
334        ...     def install(self):
335        ...         path = self.options['path']
336        ...         logging.getLogger(self.name).info(
337        ...             'Creating directory %s', os.path.basename(path))
338        ...         os.mkdir(path)
339        ...         return path
340        ...
341        ...     def update(self):
342        ...         pass
343        ... """)
344       
345        Currently, recipes must define 3 methods [#future_recipe_methods]_:
346       
347        - a constructor,
348       
349        - an install method, and
350       
351        - an update method.
352       
353        The constructor is responsible for updating a parts options to reflect
354        data read from other sections.  The buildout system keeps track of
355        whether a part specification has changed.  A part specification has
356        changed if it's options, after adjusting for data read from other
357        sections, has changed, or if the recipe has changed.  Only the options
358        for the part are considered.  If data are read from other sections,
359        then that information has to be reflected in the parts options.  In
360        the Mkdir example, the given path is interpreted relative to the
361        buildout directory, and data from the buildout directory is read.  The
362        path option is updated to reflect this.  If the directory option was
363        changed in the buildout sections, we would know to update parts
364        created using the mkdir recipe using relative path names.
365       
366        When buildout is run, it saves configuration data for installed parts
367        in a file named ".installed.cfg".  In subsequent runs, it compares
368        part-configuration data stored in the .installed.cfg file and the
369        part-configuration data loaded from the configuration files as
370        modified by recipe constructors to decide if the configuration of a
371        part has changed. If the configuration has changed, or if the recipe
372        has changed, then the part is uninstalled and reinstalled.  The
373        buildout only looks at the part's options, so any data used to
374        configure the part needs to be reflected in the part's options.  It is
375        the job of a recipe constructor to make sure that the options include
376        all relevant data.
377       
378        Of course, parts are also uninstalled if they are no-longer used.
379       
380        The recipe defines a constructor that takes a buildout object, a part
381        name, and an options dictionary. It saves them in instance attributes.
382        If the path is relative, we'll interpret it as relative to the
383        buildout directory.  The buildout object passed in is a mapping from
384        section name to a mapping of options for that section. The buildout
385        directory is available as the directory option of the buildout
386        section.  We normalize the path and save it back into the options
387        directory.
388       
389        The install method is responsible for creating the part.  In this
390        case, we need the path of the directory to create.  We'll use a path
391        option from our options dictionary.  The install method logs what it's
392        doing using the Python logging call.  We return the path that we
393        installed.  If the part is uninstalled or reinstalled, then the path
394        returned will be removed by the buildout machinery.  A recipe install
395        method is expected to return a string, or an iterable of strings
396        containing paths to be removed if a part is uninstalled.  For most
397        recipes, this is all of the uninstall support needed. For more complex
398        uninstallation scenarios use `Uninstall recipes`_.
399       
400        The update method is responsible for updating an already installed
401        part.  An empty method is often provided, as in this example, if parts
402        can't be updated.  An update method can return None, a string, or an
403        iterable of strings.  If a string or iterable of strings is returned,
404        then the saved list of paths to be uninstalled is updated with the new
405        information by adding any new files returned by the update method.
406       
407        We need to provide packaging information so that our recipe can be
408        installed as a develop egg. The minimum information we need to specify
409        [#packaging_info]_ is a name.  For recipes, we also need to define the
410        names of the recipe classes as entry points.  Packaging information is
411        provided via a setup.py script:
412       
413        >>> write(sample_buildout, 'recipes', 'setup.py',
414        ... """
415        ... from setuptools import setup
416        ...
417        ... setup(
418        ...     name = "recipes",
419        ...     entry_points = {'zc.buildout': ['mkdir = mkdir:Mkdir']},
420        ...     )
421        ... """)
422       
423        Our setup script defines an entry point. Entry points provide
424        a way for an egg to define the services it provides.  Here we've said
425        that we define a zc.buildout entry point named mkdir.  Recipe
426        classes must be exposed as entry points in the zc.buildout group.  we
427        give entry points names within the group.
428       
429        We also need a README.txt for our recipes to avoid an annoying warning
430        from distutils, on which setuptools and zc.buildout are based:
431       
432        >>> write(sample_buildout, 'recipes', 'README.txt', " ")
433       
434        Now let's update our buildout.cfg:
435       
436        >>> write(sample_buildout, 'buildout.cfg',
437        ... """
438        ... [buildout]
439        ... develop = recipes
440        ... parts = data-dir
441        ...
442        ... [data-dir]
443        ... recipe = recipes:mkdir
444        ... path = mystuff
445        ... """)
446       
447        Let's go through the changes one by one::
448       
449        develop = recipes
450       
451        This tells the buildout to install a development egg for our recipes.
452        Any number of paths can be listed.  The paths can be relative or
453        absolute.  If relative, they are treated as relative to the buildout
454        directory.  They can be directory or file paths.  If a file path is
455        given, it should point to a Python setup script.  If a directory path
456        is given, it should point to a directory containing a setup.py file.
457        Development eggs are installed before building any parts, as they may
458        provide locally-defined recipes needed by the parts.
459       
460        ::
461       
462        parts = data-dir
463       
464        Here we've named a part to be "built".  We can use any name we want
465        except that different part names must be unique and recipes will often
466        use the part name to decide what to do.
467       
468        ::
469       
470        [data-dir]
471        recipe = recipes:mkdir
472        path = mystuff
473       
474       
475        When we name a part, we also create a section of the same
476        name that contains part data.  In this section, we'll define
477        the recipe to be used to install the part.  In this case, we also
478        specify the path to be created.
479       
480        Let's run the buildout.  We do so by running the build script in the
481        buildout:
482       
483        >>> import os
484        >>> os.chdir(sample_buildout)
485        >>> buildout = os.path.join(sample_buildout, 'bin', 'buildout')
486        >>> print system(buildout),
487        Develop: '/sample-buildout/recipes'
488        Installing data-dir.
489        data-dir: Creating directory mystuff
490       
491        We see that the recipe created the directory, as expected:
492       
493        >>> ls(sample_buildout)
494        -  .installed.cfg
495        d  bin
496        -  buildout.cfg
497        d  develop-eggs
498        d  eggs
499        d  mystuff
500        d  parts
501        d  recipes
502       
503        In addition, .installed.cfg has been created containing information
504        about the part we installed:
505       
506        >>> cat(sample_buildout, '.installed.cfg')
507        [buildout]
508        installed_develop_eggs = /sample-buildout/develop-eggs/recipes.egg-link
509        parts = data-dir
510        <BLANKLINE>
511        [data-dir]
512        __buildout_installed__ = /sample-buildout/mystuff
513        __buildout_signature__ = recipes-c7vHV6ekIDUPy/7fjAaYjg==
514        path = /sample-buildout/mystuff
515        recipe = recipes:mkdir
516       
517        Note that the directory we installed is included in .installed.cfg.
518        In addition, the path option includes the actual destination
519        directory.
520       
521        If we change the name of the directory in the configuration file,
522        we'll see that the directory gets removed and recreated:
523       
524        >>> write(sample_buildout, 'buildout.cfg',
525        ... """
526        ... [buildout]
527        ... develop = recipes
528        ... parts = data-dir
529        ...
530        ... [data-dir]
531        ... recipe = recipes:mkdir
532        ... path = mydata
533        ... """)
534       
535        >>> print system(buildout),
536        Develop: '/sample-buildout/recipes'
537        Uninstalling data-dir.
538        Installing data-dir.
539        data-dir: Creating directory mydata
540       
541        >>> ls(sample_buildout)
542        -  .installed.cfg
543        d  bin
544        -  buildout.cfg
545        d  develop-eggs
546        d  eggs
547        d  mydata
548        d  parts
549        d  recipes
550       
551        If any of the files or directories created by a recipe are removed,
552        the part will be reinstalled:
553       
554        >>> rmdir(sample_buildout, 'mydata')
555        >>> print system(buildout),
556        Develop: '/sample-buildout/recipes'
557        Uninstalling data-dir.
558        Installing data-dir.
559        data-dir: Creating directory mydata
560       
561        Error reporting
562        ---------------
563       
564        If a user makes an error, an error needs to be printed and work needs
565        to stop.  This is accomplished by logging a detailed error message and
566        then raising a (or an instance of a subclass of a)
567        zc.buildout.UserError exception.  Raising an error other than a
568        UserError still displays the error, but labels it as a bug in the
569        buildout software or recipe. In the sample above, of someone gives a
570        non-existent directory to create the directory in:
571       
572       
573        >>> write(sample_buildout, 'buildout.cfg',
574        ... """
575        ... [buildout]
576        ... develop = recipes
577        ... parts = data-dir
578        ...
579        ... [data-dir]
580        ... recipe = recipes:mkdir
581        ... path = /xxx/mydata
582        ... """)
583       
584        We'll get a user error, not a traceback.
585       
586        >>> print system(buildout),
587        Develop: '/sample-buildout/recipes'
588        data-dir: Cannot create /xxx/mydata. /xxx is not a directory.
589        While:
590        Installing.
591        Getting section data-dir.
592        Initializing part data-dir.
593        Error: Invalid Path
594       
595       
596        Recipe Error Handling
597        ---------------------
598       
599        If an error occurs during installation, it is up to the recipe to
600        clean up any system side effects, such as files created.  Let's update
601        the mkdir recipe to support multiple paths:
602       
603        >>> write(sample_buildout, 'recipes', 'mkdir.py',
604        ... """
605        ... import logging, os, zc.buildout
606        ...
607        ... class Mkdir:
608        ...
609        ...     def __init__(self, buildout, name, options):
610        ...         self.name, self.options = name, options
611        ...
612        ...         # Normalize paths and check that their parent
613        ...         # directories exist:
614        ...         paths = []
615        ...         for path in options['path'].split():
616        ...             path = os.path.join(buildout['buildout']['directory'], path)
617        ...             if not os.path.isdir(os.path.dirname(path)):
618        ...                 logging.getLogger(self.name).error(
619        ...                     'Cannot create %s. %s is not a directory.',
620        ...                     options['path'], os.path.dirname(options['path']))
621        ...                 raise zc.buildout.UserError('Invalid Path')
622        ...             paths.append(path)
623        ...         options['path'] = ' '.join(paths)
624        ...
625        ...     def install(self):
626        ...         paths = self.options['path'].split()
627        ...         for path in paths:
628        ...             logging.getLogger(self.name).info(
629        ...                 'Creating directory %s', os.path.basename(path))
630        ...             os.mkdir(path)
631        ...         return paths
632        ...
633        ...     def update(self):
634        ...         pass
635        ... """)
636       
637        If there is an error creating a path, the install method will exit and
638        leave previously created paths in place:
639       
640        >>> write(sample_buildout, 'buildout.cfg',
641        ... """
642        ... [buildout]
643        ... develop = recipes
644        ... parts = data-dir
645        ...
646        ... [data-dir]
647        ... recipe = recipes:mkdir
648        ... path = foo bin
649        ... """)
650       
651        >>> print system(buildout), # doctest: +ELLIPSIS
652        Develop: '/sample-buildout/recipes'
653        Uninstalling data-dir.
654        Installing data-dir.
655        data-dir: Creating directory foo
656        data-dir: Creating directory bin
657        While:
658        Installing data-dir.
659        <BLANKLINE>
660        An internal error occured due to a bug in either zc.buildout or in a
661        recipe being used:
662        Traceback (most recent call last):
663        ...
664        OSError: [Errno 17] File exists: '/sample-buildout/bin'
665       
666        We meant to create a directory bins, but typed bin.  Now foo was
667        left behind.
668       
669        >>> os.path.exists('foo')
670        True
671       
672        If we fix the typo:
673       
674        >>> write(sample_buildout, 'buildout.cfg',
675        ... """
676        ... [buildout]
677        ... develop = recipes
678        ... parts = data-dir
679        ...
680        ... [data-dir]
681        ... recipe = recipes:mkdir
682        ... path = foo bins
683        ... """)
684       
685        >>> print system(buildout), # doctest: +ELLIPSIS
686        Develop: '/sample-buildout/recipes'
687        Installing data-dir.
688        data-dir: Creating directory foo
689        While:
690        Installing data-dir.
691        <BLANKLINE>
692        An internal error occured due to a bug in either zc.buildout or in a
693        recipe being used:
694        Traceback (most recent call last):
695        ...
696        OSError: [Errno 17] File exists: '/sample-buildout/foo'
697       
698        Now they fail because foo exists, because it was left behind.
699       
700        >>> remove('foo')
701       
702        Let's fix the recipe:
703       
704        >>> write(sample_buildout, 'recipes', 'mkdir.py',
705        ... """
706        ... import logging, os, zc.buildout
707        ...
708        ... class Mkdir:
709        ...
710        ...     def __init__(self, buildout, name, options):
711        ...         self.name, self.options = name, options
712        ...
713        ...         # Normalize paths and check that their parent
714        ...         # directories exist:
715        ...         paths = []
716        ...         for path in options['path'].split():
717        ...             path = os.path.join(buildout['buildout']['directory'], path)
718        ...             if not os.path.isdir(os.path.dirname(path)):
719        ...                 logging.getLogger(self.name).error(
720        ...                     'Cannot create %s. %s is not a directory.',
721        ...                     options['path'], os.path.dirname(options['path']))
722        ...                 raise zc.buildout.UserError('Invalid Path')
723        ...             paths.append(path)
724        ...         options['path'] = ' '.join(paths)
725        ...
726        ...     def install(self):
727        ...         paths = self.options['path'].split()
728        ...         created = []
729        ...         try:
730        ...             for path in paths:
731        ...                 logging.getLogger(self.name).info(
732        ...                     'Creating directory %s', os.path.basename(path))
733        ...                 os.mkdir(path)
734        ...                 created.append(path)
735        ...         except:
736        ...             for d in created:
737        ...                 os.rmdir(d)
738        ...             raise
739        ...
740        ...         return paths
741        ...
742        ...     def update(self):
743        ...         pass
744        ... """)
745       
746        And put back the typo:
747       
748        >>> write(sample_buildout, 'buildout.cfg',
749        ... """
750        ... [buildout]
751        ... develop = recipes
752        ... parts = data-dir
753        ...
754        ... [data-dir]
755        ... recipe = recipes:mkdir
756        ... path = foo bin
757        ... """)
758       
759        When we rerun the buildout:
760       
761        >>> print system(buildout), # doctest: +ELLIPSIS
762        Develop: '/sample-buildout/recipes'
763        Installing data-dir.
764        data-dir: Creating directory foo
765        data-dir: Creating directory bin
766        While:
767        Installing data-dir.
768        <BLANKLINE>
769        An internal error occured due to a bug in either zc.buildout or in a
770        recipe being used:
771        Traceback (most recent call last):
772        ...
773        OSError: [Errno 17] File exists: '/sample-buildout/bin'
774       
775        .. Wait for the file to really disappear. My linux is weird.
776       
777        >>> wait_until("foo goes away", lambda : not os.path.exists('foo'))
778       
779        we get the same error, but we don't get the directory left behind:
780       
781        >>> os.path.exists('foo')
782        False
783       
784        It's critical that recipes clean up partial effects when errors
785        occur.  Because recipes most commonly create files and directories,
786        buildout provides a helper API for removing created files when an
787        error occurs.  Option objects have a created method that can be called
788        to record files as they are created.  If the install or update method
789        returns with an error, then any registered paths are removed
790        automatically.  The method returns the files registered and can be
791        used to return the files created.  Let's use this API to simplify the
792        recipe:
793       
794        >>> write(sample_buildout, 'recipes', 'mkdir.py',
795        ... """
796        ... import logging, os, zc.buildout
797        ...
798        ... class Mkdir:
799        ...
800        ...     def __init__(self, buildout, name, options):
801        ...         self.name, self.options = name, options
802        ...
803        ...         # Normalize paths and check that their parent
804        ...         # directories exist:
805        ...         paths = []
806        ...         for path in options['path'].split():
807        ...             path = os.path.join(buildout['buildout']['directory'], path)
808        ...             if not os.path.isdir(os.path.dirname(path)):
809        ...                 logging.getLogger(self.name).error(
810        ...                     'Cannot create %s. %s is not a directory.',
811        ...                     options['path'], os.path.dirname(options['path']))
812        ...                 raise zc.buildout.UserError('Invalid Path')
813        ...             paths.append(path)
814        ...         options['path'] = ' '.join(paths)
815        ...
816        ...     def install(self):
817        ...         paths = self.options['path'].split()
818        ...         for path in paths:
819        ...             logging.getLogger(self.name).info(
820        ...                 'Creating directory %s', os.path.basename(path))
821        ...             os.mkdir(path)
822        ...             self.options.created(path)
823        ...
824        ...         return self.options.created()
825        ...
826        ...     def update(self):
827        ...         pass
828        ... """)
829       
830        ..
831       
832        >>> remove(sample_buildout, 'recipes', 'mkdir.pyc')
833       
834        We returned by calling created, taking advantage of the fact that it
835        returns the registered paths.  We did this for illustrative purposes.
836        It would be simpler just to return the paths as before.
837       
838        If we rerun the buildout, again, we'll get the error and no
839        directories will be created:
840       
841        >>> print system(buildout), # doctest: +ELLIPSIS
842        Develop: '/sample-buildout/recipes'
843        Installing data-dir.
844        data-dir: Creating directory foo
845        data-dir: Creating directory bin
846        While:
847        Installing data-dir.
848        <BLANKLINE>
849        An internal error occured due to a bug in either zc.buildout or in a
850        recipe being used:
851        Traceback (most recent call last):
852        ...
853        OSError: [Errno 17] File exists: '/sample-buildout/bin'
854       
855        >>> os.path.exists('foo')
856        False
857       
858        Now, we'll fix the typo again and we'll get the directories we expect:
859       
860        >>> write(sample_buildout, 'buildout.cfg',
861        ... """
862        ... [buildout]
863        ... develop = recipes
864        ... parts = data-dir
865        ...
866        ... [data-dir]
867        ... recipe = recipes:mkdir
868        ... path = foo bins
869        ... """)
870       
871        >>> print system(buildout),
872        Develop: '/sample-buildout/recipes'
873        Installing data-dir.
874        data-dir: Creating directory foo
875        data-dir: Creating directory bins
876       
877        >>> os.path.exists('foo')
878        True
879        >>> os.path.exists('bins')
880        True
881       
882        Configuration file syntax
883        -------------------------
884       
885        As mentioned earlier, buildout configuration files use the format
886        defined by the Python ConfigParser module with extensions.  The
887        extensions are:
888       
889        - option names are case sensitive
890       
891        - option values can use a substitution syntax, described below, to
892        refer to option values in specific sections.
893       
894        - option values can be appended or removed using the - and +
895        operators.
896       
897        The ConfigParser syntax is very flexible.  Section names can contain
898        any characters other than newlines and right square braces ("]").
899        Option names can contain any characters other than newlines, colons,
900        and equal signs, can not start with a space, and don't include
901        trailing spaces.
902       
903        It is likely that, in the future, some characters will be given
904        special buildout-defined meanings.  This is already true of the
905        characters ":", "$", "%", "(", and ")".  For now, it is a good idea to
906        keep section and option names simple, sticking to alphanumeric
907        characters, hyphens, and periods.
908       
909        Variable substitutions
910        ----------------------
911       
912        Buildout configuration files support variable substitution.
913        To illustrate this, we'll create an debug recipe to
914        allow us to see interactions with the buildout:
915       
916        >>> write(sample_buildout, 'recipes', 'debug.py',
917        ... """
918        ... class Debug:
919        ...
920        ...     def __init__(self, buildout, name, options):
921        ...         self.buildout = buildout
922        ...         self.name = name
923        ...         self.options = options
924        ...
925        ...     def install(self):
926        ...         items = self.options.items()
927        ...         items.sort()
928        ...         for option, value in items:
929        ...             print option, value
930        ...         return ()
931        ...
932        ...     update = install
933        ... """)
934       
935        This recipe doesn't actually create anything. The install method
936        doesn't return anything, because it didn't create any files or
937        directories.
938       
939        We also have to update our setup script:
940       
941        >>> write(sample_buildout, 'recipes', 'setup.py',
942        ... """
943        ... from setuptools import setup
944        ... entry_points = (
945        ... '''
946        ... [zc.buildout]
947        ... mkdir = mkdir:Mkdir
948        ... debug = debug:Debug
949        ... ''')
950        ... setup(name="recipes", entry_points=entry_points)
951        ... """)
952       
953        We've rearranged the script a bit to make the entry points easier to
954        edit.  In particular, entry points are now defined as a configuration
955        string, rather than a dictionary.
956       
957        Let's update our configuration to provide variable substitution
958        examples:
959       
960        >>> write(sample_buildout, 'buildout.cfg',
961        ... """
962        ... [buildout]
963        ... develop = recipes
964        ... parts = data-dir debug
965        ... log-level = INFO
966        ...
967        ... [debug]
968        ... recipe = recipes:debug
969        ... File 1 = ${data-dir:path}/file
970        ... File 2 = ${debug:File 1}/log
971        ...
972        ... [data-dir]
973        ... recipe = recipes:mkdir
974        ... path = mydata
975        ... """)
976       
977        We used a string-template substitution for File 1 and File 2.  This
978        type of substitution uses the string.Template syntax.  Names
979        substituted are qualified option names, consisting of a section name
980        and option name joined by a colon.
981       
982        Now, if we run the buildout, we'll see the options with the values
983        substituted.
984       
985        >>> print system(buildout),
986        Develop: '/sample-buildout/recipes'
987        Uninstalling data-dir.
988        Installing data-dir.
989        data-dir: Creating directory mydata
990        Installing debug.
991        File 1 /sample-buildout/mydata/file
992        File 2 /sample-buildout/mydata/file/log
993        recipe recipes:debug
994       
995        Note that the substitution of the data-dir path option reflects the
996        update to the option performed by the mkdir recipe.
997       
998        It might seem surprising that mydata was created again.  This is
999        because we changed our recipes package by adding the debug module.
1000        The buildout system didn't know if this module could effect the mkdir
1001        recipe, so it assumed it could and reinstalled mydata.  If we rerun
1002        the buildout:
1003       
1004        >>> print system(buildout),
1005        Develop: '/sample-buildout/recipes'
1006        Updating data-dir.
1007        Updating debug.
1008        File 1 /sample-buildout/mydata/file
1009        File 2 /sample-buildout/mydata/file/log
1010        recipe recipes:debug
1011       
1012        We can see that mydata was not recreated.
1013       
1014        Note that, in this case, we didn't specify a log level, so
1015        we didn't get output about what the buildout was doing.
1016       
1017        Section and option names in variable substitutions are only allowed to
1018        contain alphanumeric characters, hyphens, periods and spaces. This
1019        restriction might be relaxed in future releases.
1020       
1021       
1022        Automatic part selection and ordering
1023        -------------------------------------
1024       
1025        When a section with a recipe is referred to, either through variable
1026        substitution or by an initializing recipe, the section is treated as a
1027        part and added to the part list before the referencing part.  For
1028        example, we can leave data-dir out of the parts list:
1029       
1030        >>> write(sample_buildout, 'buildout.cfg',
1031        ... """
1032        ... [buildout]
1033        ... develop = recipes
1034        ... parts = debug
1035        ... log-level = INFO
1036        ...
1037        ... [debug]
1038        ... recipe = recipes:debug
1039        ... File 1 = ${data-dir:path}/file
1040        ... File 2 = ${debug:File 1}/log
1041        ...
1042        ... [data-dir]
1043        ... recipe = recipes:mkdir
1044        ... path = mydata
1045        ... """)
1046       
1047       
1048        It will still be treated as a part:
1049       
1050        >>> print system(buildout),
1051        Develop: '/sample-buildout/recipes'
1052        Updating data-dir.
1053        Updating debug.
1054        File 1 /sample-buildout/mydata/file
1055        File 2 /sample-buildout/mydata/file/log
1056        recipe recipes:debug
1057       
1058        >>> cat('.installed.cfg') # doctest: +ELLIPSIS
1059        [buildout]
1060        installed_develop_eggs = /sample-buildout/develop-eggs/recipes.egg-link
1061        parts = data-dir debug
1062        ...
1063       
1064        Note that the data-dir part is included *before* the debug part,
1065        because the debug part refers to the data-dir part.  Even if we list
1066        the data-dir part after the debug part, it will be included before:
1067       
1068        >>> write(sample_buildout, 'buildout.cfg',
1069        ... """
1070        ... [buildout]
1071        ... develop = recipes
1072        ... parts = debug data-dir
1073        ... log-level = INFO
1074        ...
1075        ... [debug]
1076        ... recipe = recipes:debug
1077        ... File 1 = ${data-dir:path}/file
1078        ... File 2 = ${debug:File 1}/log
1079        ...
1080        ... [data-dir]
1081        ... recipe = recipes:mkdir
1082        ... path = mydata
1083        ... """)
1084       
1085       
1086        It will still be treated as a part:
1087       
1088        >>> print system(buildout),
1089        Develop: '/sample-buildout/recipes'
1090        Updating data-dir.
1091        Updating debug.
1092        File 1 /sample-buildout/mydata/file
1093        File 2 /sample-buildout/mydata/file/log
1094        recipe recipes:debug
1095       
1096        >>> cat('.installed.cfg') # doctest: +ELLIPSIS
1097        [buildout]
1098        installed_develop_eggs = /sample-buildout/develop-eggs/recipes.egg-link
1099        parts = data-dir debug
1100        ...
1101       
1102       
1103        Adding and removing options
1104        ---------------------------
1105       
1106        We can append and remove values to an option by using the + and -
1107        operators.
1108       
1109        This is illustrated below; first we define a base configuration.
1110       
1111        >>> write(sample_buildout, 'base.cfg',
1112        ... """
1113        ... [buildout]
1114        ... parts = part1 part2 part3
1115        ...
1116        ... [part1]
1117        ... recipe =
1118        ... option = a1 a2
1119        ...
1120        ... [part2]
1121        ... recipe =
1122        ... option = b1 b2 b3 b4
1123        ...
1124        ... [part3]
1125        ... recipe =
1126        ... option = c1 c2
1127        ...
1128        ... """)
1129       
1130        Extending this configuration, we can "adjust" the values set in the
1131        base configuration file.
1132       
1133        >>> write(sample_buildout, 'extension1.cfg',
1134        ... """
1135        ... [buildout]
1136        ... extends = base.cfg
1137        ...
1138        ... # appending values
1139        ... [part1]
1140        ... option += a3 a4
1141        ...
1142        ... # removing values
1143        ... [part2]
1144        ... option -= b1 b2
1145        ...
1146        ... # alt. spelling
1147        ... [part3]
1148        ... option+=c3 c4 c5
1149        ...
1150        ... # normal assignment
1151        ... [part4]
1152        ... option = h1 h2
1153        ...
1154        ... """)
1155       
1156        An additional extension.
1157       
1158        >>> write(sample_buildout, 'extension2.cfg',
1159        ... """
1160        ... [buildout]
1161        ... extends = extension1.cfg
1162        ...
1163        ... # appending values
1164        ... [part1]
1165        ... option += a5
1166        ...
1167        ... # removing values
1168        ... [part2]
1169        ... option -= b1 b2 b3
1170        ...
1171        ... """)
1172       
1173        To verify that the options are adjusted correctly, we'll set up an
1174        extension that prints out the options.
1175       
1176        >>> mkdir(sample_buildout, 'demo')
1177        >>> write(sample_buildout, 'demo', 'demo.py',
1178        ... """
1179        ... def ext(buildout):
1180        ...     print [part['option'] for name, part in buildout.items() \
1181        ...           if name.startswith('part')]
1182        ... """)
1183       
1184        >>> write(sample_buildout, 'demo', 'setup.py',
1185        ... """
1186        ... from setuptools import setup
1187        ...
1188        ... setup(
1189        ...     name="demo",
1190        ...     entry_points={'zc.buildout.extension': ['ext = demo:ext']},
1191        ...     )
1192        ... """)
1193       
1194        Set up a buildout configuration for this extension.
1195       
1196        >>> write(sample_buildout, 'buildout.cfg',
1197        ... """
1198        ... [buildout]
1199        ... develop = demo
1200        ... parts =
1201        ... """)
1202       
1203        >>> os.chdir(sample_buildout)
1204        >>> print system(os.path.join(sample_buildout, 'bin', 'buildout')),
1205        Develop: '/sample-buildout/demo'
1206        Uninstalling debug.
1207        Getting distribution for 'recipes'.
1208        zip_safe flag not set; analyzing archive contents...
1209        Got recipes 0.0.0.
1210        Uninstalling data-dir.
1211        warning: install_lib: 'build/lib' does not exist -- no Python modules to install
1212       
1213        Verify option values.
1214       
1215        >>> write(sample_buildout, 'buildout.cfg',
1216        ... """
1217        ... [buildout]
1218        ... develop = demo
1219        ... extensions = demo
1220        ... extends = extension2.cfg
1221        ... """)
1222       
1223        >>> print system(os.path.join('bin', 'buildout')),
1224        ['a1 a2/na3 a4/na5', 'b1 b2 b3 b4', 'c1 c2/nc3 c4 c5', 'h1 h2']
1225        Develop: '/sample-buildout/demo'
1226       
1227        Cleanup.
1228       
1229        >>> os.remove(os.path.join(sample_buildout, 'base.cfg'))
1230        >>> os.remove(os.path.join(sample_buildout, 'extension1.cfg'))
1231        >>> os.remove(os.path.join(sample_buildout, 'extension2.cfg'))
1232       
1233        Multiple configuration files
1234        ----------------------------
1235       
1236        A configuration file can "extend" another configuration file.
1237        Options are read from the other configuration file if they aren't
1238        already defined by your configuration file.
1239       
1240        The configuration files your file extends can extend
1241        other configuration files.  The same file may be
1242        used more than once although, of course, cycles aren't allowed.
1243       
1244        To see how this works, we use an example:
1245       
1246        >>> write(sample_buildout, 'buildout.cfg',
1247        ... """
1248        ... [buildout]
1249        ... extends = base.cfg
1250        ...
1251        ... [debug]
1252        ... op = buildout
1253        ... """)
1254       
1255        >>> write(sample_buildout, 'base.cfg',
1256        ... """
1257        ... [buildout]
1258        ... develop = recipes
1259        ... parts = debug
1260        ...
1261        ... [debug]
1262        ... recipe = recipes:debug
1263        ... op = base
1264        ... """)
1265       
1266        >>> print system(buildout),
1267        Develop: '/sample-buildout/recipes'
1268        Installing debug.
1269        op buildout
1270        recipe recipes:debug
1271       
1272        The example is pretty trivial, but the pattern it illustrates is
1273        pretty common.  In a more practical example, the base buildout might
1274        represent a product and the extending buildout might be a
1275        customization.
1276       
1277        Here is a more elaborate example.
1278       
1279        >>> other = tmpdir('other')
1280       
1281        >>> write(sample_buildout, 'buildout.cfg',
1282        ... """
1283        ... [buildout]
1284        ... extends = b1.cfg b2.cfg %(b3)s
1285        ...
1286        ... [debug]
1287        ... op = buildout
1288        ... """ % dict(b3=os.path.join(other, 'b3.cfg')))
1289       
1290        >>> write(sample_buildout, 'b1.cfg',
1291        ... """
1292        ... [buildout]
1293        ... extends = base.cfg
1294        ...
1295        ... [debug]
1296        ... op1 = b1 1
1297        ... op2 = b1 2
1298        ... """)
1299       
1300        >>> write(sample_buildout, 'b2.cfg',
1301        ... """
1302        ... [buildout]
1303        ... extends = base.cfg
1304        ...
1305        ... [debug]
1306        ... op2 = b2 2
1307        ... op3 = b2 3
1308        ... """)
1309       
1310        >>> write(other, 'b3.cfg',
1311        ... """
1312        ... [buildout]
1313        ... extends = b3base.cfg
1314        ...
1315        ... [debug]
1316        ... op4 = b3 4
1317        ... """)
1318       
1319        >>> write(other, 'b3base.cfg',
1320        ... """
1321        ... [debug]
1322        ... op5 = b3base 5
1323        ... """)
1324       
1325        >>> write(sample_buildout, 'base.cfg',
1326        ... """
1327        ... [buildout]
1328        ... develop = recipes
1329        ... parts = debug
1330        ...
1331        ... [debug]
1332        ... recipe = recipes:debug
1333        ... name = base
1334        ... """)
1335       
1336        >>> print system(buildout),
1337        Develop: '/sample-buildout/recipes'
1338        Uninstalling debug.
1339        Installing debug.
1340        name base
1341        op buildout
1342        op1 b1 1
1343        op2 b2 2
1344        op3 b2 3
1345        op4 b3 4
1346        op5 b3base 5
1347        recipe recipes:debug
1348       
1349        There are several things to note about this example:
1350       
1351        - We can name multiple files in an extends option.
1352       
1353        - We can reference files recursively.
1354       
1355        - Relative file names in extended options are interpreted relative to
1356        the directory containing the referencing configuration file.
1357       
1358        Loading Configuration from URLs
1359        -------------------------------
1360       
1361        Configuration files can be loaded from URLs.  To see how this works,
1362        we'll set up a web server with some configuration files.
1363       
1364        >>> server_data = tmpdir('server_data')
1365       
1366        >>> write(server_data, "r1.cfg",
1367        ... """
1368        ... [debug]
1369        ... op1 = r1 1
1370        ... op2 = r1 2
1371        ... """)
1372       
1373        >>> write(server_data, "r2.cfg",
1374        ... """
1375        ... [buildout]
1376        ... extends = r1.cfg
1377        ...
1378        ... [debug]
1379        ... op2 = r2 2
1380        ... op3 = r2 3
1381        ... """)
1382       
1383        >>> server_url = start_server(server_data)
1384       
1385        >>> write('client.cfg',
1386        ... """
1387        ... [buildout]
1388        ... develop = recipes
1389        ... parts = debug
1390        ... extends = %(url)s/r2.cfg
1391        ...
1392        ... [debug]
1393        ... recipe = recipes:debug
1394        ... name = base
1395        ... """ % dict(url=server_url))
1396       
1397       
1398        >>> print system(buildout+ ' -c client.cfg'),
1399        Develop: '/sample-buildout/recipes'
1400        Uninstalling debug.
1401        Installing debug.
1402        name base
1403        op1 r1 1
1404        op2 r2 2
1405        op3 r2 3
1406        recipe recipes:debug
1407       
1408        Here we specified a URL for the file we extended.  The file we
1409        downloaded, itself referred to a file on the server using a relative
1410        URL reference.  Relative references are interpreted relative to the
1411        base URL when they appear in configuration files loaded via URL.
1412       
1413        We can also specify a URL as the configuration file to be used by a
1414        buildout.
1415       
1416        >>> os.remove('client.cfg')
1417        >>> write(server_data, 'remote.cfg',
1418        ... """
1419        ... [buildout]
1420        ... develop = recipes
1421        ... parts = debug
1422        ... extends = r2.cfg
1423        ...
1424        ... [debug]
1425        ... recipe = recipes:debug
1426        ... name = remote
1427        ... """)
1428       
1429        >>> print system(buildout + ' -c ' + server_url + '/remote.cfg'),
1430        While:
1431        Initializing.
1432        Error: Missing option: buildout:directory
1433       
1434        Normally, the buildout directory defaults to directory
1435        containing a configuration file.  This won't work for configuration
1436        files loaded from URLs.  In this case, the buildout directory would
1437        normally be defined on the command line:
1438       
1439        >>> print system(buildout
1440        ...              + ' -c ' + server_url + '/remote.cfg'
1441        ...              + ' buildout:directory=' + sample_buildout
1442        ...              ),
1443        Develop: '/sample-buildout/recipes'
1444        Uninstalling debug.
1445        Installing debug.
1446        name remote
1447        op1 r1 1
1448        op2 r2 2
1449        op3 r2 3
1450        recipe recipes:debug
1451       
1452        User defaults
1453        -------------
1454       
1455        If the file $HOME/.buildout/default.cfg, exists, it is read before
1456        reading the configuration file.  ($HOME is the value of the HOME
1457        environment variable. The '/' is replaced by the operating system file
1458        delimiter.)
1459       
1460        >>> old_home = os.environ['HOME']
1461        >>> home = tmpdir('home')
1462        >>> mkdir(home, '.buildout')
1463        >>> write(home, '.buildout', 'default.cfg',
1464        ... """
1465        ... [debug]
1466        ... op1 = 1
1467        ... op7 = 7
1468        ... """)
1469       
1470        >>> os.environ['HOME'] = home
1471        >>> print system(buildout),
1472        Develop: '/sample-buildout/recipes'
1473        Uninstalling debug.
1474        Installing debug.
1475        name base
1476        op buildout
1477        op1 b1 1
1478        op2 b2 2
1479        op3 b2 3
1480        op4 b3 4
1481        op5 b3base 5
1482        op7 7
1483        recipe recipes:debug
1484       
1485        A buildout command-line argument, -U, can be used to suppress reading
1486        user defaults:
1487       
1488        >>> print system(buildout + ' -U'),
1489        Develop: '/sample-buildout/recipes'
1490        Uninstalling debug.
1491        Installing debug.
1492        name base
1493        op buildout
1494        op1 b1 1
1495        op2 b2 2
1496        op3 b2 3
1497        op4 b3 4
1498        op5 b3base 5
1499        recipe recipes:debug
1500       
1501        >>> os.environ['HOME'] = old_home
1502       
1503        Log level
1504        ---------
1505       
1506        We can control the level of logging by specifying a log level in out
1507        configuration file.  For example, so suppress info messages, we can
1508        set the logging level to WARNING
1509       
1510        >>> write(sample_buildout, 'buildout.cfg',
1511        ... """
1512        ... [buildout]
1513        ... log-level = WARNING
1514        ... extends = b1.cfg b2.cfg
1515        ... """)
1516       
1517        >>> print system(buildout),
1518        name base
1519        op1 b1 1
1520        op2 b2 2
1521        op3 b2 3
1522        recipe recipes:debug
1523       
1524        Uninstall recipes
1525        -----------------
1526       
1527        As we've seen, when parts are installed, buildout keeps track of files
1528        and directories that they create. When the parts are uninstalled these
1529        files and directories are deleted.
1530       
1531        Sometimes more clean up is needed. For example, a recipe might add a
1532        system service by calling chkconfig --add during installation. Later
1533        during uninstallation, chkconfig --del will need to be called to
1534        remove the system service.
1535       
1536        In order to deal with these uninstallation issues, you can register
1537        uninstall recipes. Uninstall recipes are registered using the
1538        'zc.buildout.uninstall' entry point. Parts specify uninstall recipes
1539        using the 'uninstall' option.
1540       
1541        In comparison to regular recipes, uninstall recipes are much
1542        simpler. They are simply callable objects that accept the name of the
1543        part to be uninstalled and the part's options dictionary. Uninstall
1544        recipes don't have access to the part itself since it maybe not be
1545        able to be instantiated at uninstallation time.
1546       
1547        Here's a recipe that simulates installation of a system service, along
1548        with an uninstall recipe that simulates removing the service.
1549       
1550        >>> write(sample_buildout, 'recipes', 'service.py',
1551        ... """
1552        ... class Service:
1553        ...
1554        ...     def __init__(self, buildout, name, options):
1555        ...         self.buildout = buildout
1556        ...         self.name = name
1557        ...         self.options = options
1558        ...
1559        ...     def install(self):
1560        ...         print "chkconfig --add %s" % self.options['script']
1561        ...         return ()
1562        ...
1563        ...     def update(self):
1564        ...         pass
1565        ...
1566        ...
1567        ... def uninstall_service(name, options):
1568        ...     print "chkconfig --del %s" % options['script']
1569        ... """)
1570       
1571        To use these recipes we must register them using entry points. Make
1572        sure to use the same name for the recipe and uninstall recipe. This is
1573        required to let buildout know which uninstall recipe goes with which
1574        recipe.
1575       
1576        >>> write(sample_buildout, 'recipes', 'setup.py',
1577        ... """
1578        ... from setuptools import setup
1579        ... entry_points = (
1580        ... '''
1581        ... [zc.buildout]
1582        ... mkdir = mkdir:Mkdir
1583        ... debug = debug:Debug
1584        ... service = service:Service
1585        ...
1586        ... [zc.buildout.uninstall]
1587        ... service = service:uninstall_service
1588        ... ''')
1589        ... setup(name="recipes", entry_points=entry_points)
1590        ... """)
1591       
1592        Here's how these recipes could be used in a buildout:
1593       
1594        >>> write(sample_buildout, 'buildout.cfg',
1595        ... """
1596        ... [buildout]
1597        ... develop = recipes
1598        ... parts = service
1599        ...
1600        ... [service]
1601        ... recipe = recipes:service
1602        ... script = /path/to/script
1603        ... """)
1604       
1605        When the buildout is run the service will be installed
1606       
1607        >>> print system(buildout)
1608        Develop: '/sample-buildout/recipes'
1609        Uninstalling debug.
1610        Installing service.
1611        chkconfig --add /path/to/script
1612        <BLANKLINE>
1613       
1614        The service has been installed. If the buildout is run again with no
1615        changes, the service shouldn't be changed.
1616       
1617        >>> print system(buildout)
1618        Develop: '/sample-buildout/recipes'
1619        Updating service.
1620        <BLANKLINE>
1621       
1622        Now we change the service part to trigger uninstallation and
1623        re-installation.
1624       
1625        >>> write(sample_buildout, 'buildout.cfg',
1626        ... """
1627        ... [buildout]
1628        ... develop = recipes
1629        ... parts = service
1630        ...
1631        ... [service]
1632        ... recipe = recipes:service
1633        ... script = /path/to/a/different/script
1634        ... """)
1635       
1636        >>> print system(buildout)
1637        Develop: '/sample-buildout/recipes'
1638        Uninstalling service.
1639        Running uninstall recipe.
1640        chkconfig --del /path/to/script
1641        Installing service.
1642        chkconfig --add /path/to/a/different/script
1643        <BLANKLINE>
1644       
1645        Now we remove the service part, and add another part.
1646       
1647        >>> write(sample_buildout, 'buildout.cfg',
1648        ... """
1649        ... [buildout]
1650        ... develop = recipes
1651        ... parts = debug
1652        ...
1653        ... [debug]
1654        ... recipe = recipes:debug
1655        ... """)
1656       
1657        >>> print system(buildout)
1658        Develop: '/sample-buildout/recipes'
1659        Uninstalling service.
1660        Running uninstall recipe.
1661        chkconfig --del /path/to/a/different/script
1662        Installing debug.
1663        recipe recipes:debug
1664        <BLANKLINE>
1665       
1666        Uninstall recipes don't have to take care of removing all the files
1667        and directories created by the part. This is still done automatically,
1668        following the execution of the uninstall recipe. An upshot is that an
1669        uninstallation recipe can access files and directories created by a
1670        recipe before they are deleted.
1671       
1672        For example, here's an uninstallation recipe that simulates backing up
1673        a directory before it is deleted. It is designed to work with the
1674        mkdir recipe introduced earlier.
1675       
1676        >>> write(sample_buildout, 'recipes', 'backup.py',
1677        ... """
1678        ... import os
1679        ... def backup_directory(name, options):
1680        ...     path = options['path']
1681        ...     size = len(os.listdir(path))
1682        ...     print "backing up directory %s of size %s" % (path, size)
1683        ... """)
1684       
1685        It must be registered with the zc.buildout.uninstall entry
1686        point. Notice how it is given the name 'mkdir' to associate it with
1687        the mkdir recipe.
1688       
1689        >>> write(sample_buildout, 'recipes', 'setup.py',
1690        ... """
1691        ... from setuptools import setup
1692        ... entry_points = (
1693        ... '''
1694        ... [zc.buildout]
1695        ... mkdir = mkdir:Mkdir
1696        ... debug = debug:Debug
1697        ... service = service:Service
1698        ...
1699        ... [zc.buildout.uninstall]
1700        ... uninstall_service = service:uninstall_service
1701        ... mkdir = backup:backup_directory
1702        ... ''')
1703        ... setup(name="recipes", entry_points=entry_points)
1704        ... """)
1705       
1706        Now we can use it with a mkdir part.
1707       
1708        >>> write(sample_buildout, 'buildout.cfg',
1709        ... """
1710        ... [buildout]
1711        ... develop = recipes
1712        ... parts = dir debug
1713        ...
1714        ... [dir]
1715        ... recipe = recipes:mkdir
1716        ... path = my_directory
1717        ...
1718        ... [debug]
1719        ... recipe = recipes:debug
1720        ... """)
1721       
1722        Run the buildout to install the part.
1723       
1724        >>> print system(buildout)
1725        Develop: '/sample-buildout/recipes'
1726        Uninstalling debug.
1727        Installing dir.
1728        dir: Creating directory my_directory
1729        Installing debug.
1730        recipe recipes:debug
1731        <BLANKLINE>
1732       
1733        Now we remove the part from the configuration file.
1734       
1735        >>> write(sample_buildout, 'buildout.cfg',
1736        ... """
1737        ... [buildout]
1738        ... develop = recipes
1739        ... parts = debug
1740        ...
1741        ... [debug]
1742        ... recipe = recipes:debug
1743        ... """)
1744       
1745        When the buildout is run the part is removed, and the uninstall recipe
1746        is run before the directory is deleted.
1747       
1748        >>> print system(buildout)
1749        Develop: '/sample-buildout/recipes'
1750        Uninstalling dir.
1751        Running uninstall recipe.
1752        backing up directory /sample-buildout/my_directory of size 0
1753        Updating debug.
1754        recipe recipes:debug
1755        <BLANKLINE>
1756       
1757        Now we will return the registration to normal for the benefit of the
1758        rest of the examples.
1759       
1760        >>> write(sample_buildout, 'recipes', 'setup.py',
1761        ... """
1762        ... from setuptools import setup
1763        ... entry_points = (
1764        ... '''
1765        ... [zc.buildout]
1766        ... mkdir = mkdir:Mkdir
1767        ... debug = debug:Debug
1768        ... ''')
1769        ... setup(name="recipes", entry_points=entry_points)
1770        ... """)
1771       
1772       
1773        Command-line usage
1774        ------------------
1775       
1776        A number of arguments can be given on the buildout command line.  The
1777        command usage is::
1778       
1779        buildout [options and assignments] [command [command arguments]]
1780       
1781        The following options are supported:
1782       
1783        -h (or --help)
1784        Print basic usage information.  If this option is used, then all
1785        other options are ignored.
1786       
1787        -c filename
1788        The -c option can be used to specify a configuration file, rather than
1789        buildout.cfg in the current directory.
1790       
1791       
1792        -t socket_timeout
1793       
1794        Specify the socket timeout in seconds.
1795       
1796        -v
1797        Increment the verbosity by 10.  The verbosity is used to adjust
1798        the logging level.  The verbosity is subtracted from the numeric
1799        value of the log-level option specified in the configuration file.
1800       
1801        -q
1802        Decrement the verbosity by 10.
1803       
1804        -U
1805        Don't read user-default configuration.
1806       
1807        -o
1808        Run in off-line mode.  This is equivalent to the assignment
1809        buildout:offline=true.
1810       
1811        -O
1812        Run in non-off-line mode.  This is equivalent to the assignment
1813        buildout:offline=false.  This is the default buildout mode.  The
1814        -O option would normally be used to override a true offline
1815        setting in a configuration file.
1816       
1817        -n
1818        Run in newest mode.  This is equivalent to the assignment
1819        buildout:newest=true.  With this setting, which is the default,
1820        buildout will try to find the newest versions of distributions
1821        available that satisfy its requirements.
1822       
1823        -N
1824        Run in non-newest mode.  This is equivalent to the assignment
1825        buildout:newest=false.  With this setting, buildout will not seek
1826        new distributions if installed distributions satisfy it's
1827        requirements.
1828       
1829        Assignments are of the form::
1830       
1831        section_name:option_name=value
1832       
1833        Options and assignments can be given in any order.
1834       
1835        Here's an example:
1836       
1837        >>> write(sample_buildout, 'other.cfg',
1838        ... """
1839        ... [buildout]
1840        ... develop = recipes
1841        ... parts = debug
1842        ... installed = .other.cfg
1843        ... log-level = WARNING
1844        ...
1845        ... [debug]
1846        ... name = other
1847        ... recipe = recipes:debug
1848        ... """)
1849       
1850        Note that we used the installed buildout option to specify an
1851        alternate file to store information about installed parts.
1852       
1853        >>> print system(buildout+' -c other.cfg debug:op1=foo -v'),
1854        Develop: '/sample-buildout/recipes'
1855        Installing debug.
1856        name other
1857        op1 foo
1858        recipe recipes:debug
1859       
1860        Here we used the -c option to specify an alternate configuration file,
1861        and the -v option to increase the level of logging from the default,
1862        WARNING.
1863       
1864        Options can also be combined in the usual Unix way, as in:
1865       
1866        >>> print system(buildout+' -vcother.cfg debug:op1=foo'),
1867        Develop: '/sample-buildout/recipes'
1868        Updating debug.
1869        name other
1870        op1 foo
1871        recipe recipes:debug
1872       
1873        Here we combined the -v and -c options with the configuration file
1874        name.  Note that the -c option has to be last, because it takes an
1875        argument.
1876       
1877        >>> os.remove(os.path.join(sample_buildout, 'other.cfg'))
1878        >>> os.remove(os.path.join(sample_buildout, '.other.cfg'))
1879       
1880        The most commonly used command is 'install' and it takes a list of
1881        parts to install. if any parts are specified, only those parts are
1882        installed.  To illustrate this, we'll update our configuration and run
1883        the buildout in the usual way:
1884       
1885        >>> write(sample_buildout, 'buildout.cfg',
1886        ... """
1887        ... [buildout]
1888        ... develop = recipes
1889        ... parts = debug d1 d2 d3
1890        ...
1891        ... [d1]
1892        ... recipe = recipes:mkdir
1893        ... path = d1
1894        ...
1895        ... [d2]
1896        ... recipe = recipes:mkdir
1897        ... path = d2
1898        ...
1899        ... [d3]
1900        ... recipe = recipes:mkdir
1901        ... path = d3
1902        ...
1903        ... [debug]
1904        ... recipe = recipes:debug
1905        ... """)
1906       
1907        >>> print system(buildout),
1908        Develop: '/sample-buildout/recipes'
1909        Uninstalling debug.
1910        Installing debug.
1911        recipe recipes:debug
1912        Installing d1.
1913        d1: Creating directory d1
1914        Installing d2.
1915        d2: Creating directory d2
1916        Installing d3.
1917        d3: Creating directory d3
1918       
1919        >>> ls(sample_buildout)
1920        -  .installed.cfg
1921        -  b1.cfg
1922        -  b2.cfg
1923        -  base.cfg
1924        d  bin
1925        -  buildout.cfg
1926        d  d1
1927        d  d2
1928        d  d3
1929        d  demo
1930        d  develop-eggs
1931        d  eggs
1932        d  parts
1933        d  recipes
1934       
1935        >>> cat(sample_buildout, '.installed.cfg')
1936        [buildout]
1937        installed_develop_eggs = /sample-buildout/develop-eggs/recipes.egg-link
1938        parts = debug d1 d2 d3
1939        <BLANKLINE>
1940        [debug]
1941        __buildout_installed__ =
1942        __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
1943        recipe = recipes:debug
1944        <BLANKLINE>
1945        [d1]
1946        __buildout_installed__ = /sample-buildout/d1
1947        __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
1948        path = /sample-buildout/d1
1949        recipe = recipes:mkdir
1950        <BLANKLINE>
1951        [d2]
1952        __buildout_installed__ = /sample-buildout/d2
1953        __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
1954        path = /sample-buildout/d2
1955        recipe = recipes:mkdir
1956        <BLANKLINE>
1957        [d3]
1958        __buildout_installed__ = /sample-buildout/d3
1959        __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
1960        path = /sample-buildout/d3
1961        recipe = recipes:mkdir
1962       
1963        Now we'll update our configuration file:
1964       
1965        >>> write(sample_buildout, 'buildout.cfg',
1966        ... """
1967        ... [buildout]
1968        ... develop = recipes
1969        ... parts = debug d2 d3 d4
1970        ...
1971        ... [d2]
1972        ... recipe = recipes:mkdir
1973        ... path = data2
1974        ...
1975        ... [d3]
1976        ... recipe = recipes:mkdir
1977        ... path = data3
1978        ...
1979        ... [d4]
1980        ... recipe = recipes:mkdir
1981        ... path = ${d2:path}-extra
1982        ...
1983        ... [debug]
1984        ... recipe = recipes:debug
1985        ... x = 1
1986        ... """)
1987       
1988        and run the buildout specifying just d3 and d4:
1989       
1990        >>> print system(buildout+' install d3 d4'),
1991        Develop: '/sample-buildout/recipes'
1992        Uninstalling d3.
1993        Installing d3.
1994        d3: Creating directory data3
1995        Installing d4.
1996        d4: Creating directory data2-extra
1997       
1998        >>> ls(sample_buildout)
1999        -  .installed.cfg
2000        -  b1.cfg
2001        -  b2.cfg
2002        -  base.cfg
2003        d  bin
2004        -  buildout.cfg
2005        d  d1
2006        d  d2
2007        d  data2-extra
2008        d  data3
2009        d  demo
2010        d  develop-eggs
2011        d  eggs
2012        d  parts
2013        d  recipes
2014       
2015        Only the d3 and d4 recipes ran.  d3 was removed and data3 and data2-extra
2016        were created.
2017       
2018        The .installed.cfg is only updated for the recipes that ran:
2019       
2020        >>> cat(sample_buildout, '.installed.cfg')
2021        [buildout]
2022        installed_develop_eggs = /sample-buildout/develop-eggs/recipes.egg-link
2023        parts = debug d1 d2 d3 d4
2024        <BLANKLINE>
2025        [debug]
2026        __buildout_installed__ =
2027        __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
2028        recipe = recipes:debug
2029        <BLANKLINE>
2030        [d1]
2031        __buildout_installed__ = /sample-buildout/d1
2032        __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
2033        path = /sample-buildout/d1
2034        recipe = recipes:mkdir
2035        <BLANKLINE>
2036        [d2]
2037        __buildout_installed__ = /sample-buildout/d2
2038        __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
2039        path = /sample-buildout/d2
2040        recipe = recipes:mkdir
2041        <BLANKLINE>
2042        [d3]
2043        __buildout_installed__ = /sample-buildout/data3
2044        __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
2045        path = /sample-buildout/data3
2046        recipe = recipes:mkdir
2047        <BLANKLINE>
2048        [d4]
2049        __buildout_installed__ = /sample-buildout/data2-extra
2050        __buildout_signature__ = recipes-PiIFiO8ny5yNZ1S3JfT0xg==
2051        path = /sample-buildout/data2-extra
2052        recipe = recipes:mkdir
2053       
2054        Note that the installed data for debug, d1, and d2 haven't changed,
2055        because we didn't install those parts and that the d1 and d2
2056        directories are still there.
2057       
2058        Now, if we run the buildout without the install command:
2059       
2060        >>> print system(buildout),
2061        Develop: '/sample-buildout/recipes'
2062        Uninstalling d2.
2063        Uninstalling d1.
2064        Uninstalling debug.
2065        Installing debug.
2066        recipe recipes:debug
2067        x 1
2068        Installing d2.
2069        d2: Creating directory data2
2070        Updating d3.
2071        Updating d4.
2072       
2073        We see the output of the debug recipe and that data2 was created.  We
2074        also see that d1 and d2 have gone away:
2075       
2076        >>> ls(sample_buildout)
2077        -  .installed.cfg
2078        -  b1.cfg
2079        -  b2.cfg
2080        -  base.cfg
2081        d  bin
2082        -  buildout.cfg
2083        d  data2
2084        d  data2-extra
2085        d  data3
2086        d  demo
2087        d  develop-eggs
2088        d  eggs
2089        d  parts
2090        d  recipes
2091       
2092        Alternate directory and file locations
2093        --------------------------------------
2094       
2095        The buildout normally puts the bin, eggs, and parts directories in the
2096        directory in the directory containing the configuration file. You can
2097        provide alternate locations, and even names for these directories.
2098       
2099        >>> alt = tmpdir('sample-alt')
2100       
2101        >>> write(sample_buildout, 'buildout.cfg',
2102        ... """
2103        ... [buildout]
2104        ... develop = recipes
2105        ... parts =
2106        ... develop-eggs-directory = %(developbasket)s
2107        ... eggs-directory = %(basket)s
2108        ... bin-directory = %(scripts)s
2109        ... parts-directory = %(work)s
2110        ... """ % dict(
2111        ...    developbasket = os.path.join(alt, 'developbasket'),
2112        ...    basket = os.path.join(alt, 'basket'),
2113        ...    scripts = os.path.join(alt, 'scripts'),
2114        ...    work = os.path.join(alt, 'work'),
2115        ... ))
2116       
2117        >>> print system(buildout),
2118        Creating directory '/sample-alt/scripts'.
2119        Creating directory '/sample-alt/work'.
2120        Creating directory '/sample-alt/basket'.
2121        Creating directory '/sample-alt/developbasket'.
2122        Develop: '/sample-buildout/recipes'
2123        Uninstalling d4.
2124        Uninstalling d3.
2125        Uninstalling d2.
2126        Uninstalling debug.
2127       
2128        >>> ls(alt)
2129        d  basket
2130        d  developbasket
2131        d  scripts
2132        d  work
2133       
2134        >>> ls(alt, 'developbasket')
2135        -  recipes.egg-link
2136       
2137        You can also specify an alternate buildout directory:
2138       
2139        >>> rmdir(alt)
2140        >>> alt = tmpdir('sample-alt')
2141       
2142        >>> write(sample_buildout, 'buildout.cfg',
2143        ... """
2144        ... [buildout]
2145        ... directory = %(alt)s
2146        ... develop = %(recipes)s
2147        ... parts =
2148        ... """ % dict(
2149        ...    alt=alt,
2150        ...    recipes=os.path.join(sample_buildout, 'recipes'),
2151        ...    ))
2152       
2153        >>> print system(buildout),
2154        Creating directory '/sample-alt/bin'.
2155        Creating directory '/sample-alt/parts'.
2156        Creating directory '/sample-alt/eggs'.
2157        Creating directory '/sample-alt/develop-eggs'.
2158        Develop: '/sample-buildout/recipes'
2159       
2160        >>> ls(alt)
2161        -  .installed.cfg
2162        d  bin
2163        d  develop-eggs
2164        d  eggs
2165        d  parts
2166       
2167        >>> ls(alt, 'develop-eggs')
2168        -  recipes.egg-link
2169       
2170        Logging control
2171        ---------------
2172       
2173        Three buildout options are used to control logging:
2174       
2175        log-level
2176        specifies the log level
2177       
2178        verbosity
2179        adjusts the log level
2180       
2181        log-format
2182        allows an alternate logging for mat to be specified
2183       
2184        We've already seen the log level and verbosity.  Let's look at an example
2185        of changing the format:
2186       
2187        >>> write(sample_buildout, 'buildout.cfg',
2188        ... """
2189        ... [buildout]
2190        ... develop = recipes
2191        ... parts =
2192        ... log-level = 25
2193        ... verbosity = 5
2194        ... log-format = %(levelname)s %(message)s
2195        ... """)
2196       
2197        Here, we've changed the format to include the log-level name, rather
2198        than the logger name.
2199       
2200        We've also illustrated, with a contrived example, that the log level
2201        can be a numeric value and that the verbosity can be specified in the
2202        configuration file.  Because the verbosity is subtracted from the log
2203        level, we get a final log level of 20, which is the INFO level.
2204       
2205        >>> print system(buildout),
2206        INFO Develop: '/sample-buildout/recipes'
2207       
2208        Predefined buildout options
2209        ---------------------------
2210       
2211        Buildouts have a number of predefined options that recipes can use
2212        and that users can override in their configuration files.  To see
2213        these, we'll run a minimal buildout configuration with a debug logging
2214        level.  One of the features of debug logging is that the configuration
2215        database is shown.
2216       
2217        >>> write(sample_buildout, 'buildout.cfg',
2218        ... """
2219        ... [buildout]
2220        ... parts =
2221        ... """)
2222       
2223        >>> print system(buildout+' -vv'),
2224        Installing 'zc.buildout', 'setuptools'.
2225        We have a develop egg: zc.buildout 1.0.0.
2226        We have the best distribution that satisfies 'setuptools'.
2227        Picked: setuptools = 0.6
2228        <BLANKLINE>
2229        Configuration data:
2230        [buildout]
2231        bin-directory = /sample-buildout/bin
2232        develop-eggs-directory = /sample-buildout/develop-eggs
2233        directory = /sample-buildout
2234        eggs-directory = /sample-buildout/eggs
2235        executable = /usr/local/bin/python2.3
2236        installed = /sample-buildout/.installed.cfg
2237        log-format =
2238        log-level = INFO
2239        newest = true
2240        offline = false
2241        parts =
2242        parts-directory = /sample-buildout/parts
2243        python = buildout
2244        verbosity = 20
2245        <BLANKLINE>
2246       
2247        All of these options can be overridden by configuration files or by
2248        command-line assignments.  We've discussed most of these options
2249        already, but let's review them and touch on some we haven't discussed:
2250       
2251        bin-directory
2252        The directory path where scripts are written.  This can be a
2253        relative path, which is interpreted relative to the directory
2254        option.
2255       
2256        develop-eggs-directory
2257        The directory path where development egg links are created for software
2258        being created in the local project.  This can be a relative path,
2259        which is interpreted relative to the directory option.
2260       
2261        directory
2262        The buildout directory.  This is the base for other buildout file
2263        and directory locations, when relative locations are used.
2264       
2265        eggs-directory
2266        The directory path where downloaded eggs are put.  It is common to share
2267        this directory across buildouts. Eggs in this directory should
2268        *never* be modified.  This can be a relative path, which is
2269        interpreted relative to the directory option.
2270       
2271        executable
2272        The Python executable used to run the buildout.  See the python
2273        option below.
2274       
2275        installed
2276        The file path where information about the results of the previous
2277        buildout run is written.  This can be a relative path, which is
2278        interpreted relative to the directory option.  This file provides
2279        an inventory of installed parts with information needed to decide
2280        which if any parts need to be uninstalled.
2281       
2282        log-format
2283        The format used for logging messages.
2284       
2285        log-level
2286        The log level before verbosity adjustment
2287       
2288        parts
2289        A white space separated list of parts to be installed.
2290       
2291        parts-directory
2292        A working directory that parts can used to store data.
2293       
2294        python
2295        The name of a section containing information about the default
2296        Python interpreter.  Recipes that need a installation
2297        typically have options to tell them which Python installation to
2298        use.  By convention, if a section-specific option isn't used, the
2299        option is looked for in the buildout section.  The option must
2300        point to a section with an executable option giving the path to a
2301        Python executable.  By default, the buildout section defines the
2302        default Python as the Python used to run the buildout.
2303       
2304        verbosity
2305        A log-level adjustment.  Typically, this is set via the -q and -v
2306        command-line options.
2307       
2308       
2309        Creating new buildouts and bootstrapping
2310        ----------------------------------------
2311       
2312        If zc.buildout is installed, you can use it to create a new buildout
2313        with it's own local copies of zc.buildout and setuptools and with
2314        local buildout scripts.
2315       
2316        >>> sample_bootstrapped = tmpdir('sample-bootstrapped')
2317       
2318        >>> print system(buildout
2319        ...              +' -c'+os.path.join(sample_bootstrapped, 'setup.cfg')
2320        ...              +' init'),
2321        Creating '/sample-bootstrapped/setup.cfg'.
2322        Creating directory '/sample-bootstrapped/bin'.
2323        Creating directory '/sample-bootstrapped/parts'.
2324        Creating directory '/sample-bootstrapped/eggs'.
2325        Creating directory '/sample-bootstrapped/develop-eggs'.
2326        Generated script '/sample-bootstrapped/bin/buildout'.
2327       
2328        Note that a basic setup.cfg was created for us.
2329       
2330        >>> ls(sample_bootstrapped)
2331        d  bin
2332        d  develop-eggs
2333        d  eggs
2334        d  parts
2335        -  setup.cfg
2336       
2337        >>> ls(sample_bootstrapped, 'bin')
2338        -  buildout
2339       
2340        >>> _ = (ls(sample_bootstrapped, 'eggs'),
2341        ...      ls(sample_bootstrapped, 'develop-eggs'))
2342        -  setuptools-0.6-py2.3.egg
2343        -  zc.buildout-1.0-py2.3.egg
2344       
2345        (We list both the eggs and develop-eggs directories because the
2346        buildout or setuptools egg could be installed in the develop-eggs
2347        directory if the original buildout had develop eggs for either
2348        buildout or setuptools.)
2349       
2350        Note that the buildout script was installed but not run.  To run
2351        the buildout, we'd have to run the installed buildout script.
2352       
2353        If we have an existing buildout that already has a buildout.cfg, we'll
2354        normally use the bootstrap command instead of init.  It will complain
2355        if there isn't a configuration file:
2356       
2357        >>> sample_bootstrapped2 = tmpdir('sample-bootstrapped2')
2358       
2359        >>> print system(buildout
2360        ...              +' -c'+os.path.join(sample_bootstrapped2, 'setup.cfg')
2361        ...              +' bootstrap'),
2362        While:
2363        Initializing.
2364        Error: Couldn't open /sample-bootstrapped2/setup.cfg
2365       
2366        >>> write(sample_bootstrapped2, 'setup.cfg',
2367        ... """
2368        ... [buildout]
2369        ... parts =
2370        ... """)
2371       
2372        >>> print system(buildout
2373        ...              +' -c'+os.path.join(sample_bootstrapped2, 'setup.cfg')
2374        ...              +' bootstrap'),
2375        Creating directory '/sample-bootstrapped2/bin'.
2376        Creating directory '/sample-bootstrapped2/parts'.
2377        Creating directory '/sample-bootstrapped2/eggs'.
2378        Creating directory '/sample-bootstrapped2/develop-eggs'.
2379        Generated script '/sample-bootstrapped2/bin/buildout'.
2380       
2381       
2382        Newest and Offline Modes
2383        ------------------------
2384       
2385        By default buildout and recipes will try to find the newest versions
2386        of distributions needed to satisfy requirements.  This can be very
2387        time consuming, especially when incrementally working on setting up a
2388        buildout or working on a recipe.  The buildout newest option can be
2389        used to to suppress this.  If the newest option is set to false, then
2390        new distributions won't be sought if an installed distribution meets
2391        requirements.  The newest option can be set to false using the -N
2392        command-line option.
2393       
2394        The offline option goes a bit further.  If the buildout offline option
2395        is given a value of "true", the buildout and recipes that are aware of
2396        the option will avoid doing network access.  This is handy when
2397        running the buildout when not connected to the internet.  It also
2398        makes buildouts run much faster. This option is typically set using
2399        the buildout -o option.
2400       
2401        Preferring Final Releases
2402        -------------------------
2403       
2404        Currently, when searching for new releases, the newest available
2405        release is used.  This isn't usually ideal, as you may get a
2406        development release or alpha releases not ready to be widely used.
2407        You can request that final releases be preferred using the prefer
2408        final option in the buildout section::
2409       
2410        [buildout]
2411        ...
2412        prefer-final = true
2413       
2414        When the prefer-final option is set to true, then when searching for
2415        new releases, final releases are preferred.  If there are final
2416        releases that satisfy distribution requirements, then those releases
2417        are used even if newer non-final releases are available.  The buildout
2418        prefer-final option can be used to override this behavior.
2419       
2420        In buildout version 2, final releases will be preferred by default.
2421        You will then need to use a false value for prefer-final to get the
2422        newest releases.
2423       
2424        Finding distributions
2425        ---------------------
2426       
2427        By default, buildout searches the Python Package Index when looking
2428        for distributions. You can, instead, specify your own index to search
2429        using the `index` option::
2430       
2431        [buildout]
2432        ...
2433        index = http://index.example.com/
2434       
2435        This index, or the default of http://pypi.python.org/simple/ if no
2436        index is specified, will always be searched for distributions unless
2437        running buildout with options that prevent searching for
2438        distributions. The latest version of the distribution that meets the
2439        requirements of the buildout will always be used.
2440       
2441        You can also specify more locations to search for distributions using
2442        the `find-links` option. All locations specified will be searched for
2443        distributions along with the package index as described before.
2444       
2445        Locations can be urls::
2446       
2447        [buildout]
2448        ...
2449        find-links = http://download.zope.org/distribution/
2450       
2451        They can also be directories on disk::
2452       
2453        [buildout]
2454        ...
2455        find-links = /some/path
2456       
2457        Finally, they can also be direct paths to distributions::
2458       
2459        [buildout]
2460        ...
2461        find-links = /some/path/someegg-1.0.0-py2.3.egg
2462       
2463        Any number of locations can be specified in the `find-links` option::
2464       
2465        [buildout]
2466        ...
2467        find-links =
2468        http://download.zope.org/distribution/
2469        /some/otherpath
2470        /some/path/someegg-1.0.0-py2.3.egg
2471       
2472        Dependency links
2473        ----------------
2474       
2475        By default buildout will obey the setuptools dependency_links metadata
2476        when it looks for dependencies. This behavior can be controlled with
2477        the use-dependency-links buildout option::
2478       
2479        [buildout]
2480        ...
2481        use-dependency-links = false
2482       
2483        The option defaults to true. If you set it to false, then dependency
2484        links are only looked for in the locations specified by find-links.
2485       
2486        Controlling the installation database
2487        -------------------------------------
2488       
2489        The buildout installed option is used to specify the file used to save
2490        information on installed parts.  This option is initialized to
2491        ".installed.cfg", but it can be overridden in the configuration file
2492        or on the command line:
2493       
2494        >>> write('buildout.cfg',
2495        ... """
2496        ... [buildout]
2497        ... develop = recipes
2498        ... parts = debug
2499        ...
2500        ... [debug]
2501        ... recipe = recipes:debug
2502        ... """)
2503       
2504        >>> print system(buildout+' buildout:installed=inst.cfg'),
2505        Develop: '/sample-buildout/recipes'
2506        Installing debug.
2507        recipe recipes:debug
2508       
2509        >>> ls(sample_buildout)
2510        -  b1.cfg
2511        -  b2.cfg
2512        -  base.cfg
2513        d  bin
2514        -  buildout.cfg
2515        d  demo
2516        d  develop-eggs
2517        d  eggs
2518        -  inst.cfg
2519        d  parts
2520        d  recipes
2521       
2522        The installation database can be disabled by supplying an empty
2523        buildout installed option:
2524       
2525        >>> os.remove('inst.cfg')
2526        >>> print system(buildout+' buildout:installed='),
2527        Develop: '/sample-buildout/recipes'
2528        Installing debug.
2529        recipe recipes:debug
2530       
2531        >>> ls(sample_buildout)
2532        -  b1.cfg
2533        -  b2.cfg
2534        -  base.cfg
2535        d  bin
2536        -  buildout.cfg
2537        d  demo
2538        d  develop-eggs
2539        d  eggs
2540        d  parts
2541        d  recipes
2542       
2543       
2544        Note that there will be no installation database if there are no
2545        parts:
2546       
2547        >>> write('buildout.cfg',
2548        ... """
2549        ... [buildout]
2550        ... parts =
2551        ... """)
2552       
2553        >>> print system(buildout+' buildout:installed=inst.cfg'),
2554       
2555        >>> ls(sample_buildout)
2556        -  b1.cfg
2557        -  b2.cfg
2558        -  base.cfg
2559        d  bin
2560        -  buildout.cfg
2561        d  demo
2562        d  develop-eggs
2563        d  eggs
2564        d  parts
2565        d  recipes
2566       
2567        Extensions
2568        ----------
2569       
2570        An **experimental** feature allows code to be loaded and run after
2571        configuration files have been read but before the buildout has begun
2572        any processing.  The intent is to allow special plugins such as
2573        urllib2 request handlers to be loaded.
2574       
2575        To load an extension, we use the extensions option and list one or
2576        more distribution requirements, on separate lines.  The distributions
2577        named will be loaded and any zc.buildout.extensions entry points found
2578        will be called with the buildout as an argument.
2579       
2580        Let's create a sample extension in our sample buildout created in the
2581        previous section:
2582       
2583        >>> mkdir(sample_bootstrapped, 'demo')
2584       
2585        >>> write(sample_bootstrapped, 'demo', 'demo.py',
2586        ... """
2587        ... def ext(buildout):
2588        ...     print 'ext', list(buildout)
2589        ... """)
2590       
2591        >>> write(sample_bootstrapped, 'demo', 'setup.py',
2592        ... """
2593        ... from setuptools import setup
2594        ...
2595        ... setup(
2596        ...     name = "demo",
2597        ...     entry_points = {'zc.buildout.extension': ['ext = demo:ext']},
2598        ...     )
2599        ... """)
2600       
2601        Our extension just prints out the word 'demo', and lists the sections
2602        found in the buildout passed to it.
2603       
2604        We'll update our buildout.cfg to list the demo directory as a develop
2605        egg to be built:
2606       
2607        >>> write(sample_bootstrapped, 'buildout.cfg',
2608        ... """
2609        ... [buildout]
2610        ... develop = demo
2611        ... parts =
2612        ... """)
2613       
2614        >>> os.chdir(sample_bootstrapped)
2615        >>> print system(os.path.join(sample_bootstrapped, 'bin', 'buildout')),
2616        Develop: '/sample-bootstrapped/demo'
2617       
2618        Now we can add the extensions option.  We were a bit tricky and ran
2619        the buildout once with the demo develop egg defined but without the
2620        extension option.  This is because extensions are loaded before the
2621        buildout creates develop eggs. We needed to use a separate buildout
2622        run to create the develop egg.  Normally, when eggs are loaded from
2623        the network, we wouldn't need to do anything special.
2624       
2625        >>> write(sample_bootstrapped, 'buildout.cfg',
2626        ... """
2627        ... [buildout]
2628        ... develop = demo
2629        ... extensions = demo
2630        ... parts =
2631        ... """)
2632       
2633        We see that our extension is loaded and executed:
2634       
2635        >>> print system(os.path.join(sample_bootstrapped, 'bin', 'buildout')),
2636        ext ['buildout']
2637        Develop: '/sample-bootstrapped/demo'
2638       
2639        Allow hosts
2640        -----------
2641       
2642        On some environments the links visited by `zc.buildout` can be forbidden
2643        by paranoiac firewalls. These URL might be on the chain of links
2644        visited by `zc.buildout` wheter they are defined in the `find-links` option,
2645        wheter they are defined by various eggs in their `url`, `download_url`,
2646        `dependency_links` metadata.
2647       
2648        It is even harder to track that package_index works like a spider and
2649        might visit links and go to other location.
2650       
2651        The `allow-hosts` option provides a way to prevent this, and
2652        works exactly like the one provided in `easy_install`.
2653       
2654        You can provide a list of allowed host, together with wildcards::
2655       
2656        [buildout]
2657        ...
2658       
2659        allow-hosts =
2660        *.python.org
2661        example.com
2662       
2663        All urls that does not match these hosts will not be visited.
2664       
2665        .. [#future_recipe_methods] In the future, additional methods may be
2666        added. Older recipes with fewer methods will still be
2667        supported.
2668       
2669        .. [#packaging_info] If we wanted to create a distribution from this
2670        package, we would need specify much more information.  See the
2671        `setuptools documentation
2672        <http://peak.telecommunity.com/DevCenter/setuptools>`_.
2673       
2674        Always unzipping eggs
2675        =====================
2676       
2677        By default, zc.buildout doesn't unzip zip-safe eggs.
2678       
2679        >>> write('buildout.cfg',
2680        ... '''
2681        ... [buildout]
2682        ... parts = eggs
2683        ... find-links = %(link_server)s
2684        ...
2685        ... [eggs]
2686        ... recipe = zc.recipe.egg
2687        ... eggs = demo
2688        ... ''' % globals())
2689       
2690        >>> _ = system(buildout)
2691        >>> ls('eggs')
2692        -  demo-0.4c1-py2.4.egg
2693        -  demoneeded-1.2c1-py2.4.egg
2694        d  setuptools-0.6c8-py2.4.egg
2695        -  zc.buildout.egg-link
2696       
2697        This follows the
2698        policy followed by setuptools itself.  Experience shows this policy
2699        to to be inconvenient.  Zipped eggs make debugging more difficult and
2700        often import more slowly.
2701       
2702        You can include an unzip option in the buildout section to change the
2703        default unzipping policy.
2704       
2705        >>> write('buildout.cfg',
2706        ... '''
2707        ... [buildout]
2708        ... parts = eggs
2709        ... find-links = %(link_server)s
2710        ... unzip = true
2711        ...
2712        ... [eggs]
2713        ... recipe = zc.recipe.egg
2714        ... eggs = demo
2715        ... ''' % globals())
2716       
2717       
2718        >>> import os
2719        >>> for name in os.listdir('eggs'):
2720        ...     if name.startswith('demo'):
2721        ...         remove('eggs', name)
2722       
2723        >>> _ = system(buildout)
2724        >>> ls('eggs')
2725        d  demo-0.4c1-py2.4.egg
2726        d  demoneeded-1.2c1-py2.4.egg
2727        d  setuptools-0.6c8-py2.4.egg
2728        -  zc.buildout.egg-link
2729       
2730        Repeatable buildouts: controlling eggs used
2731        ===========================================
2732       
2733        One of the goals of zc.buildout is to provide enough control to make
2734        buildouts repeatable.  It should be possible to check the buildout
2735        configuration files for a project into a version control system and
2736        later use the checked in files to get the same buildout, subject to
2737        changes in the environment outside the buildout.
2738       
2739        An advantage of using Python eggs is that depenencies of eggs used are
2740        automatically determined and used.  The automatic inclusion of
2741        depenent distributions is at odds with the goal of repeatable
2742        buildouts.
2743       
2744        To support repeatable buildouts, a versions section can be created
2745        with options for each distribution name whos version is to be fixed.
2746        The section can then be specified via the buildout versions option.
2747       
2748        To see how this works, we'll create two versions of a recipe egg:
2749       
2750        >>> mkdir('recipe')
2751        >>> write('recipe', 'recipe.py',
2752        ... '''
2753        ... class Recipe:
2754        ...     def __init__(*a): pass
2755        ...     def install(self):
2756        ...         print 'recipe v1'
2757        ...         return ()
2758        ...     update = install
2759        ... ''')
2760       
2761        >>> write('recipe', 'setup.py',
2762        ... '''
2763        ... from setuptools import setup
2764        ... setup(name='spam', version='1', py_modules=['recipe'],
2765        ...       entry_points={'zc.buildout': ['default = recipe:Recipe']},
2766        ...       )
2767        ... ''')
2768       
2769        >>> write('recipe', 'README', '')
2770       
2771        >>> print system(buildout+' setup recipe bdist_egg'), # doctest: +ELLIPSIS
2772        Running setup script 'recipe/setup.py'.
2773        ...
2774       
2775        >>> rmdir('recipe', 'build')
2776       
2777        >>> write('recipe', 'recipe.py',
2778        ... '''
2779        ... class Recipe:
2780        ...     def __init__(*a): pass
2781        ...     def install(self):
2782        ...         print 'recipe v2'
2783        ...         return ()
2784        ...     update = install
2785        ... ''')
2786       
2787        >>> write('recipe', 'setup.py',
2788        ... '''
2789        ... from setuptools import setup
2790        ... setup(name='spam', version='2', py_modules=['recipe'],
2791        ...       entry_points={'zc.buildout': ['default = recipe:Recipe']},
2792        ...       )
2793        ... ''')
2794       
2795       
2796        >>> print system(buildout+' setup recipe bdist_egg'), # doctest: +ELLIPSIS
2797        Running setup script 'recipe/setup.py'.
2798        ...
2799       
2800        and we'll configure a buildout to use it:
2801       
2802        >>> write('buildout.cfg',
2803        ... '''
2804        ... [buildout]
2805        ... parts = foo
2806        ... find-links = %s
2807        ...
2808        ... [foo]
2809        ... recipe = spam
2810        ... ''' % join('recipe', 'dist'))
2811       
2812        If we run the buildout, it will use version 2:
2813       
2814        >>> print system(buildout),
2815        Getting distribution for 'spam'.
2816        Got spam 2.
2817        Installing foo.
2818        recipe v2
2819       
2820        We can specify a versions section that lists our recipe and name it in
2821        the buildout section:
2822       
2823        >>> write('buildout.cfg',
2824        ... '''
2825        ... [buildout]
2826        ... parts = foo
2827        ... find-links = %s
2828        ... versions = release-1
2829        ...
2830        ... [release-1]
2831        ... spam = 1
2832        ... eggs = 2.2
2833        ...
2834        ... [foo]
2835        ... recipe = spam
2836        ... ''' % join('recipe', 'dist'))
2837       
2838        Here we created a release-1 section listing the version 1 for the spam
2839        distribution.  We told the buildout to use it by specifying release-1
2840        as in the versions option.
2841       
2842        Now, if we run the buildout, we'll use version 1 of the spam recipe:
2843       
2844        >>> print system(buildout),
2845        Getting distribution for 'spam==1'.
2846        Got spam 1.
2847        Uninstalling foo.
2848        Installing foo.
2849        recipe v1
2850       
2851        Running the buildout in verbose mode will help us get information
2852        about versions used. If we run the buildout in verbose mode without
2853        specifying a versions section:
2854       
2855        >>> print system(buildout+' buildout:versions= -v'), # doctest: +ELLIPSIS
2856        Installing 'zc.buildout', 'setuptools'.
2857        We have a develop egg: zc.buildout 1.0.0.
2858        We have the best distribution that satisfies 'setuptools'.
2859        Picked: setuptools = 0.6
2860        Installing 'spam'.
2861        We have the best distribution that satisfies 'spam'.
2862        Picked: spam = 2.
2863        Uninstalling foo.
2864        Installing foo.
2865        recipe v2
2866       
2867        We'll get output that includes lines that tell us what versions
2868        buildout chose a for us, like::
2869       
2870        zc.buildout.easy_install.picked: spam = 2
2871       
2872        This allows us to discover versions that are picked dynamically, so
2873        that we can fix them in a versions section.
2874       
2875        If we run the buildout with the versions section:
2876       
2877        >>> print system(buildout+' -v'), # doctest: +ELLIPSIS
2878        Installing 'zc.buildout', 'setuptools'.
2879        We have a develop egg: zc.buildout 1.0.0.
2880        We have the best distribution that satisfies 'setuptools'.
2881        Picked: setuptools = 0.6
2882        Installing 'spam'.
2883        We have the distribution that satisfies 'spam==1'.
2884        Uninstalling foo.
2885        Installing foo.
2886        recipe v1
2887       
2888        We won't get output for the spam distribution, which we didn't pick,
2889        but we will get output for setuptools, which we didn't specify
2890        versions for.
2891       
2892        You can request buildout to generate an error if it picks any
2893        versions:
2894       
2895        >>> write('buildout.cfg',
2896        ... '''
2897        ... [buildout]
2898        ... parts = foo
2899        ... find-links = %s
2900        ... versions = release-1
2901        ... allow-picked-versions = false
2902        ...
2903        ... [release-1]
2904        ... spam = 1
2905        ... eggs = 2.2
2906        ...
2907        ... [foo]
2908        ... recipe = spam
2909        ... ''' % join('recipe', 'dist'))
2910       
2911        Using a download cache
2912        ======================
2913       
2914        Normally, when distributions are installed, if any processing is
2915        needed, they are downloaded from the internet to a temporary directory
2916        and then installed from there.  A download cache can be used to avoid
2917        the download step.  This can be useful to reduce network access and to
2918        create source distributions of an entire buildout.
2919       
2920        The buildout download-cache option can be used to specify a directory
2921        to be used as a download cache.
2922       
2923        In this example, we'll create a directory to hold the cache:
2924       
2925        >>> cache = tmpdir('cache')
2926       
2927        And set up a buildout that downloads some eggs:
2928       
2929        >>> write('buildout.cfg',
2930        ... '''
2931        ... [buildout]
2932        ... parts = eggs
2933        ... download-cache = %(cache)s
2934        ... find-links = %(link_server)s
2935        ...
2936        ... [eggs]
2937        ... recipe = zc.recipe.egg
2938        ... eggs = demo ==0.2
2939        ... ''' % globals())
2940       
2941        We specified a link server that has some distributions available for
2942        download:
2943       
2944        >>> print get(link_server),
2945        <html><body>
2946        <a href="bigdemo-0.1-py2.4.egg">bigdemo-0.1-py2.4.egg</a><br>
2947        <a href="demo-0.1-py2.4.egg">demo-0.1-py2.4.egg</a><br>
2948        <a href="demo-0.2-py2.4.egg">demo-0.2-py2.4.egg</a><br>
2949        <a href="demo-0.3-py2.4.egg">demo-0.3-py2.4.egg</a><br>
2950        <a href="demo-0.4c1-py2.4.egg">demo-0.4c1-py2.4.egg</a><br>
2951        <a href="demoneeded-1.0.zip">demoneeded-1.0.zip</a><br>
2952        <a href="demoneeded-1.1.zip">demoneeded-1.1.zip</a><br>
2953        <a href="demoneeded-1.2c1.zip">demoneeded-1.2c1.zip</a><br>
2954        <a href="extdemo-1.4.zip">extdemo-1.4.zip</a><br>
2955        <a href="index/">index/</a><br>
2956        <a href="other-1.0-py2.4.egg">other-1.0-py2.4.egg</a><br>
2957        </body></html>
2958       
2959       
2960        We'll enable logging on the link server so we can see what's going on:
2961       
2962        >>> get(link_server+'enable_server_logging')
2963        GET 200 /enable_server_logging
2964        ''
2965       
2966        We also specified a download cache.
2967       
2968        If we run the buildout, we'll see the eggs installed from the link
2969        server as usual:
2970       
2971        >>> print system(buildout),
2972        GET 200 /
2973        GET 200 /demo-0.2-py2.4.egg
2974        GET 200 /demoneeded-1.2c1.zip
2975        Installing eggs.
2976        Getting distribution for 'demo==0.2'.
2977        Got demo 0.2.
2978        Getting distribution for 'demoneeded'.
2979        Got demoneeded 1.2c1.
2980        Generated script '/sample-buildout/bin/demo'.
2981       
2982        We'll also get the download cache populated.  The buildout doesn't put
2983        files in the cache directly.  It creates an intermediate directory,
2984        dist:
2985       
2986       
2987        >>> ls(cache)
2988        d  dist
2989       
2990        >>> ls(cache, 'dist')
2991        -  demo-0.2-py2.4.egg
2992        -  demoneeded-1.2c1.zip
2993       
2994        If we remove the installed eggs from eggs directory and re-run the buildout:
2995       
2996        >>> import os
2997        >>> for  f in os.listdir('eggs'):
2998        ...     if f.startswith('demo'):
2999        ...         remove('eggs', f)
3000       
3001        >>> print system(buildout),
3002        GET 200 /
3003        Updating eggs.
3004        Getting distribution for 'demo==0.2'.
3005        Got demo 0.2.
3006        Getting distribution for 'demoneeded'.
3007        Got demoneeded 1.2c1.
3008       
3009        We see that the distributions aren't downloaded, because they're
3010        downloaded from the cache.
3011       
3012        Installing solely from a download cache
3013        ---------------------------------------
3014       
3015        A download cache can be used as the basis of application source
3016        releases.  In an application source release, we want to distribute an
3017        application that can be built without making any network accesses.  In
3018        this case, we distribute a buildout with download cache and tell the
3019        buildout to install from the download cache only, without making
3020        network accesses.  The buildout install-from-cache option can be used
3021        to signal that packages should be installed only from the download
3022        cache.
3023       
3024        Let's remove our installed eggs and run the buildout with the
3025        install-from-cache option set to true:
3026       
3027        >>> for  f in os.listdir('eggs'):
3028        ...     if f.startswith('demo'):
3029        ...         remove('eggs', f)
3030       
3031        >>> write('buildout.cfg',
3032        ... '''
3033        ... [buildout]
3034        ... parts = eggs
3035        ... download-cache = %(cache)s
3036        ... install-from-cache = true
3037        ... find-links = %(link_server)s
3038        ...
3039        ... [eggs]
3040        ... recipe = zc.recipe.egg
3041        ... eggs = demo
3042        ... ''' % globals())
3043       
3044        >>> print system(buildout),
3045        Uninstalling eggs.
3046        Installing eggs.
3047        Getting distribution for 'demo'.
3048        Got demo 0.2.
3049        Getting distribution for 'demoneeded'.
3050        Got demoneeded 1.2c1.
3051        Generated script '/sample-buildout/bin/demo'.
3052       
3053        Using zc.buildout to run setup scripts
3054        ======================================
3055       
3056        zc buildout has a convenience command for running setup scripts.  Why?
3057        There are two reasons.  If a setup script doesn't import setuptools,
3058        you can't use any setuptools-provided commands, like bdist_egg.  When
3059        buildout runs a setup script, it arranges to import setuptools before
3060        running the script so setuptools-provided commands are available.
3061       
3062        If you use a squeaky-clean Python to do your development, the setup
3063        script that would import setuptools because setuptools isn't in the
3064        path.  Because buildout requires setuptools and knows where it has
3065        installed a setuptools egg, it adds the setuptools egg to the Python
3066        path before running the script.  To run a setup script, use the
3067        buildout setup command, passing the name of a script or a directory
3068        containing a setup script and arguments to the script.  Let's look at
3069        an example:
3070       
3071        >>> mkdir('test')
3072        >>> cd('test')
3073        >>> write('setup.py',
3074        ... '''
3075        ... from distutils.core import setup
3076        ... setup(name='sample')
3077        ... ''')
3078       
3079        We've created a super simple (stupid) setup script.  Note that it
3080        doesn't import setuptools.  Let's try running it to create an egg.
3081        We'll use the buildout script from our sample buildout:
3082       
3083        >>> print system(buildout+' setup'),
3084        Error: The setup command requires the path to a setup script or
3085        directory containing a setup script, and it's arguments.
3086       
3087        Oops, we forgot to give the name of the setup script:
3088       
3089        >>> print system(buildout+' setup setup.py bdist_egg'), # doctest: +ELLIPSIS
3090        Running setup script 'setup.py'.
3091        ...
3092       
3093        >>> ls('dist')
3094        -  sample-0.0.0-py2.5.egg
3095       
3096        Note that we can specify a directory name.  This is often shorter and
3097        preferred by the lazy :)
3098       
3099        >>> print system(buildout+' setup . bdist_egg'), # doctest: +ELLIPSIS
3100        Running setup script './setup.py'.
3101        ...
3102       
3103        Automatic Buildout Updates
3104        ==========================
3105       
3106        When a buildout is run, one of the first steps performed is to check
3107        for updates to either zc.buildout or setuptools.  To demonstrate this,
3108        we've creates some "new releases" of buildout and setuptools in a
3109        new_releases folder:
3110       
3111        >>> ls(new_releases)
3112        d  setuptools
3113        -  setuptools-99.99-py2.4.egg
3114        d  zc.buildout
3115        -  zc.buildout-99.99-py2.4.egg
3116       
3117        Let's update the sample buildout.cfg to look in this area:
3118       
3119        >>> write(sample_buildout, 'buildout.cfg',
3120        ... """
3121        ... [buildout]
3122        ... find-links = %(new_releases)s
3123        ... index = %(new_releases)s
3124        ... parts = show-versions
3125        ... develop = showversions
3126        ...
3127        ... [show-versions]
3128        ... recipe = showversions
3129        ... """ % dict(new_releases=new_releases))
3130       
3131        We'll also include a recipe that echos the versions of setuptools and
3132        zc.buildout used:
3133       
3134        >>> mkdir(sample_buildout, 'showversions')
3135       
3136        >>> write(sample_buildout, 'showversions', 'showversions.py',
3137        ... """
3138        ... import pkg_resources
3139        ...
3140        ... class Recipe:
3141        ...
3142        ...     def __init__(self, buildout, name, options):
3143        ...         pass
3144        ...
3145        ...     def install(self):
3146        ...         for project in 'zc.buildout', 'setuptools':
3147        ...             req = pkg_resources.Requirement.parse(project)
3148        ...             print project, pkg_resources.working_set.find(req).version
3149        ...         return ()
3150        ...     update = install
3151        ... """)
3152       
3153       
3154        >>> write(sample_buildout, 'showversions', 'setup.py',
3155        ... """
3156        ... from setuptools import setup
3157        ...
3158        ... setup(
3159        ...     name = "showversions",
3160        ...     entry_points = {'zc.buildout': ['default = showversions:Recipe']},
3161        ...     )
3162        ... """)
3163       
3164       
3165        Now if we run the buildout, the buildout will upgrade itself to the
3166        new versions found in new releases:
3167       
3168        >>> print system(buildout),
3169        Getting distribution for 'zc.buildout'.
3170        Got zc.buildout 99.99.
3171        Getting distribution for 'setuptools'.
3172        Got setuptools 99.99.
3173        Upgraded:
3174        zc.buildout version 99.99,
3175        setuptools version 99.99;
3176        restarting.
3177        Generated script '/sample-buildout/bin/buildout'.
3178        Develop: '/sample-buildout/showversions'
3179        Installing show-versions.
3180        zc.buildout 99.99
3181        setuptools 99.99
3182       
3183        Our buildout script has been updated to use the new eggs:
3184       
3185        >>> cat(sample_buildout, 'bin', 'buildout')
3186        #!/usr/local/bin/python2.4
3187        <BLANKLINE>
3188        import sys
3189        sys.path[0:0] = [
3190        '/sample-buildout/eggs/zc.buildout-99.99-py2.4.egg',
3191        '/sample-buildout/eggs/setuptools-99.99-py2.4.egg',
3192        ]
3193        <BLANKLINE>
3194        import zc.buildout.buildout
3195        <BLANKLINE>
3196        if __name__ == '__main__':
3197        zc.buildout.buildout.main()
3198       
3199        Now, let's recreate the sample buildout. If we specify constraints on
3200        the versions of zc.buildout and setuptools to use, running the
3201        buildout will install earlier versions of these packages:
3202       
3203        >>> write(sample_buildout, 'buildout.cfg',
3204        ... """
3205        ... [buildout]
3206        ... find-links = %(new_releases)s
3207        ... index = %(new_releases)s
3208        ... parts = show-versions
3209        ... develop = showversions
3210        ... zc.buildout-version = < 99
3211        ... setuptools-version = < 99
3212        ...
3213        ... [show-versions]
3214        ... recipe = showversions
3215        ... """ % dict(new_releases=new_releases))
3216       
3217        Now we can see that we actually "upgrade" to an earlier version.
3218       
3219        >>> print system(buildout),
3220        Upgraded:
3221        zc.buildout version 1.0.0,
3222        setuptools version 0.6;
3223        restarting.
3224        Generated script '/sample-buildout/bin/buildout'.
3225        Develop: '/sample-buildout/showversions'
3226        Updating show-versions.
3227        zc.buildout 1.0.0
3228        setuptools 0.6
3229       
3230        There are a number of cases, described below, in which the updates
3231        don't happen.
3232       
3233        We won't upgrade in offline mode:
3234       
3235        >>> write(sample_buildout, 'buildout.cfg',
3236        ... """
3237        ... [buildout]
3238        ... find-links = %(new_releases)s
3239        ... index = %(new_releases)s
3240        ... parts = show-versions
3241        ... develop = showversions
3242        ...
3243        ... [show-versions]
3244        ... recipe = showversions
3245        ... """ % dict(new_releases=new_releases))
3246       
3247        >>> print system(buildout+' -o'),
3248        Develop: '/sample-buildout/showversions'
3249        Updating show-versions.
3250        zc.buildout 1.0.0
3251        setuptools 0.6
3252       
3253        Or in non-newest mode:
3254       
3255        >>> print system(buildout+' -N'),
3256        Develop: '/sample-buildout/showversions'
3257        Updating show-versions.
3258        zc.buildout 1.0.0
3259        setuptools 0.6
3260       
3261        We also won't upgrade if the buildout script being run isn't in the
3262        buildouts bin directory.  To see this we'll create a new buildout
3263        directory:
3264       
3265        >>> sample_buildout2 = tmpdir('sample_buildout2')
3266        >>> write(sample_buildout2, 'buildout.cfg',
3267        ... """
3268        ... [buildout]
3269        ... find-links = %(new_releases)s
3270        ... index = %(new_releases)s
3271        ... parts =
3272        ... """ % dict(new_releases=new_releases))
3273       
3274        >>> cd(sample_buildout2)
3275        >>> print system(buildout),
3276        Creating directory '/sample_buildout2/bin'.
3277        Creating directory '/sample_buildout2/parts'.
3278        Creating directory '/sample_buildout2/eggs'.
3279        Creating directory '/sample_buildout2/develop-eggs'.
3280        Getting distribution for 'zc.buildout'.
3281        Got zc.buildout 99.99.
3282        Getting distribution for 'setuptools'.
3283        Got setuptools 99.99.
3284        Not upgrading because not running a local buildout command.
3285       
3286        >>> ls('bin')
3287       
3288        Debugging buildouts
3289        ===================
3290       
3291        Buildouts can be pretty complex.  When things go wrong, it isn't
3292        always obvious why.  Errors can occur due to problems in user input or
3293        due to bugs in zc.buildout or recipes.  When an error occurs, Python's
3294        post-mortem debugger can be used to inspect the state of the buildout
3295        or recipe code were there error occured.  To enable this, use the -D
3296        option to the buildout.  Let's create a recipe that has a bug:
3297       
3298        >>> mkdir(sample_buildout, 'recipes')
3299       
3300        >>> write(sample_buildout, 'recipes', 'mkdir.py',
3301        ... """
3302        ... import os, zc.buildout
3303        ...
3304        ... class Mkdir:
3305        ...
3306        ...     def __init__(self, buildout, name, options):
3307        ...         self.name, self.options = name, options
3308        ...         options['path'] = os.path.join(
3309        ...                               buildout['buildout']['directory'],
3310        ...                               options['path'],
3311        ...                               )
3312        ...
3313        ...     def install(self):
3314        ...         directory = self.options['directory']
3315        ...         os.mkdir(directory)
3316        ...         return directory
3317        ...
3318        ...     def update(self):
3319        ...         pass
3320        ... """)
3321       
3322        >>> write(sample_buildout, 'recipes', 'setup.py',
3323        ... """
3324        ... from setuptools import setup
3325        ...
3326        ... setup(name = "recipes",
3327        ...       entry_points = {'zc.buildout': ['mkdir = mkdir:Mkdir']},
3328        ...       )
3329        ... """)
3330       
3331        And create a buildout that uses it:
3332       
3333        >>> write(sample_buildout, 'buildout.cfg',
3334        ... """
3335        ... [buildout]
3336        ... develop = recipes
3337        ... parts = data-dir
3338        ...
3339        ... [data-dir]
3340        ... recipe = recipes:mkdir
3341        ... path = mystuff
3342        ... """)
3343       
3344        If we run the buildout, we'll get an error:
3345       
3346        >>> print system(buildout),
3347        Develop: '/sample-buildout/recipes'
3348        Installing data-dir.
3349        While:
3350        Installing data-dir.
3351        Error: Missing option: data-dir:directory
3352       
3353       
3354        If we want to debug the error, we can add the -D option. Here's we'll
3355        supply some input:
3356       
3357        >>> print system(buildout+" -D", """\
3358        ... up
3359        ... p self.options.keys()
3360        ... q
3361        ... """),
3362        Develop: '/sample-buildout/recipes'
3363        Installing data-dir.
3364        > /zc/buildout/buildout.py(925)__getitem__()
3365        -> raise MissingOption("Missing option: %s:%s" % (self.name, key))
3366        (Pdb) > /sample-buildout/recipes/mkdir.py(14)install()
3367        -> directory = self.options['directory']
3368        (Pdb) ['path', 'recipe']
3369        (Pdb) While:
3370        Installing data-dir.
3371        Traceback (most recent call last):
3372        File "/zc/buildout/buildout.py", line 1352, in main
3373        getattr(buildout, command)(args)
3374        File "/zc/buildout/buildout.py", line 383, in install
3375        installed_files = self[part]._call(recipe.install)
3376        File "/zc/buildout/buildout.py", line 961, in _call
3377        return f()
3378        File "/sample-buildout/recipes/mkdir.py", line 14, in install
3379        directory = self.options['directory']
3380        File "/zc/buildout/buildout.py", line 925, in __getitem__
3381        raise MissingOption("Missing option: %s:%s" % (self.name, key))
3382        MissingOption: Missing option: data-dir:directory
3383        <BLANKLINE>
3384        Starting pdb:
3385       
3386        Testing Support
3387        ===============
3388       
3389        The zc.buildout.testing module provides an API that can be used when
3390        writing recipe tests.  This API is documented below.  Many examples of
3391        using this API can be found in the zc.buildout, zc.recipe.egg, and
3392        zc.recipe.testrunner tests.
3393       
3394        zc.buildout.testing.buildoutSetUp(test)
3395        ---------------------------------------
3396       
3397        The buildoutSetup function can be used as a doctest setup function.
3398        It creates a sample buildout that can be used by tests, changing the
3399        current working directory to the sample_buildout. It also adds a
3400        number of names to the test namespace:
3401       
3402        ``sample_buildout``
3403        This is the name of a buildout with a basic configuration.
3404       
3405        ``buildout``
3406        This is the path of the buildout script in the sample buildout.
3407       
3408        ``ls(*path)``
3409        List the contents of a directory.  The directory path is provided as one or
3410        more strings, to be joined with os.path.join.
3411       
3412        ``cat(*path)``
3413        Display the contents of a file.   The file path is provided as one or
3414        more strings, to be joined with os.path.join.
3415       
3416        On Windows, if the file doesn't exist, the function will try
3417        adding a '-script.py' suffix.  This helps to work around a
3418        difference in script generation on windows.
3419       
3420        ``mkdir(*path)``
3421        Create a directory. The directory path is provided as one or
3422        more strings, to be joined with os.path.join.
3423       
3424        ``rmdir(*path)``
3425        Remove a directory. The directory path is provided as one or
3426        more strings, to be joined with os.path.join.
3427       
3428        ``remove(*path)``
3429        Remove a directory or file. The path is provided as one or
3430        more strings, to be joined with os.path.join.
3431       
3432        ``tmpdir(name)``
3433        Create a temporary directory with the given name.  The directory
3434        will be automatically removed at the end of the test.  The path of
3435        the created directory is returned.
3436       
3437        Further, if the the normalize_path normlaizing substitution (see
3438        below) is used, then any paths starting with this path will be
3439        normalized to::
3440       
3441        /name/restofpath
3442       
3443        No two temporary directories can be created with the same name.  A
3444        directory created with tmpdir can be removed with rmdir and recreated.
3445       
3446        Note that the sample_buildout directory is created by calling this
3447        function.
3448       
3449        ``write(*path_and_contents)``
3450        Create a file.  The file path is provided as one or more strings,
3451        to be joined with os.path.join. The last argument is the file contents.
3452       
3453        ``system(command, input='')``
3454        Execute a system command with the given input passed to the
3455        command's standard input.  The output (error and regular output)
3456        from the command is returned.
3457       
3458        ``get(url)``
3459        Get a web page.
3460       
3461        ``cd(*path)``
3462        Change to the given directory.  The directory path is provided as one or
3463        more strings, to be joined with os.path.join.
3464       
3465        The directory will be reset at the end of the test.
3466       
3467        ``join(*path)``
3468        A convenient reference to os.path.join.
3469       
3470        ``register_teardown(func)``
3471        Register a tear-down function.  The function will be called with
3472        no arguments at the end of the test.
3473       
3474        ``start_server(path)``
3475        Start a web server on the given path.  The server will be shut
3476        down at the end of the test.  The server URL is returned.
3477       
3478        You can cause the server to start and stop logging it's output
3479        using:
3480       
3481        >>> get(server_url+'enable_server_logging')
3482       
3483        and:
3484       
3485        >>> get(server_url+'disable_server_logging')
3486       
3487        This can be useful to see how buildout is interacting with a
3488        server.
3489       
3490       
3491        ``sdist(setup, dest)``
3492        Create a source distribution by running the given setup file and
3493        placing the result in the given destination directory.  If the
3494        setup argument is a directory, the thge setup.py file in that
3495        directory is used.
3496       
3497        ``bdist_egg(setup, executable, dest)``
3498        Create an egg by running the given setup file with the given
3499        Python executable and placing the result in the given destination
3500        directory.  If the setup argument is a directory, then the
3501        setup.py file in that directory is used.
3502       
3503        ``find_python(version)``
3504        Find a Python executable for the given version, where version is a
3505        string like "2.4".
3506       
3507        This function uses the following strategy to find a Python of the
3508        given version:
3509       
3510        - Look for an environment variable of the form PYTHON%(version)s.
3511       
3512        - On windows, look for \Pythonm%(version)s\python
3513       
3514        - on Unix, try running python%(version)s or just python to get the
3515        executable
3516       
3517        ``zc.buildout.testing.buildoutTearDown(test)``
3518        ----------------------------------------------
3519       
3520        Tear down everything set up by zc.buildout.testing.buildoutSetUp.  Any
3521        functions passed to register_teardown are called as well.
3522       
3523        ``install(project, destination)``
3524        ---------------------------------
3525       
3526        Install eggs for a given project into a destination.  If the
3527        destination is a test object, then the eggs directory of the
3528        sample buildout (sample_buildout) defined by the test will be used.
3529        Tests will use this to install the distributions for the packages
3530        being tested (and their dependencies) into a sample buildout. The egg
3531        to be used should already be loaded, by importing one of the modules
3532        provided, before calling this function.
3533       
3534        ``install_develop(project, destination)``
3535        -----------------------------------------
3536       
3537        Like install, but a develop egg is installed even if the current egg
3538        if not a develop egg.
3539       
3540        ``Output normalization``
3541        ------------------------
3542       
3543        Recipe tests often generate output that is dependent on temporary file
3544        locations, operating system conventions or Python versions.  To deal
3545        with these dependencies, we often use
3546        zope.testing.renormalizing.RENormalizing to normalize test output.
3547        zope.testing.renormalizing.RENormalizing takes pairs of regular
3548        expressions and substitutions. The zc.buildout.testing module provides
3549        a few helpful variables that define regular-expression/substitution
3550        pairs that you can pass to zope.testing.renormalizing.RENormalizing.
3551       
3552       
3553        ``normalize_path``
3554        Converts tests paths, based on directories created with tmpdir(),
3555        to simple paths.
3556       
3557        ``normalize_script``
3558        On Unix-like systems, scripts are implemented in single files
3559        without suffixes.  On windows, scripts are implemented with 2
3560        files, a -script.py file and a .exe file.  This normalization
3561        converts directory listings of Windows scripts to the form
3562        generated on UNix-like systems.
3563       
3564        ``normalize_egg_py``
3565        Normalize Python version and platform indicators, if specified, in
3566        egg names.
3567       
3568        Python API for egg and script installation
3569        ==========================================
3570       
3571        The easy_install module provides some functions to provide support for
3572        egg and script installation.  It provides functionality at the python
3573        level that is similar to easy_install, with a few exceptions:
3574       
3575        - By default, we look for new packages *and* the packages that
3576        they depend on.  This is somewhat like (and uses) the --upgrade
3577        option of easy_install, except that we also upgrade required
3578        packages.
3579       
3580        - If the highest-revision package satisfying a specification is
3581        already present, then we don't try to get another one.  This saves a
3582        lot of search time in the common case that packages are pegged to
3583        specific versions.
3584       
3585        - If there is a develop egg that satisfies a requirement, we don't
3586        look for additional distributions.  We always give preference to
3587        develop eggs.
3588       
3589        - Distutils options for building extensions can be passed.
3590       
3591        Distribution installation
3592        -------------------------
3593       
3594        The easy_install module provides a function, install, for installing one
3595        or more packages and their dependencies.  The install function takes 2
3596        positional arguments:
3597       
3598        - An iterable of setuptools requirement strings for the distributions
3599        to be installed, and
3600       
3601        - A destination directory to install to and to satisfy requirements
3602        from.  The destination directory can be None, in which case, no new
3603        distributions are downloaded and there will be an error if the
3604        needed distributions can't be found among those already installed.
3605       
3606        It supports a number of optional keyword arguments:
3607       
3608        links
3609        A sequence of URLs, file names, or directories to look for
3610        links to distributions.
3611       
3612        index
3613        The URL of an index server, or almost any other valid URL. :)
3614       
3615        If not specified, the Python Package Index,
3616        http://pypi.python.org/simple/, is used.  You can specify an
3617        alternate index with this option.  If you use the links option and
3618        if the links point to the needed distributions, then the index can
3619        be anything and will be largely ignored.  In the examples, here,
3620        we'll just point to an empty directory on our link server.  This
3621        will make our examples run a little bit faster.
3622       
3623        executable
3624        A path to a Python executable.  Distributions will be installed
3625        using this executable and will be for the matching Python version.
3626       
3627        path
3628        A list of additional directories to search for locally-installed
3629        distributions.
3630       
3631        always_unzip
3632        A flag indicating that newly-downloaded distributions should be
3633        directories even if they could be installed as zip files.
3634       
3635        working_set
3636        An existing working set to be augmented with additional
3637        distributions, if necessary to satisfy requirements.  This allows
3638        you to call install multiple times, if necessary, to gather
3639        multiple sets of requirements.
3640       
3641        newest
3642        A boolean value indicating whether to search for new distributions
3643        when already-installed distributions meet the requirement.  When
3644        this is true, the default, and when the destination directory is
3645        not None, then the install function will search for the newest
3646        distributions that satisfy the requirements.
3647       
3648        versions
3649        A dictionary mapping project names to version numbers to be used
3650        when selecting distributions.  This can be used to specify a set of
3651        distribution versions independent of other requirements.
3652       
3653        use_dependency_links
3654        A flag indicating whether to search for dependencies using the
3655        setup dependency_links metadata or not. If true, links are searched
3656        for using dependency_links in preference to other
3657        locations. Defaults to true.
3658       
3659        relative_paths
3660        Adjust egg paths so they are relative to the script path.  This
3661        allows scripts to work when scripts and eggs are moved, as long as
3662        they are both moved in the same way.
3663       
3664        The install method returns a working set containing the distributions
3665        needed to meet the given requirements.
3666       
3667        We have a link server that has a number of eggs:
3668       
3669        >>> print get(link_server),
3670        <html><body>
3671        <a href="bigdemo-0.1-py2.4.egg">bigdemo-0.1-py2.4.egg</a><br>
3672        <a href="demo-0.1-py2.4.egg">demo-0.1-py2.4.egg</a><br>
3673        <a href="demo-0.2-py2.4.egg">demo-0.2-py2.4.egg</a><br>
3674        <a href="demo-0.3-py2.4.egg">demo-0.3-py2.4.egg</a><br>
3675        <a href="demo-0.4c1-py2.4.egg">demo-0.4c1-py2.4.egg</a><br>
3676        <a href="demoneeded-1.0.zip">demoneeded-1.0.zip</a><br>
3677        <a href="demoneeded-1.1.zip">demoneeded-1.1.zip</a><br>
3678        <a href="demoneeded-1.2c1.zip">demoneeded-1.2c1.zip</a><br>
3679        <a href="extdemo-1.4.zip">extdemo-1.4.zip</a><br>
3680        <a href="index/">index/</a><br>
3681        <a href="other-1.0-py2.4.egg">other-1.0-py2.4.egg</a><br>
3682        </body></html>
3683       
3684        Let's make a directory and install the demo egg to it, using the demo:
3685       
3686        >>> dest = tmpdir('sample-install')
3687        >>> import zc.buildout.easy_install
3688        >>> ws = zc.buildout.easy_install.install(
3689        ...     ['demo==0.2'], dest,
3690        ...     links=[link_server], index=link_server+'index/')
3691       
3692        We requested version 0.2 of the demo distribution to be installed into
3693        the destination server.  We specified that we should search for links
3694        on the link server and that we should use the (empty) link server
3695        index directory as a package index.
3696       
3697        The working set contains the distributions we retrieved.
3698       
3699        >>> for dist in ws:
3700        ...     print dist
3701        demo 0.2
3702        demoneeded 1.1
3703       
3704        We got demoneeded because it was a dependency of demo.
3705       
3706        And the actual eggs were added to the eggs directory.
3707       
3708        >>> ls(dest)
3709        -  demo-0.2-py2.4.egg
3710        -  demoneeded-1.1-py2.4.egg
3711       
3712        If we remove the version restriction on demo, but specify a false
3713        value for newest, no new distributions will be installed:
3714       
3715        >>> ws = zc.buildout.easy_install.install(
3716        ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
3717        ...     newest=False)
3718        >>> ls(dest)
3719        -  demo-0.2-py2.4.egg
3720        -  demoneeded-1.1-py2.4.egg
3721       
3722        If we leave off the newest option, we'll get an update for demo:
3723       
3724        >>> ws = zc.buildout.easy_install.install(
3725        ...     ['demo'], dest, links=[link_server], index=link_server+'index/')
3726        >>> ls(dest)
3727        -  demo-0.2-py2.4.egg
3728        -  demo-0.3-py2.4.egg
3729        -  demoneeded-1.1-py2.4.egg
3730       
3731        Note that we didn't get the newest versions available.  There were
3732        release candidates for newer versions of both packages. By default,
3733        final releases are preferred.  We can change this behavior using the
3734        prefer_final function:
3735       
3736        >>> zc.buildout.easy_install.prefer_final(False)
3737        True
3738       
3739        The old setting is returned.
3740       
3741        >>> ws = zc.buildout.easy_install.install(
3742        ...     ['demo'], dest, links=[link_server], index=link_server+'index/')
3743        >>> for dist in ws:
3744        ...     print dist
3745        demo 0.4c1
3746        demoneeded 1.2c1
3747       
3748        >>> ls(dest)
3749        -  demo-0.2-py2.4.egg
3750        -  demo-0.3-py2.4.egg
3751        -  demo-0.4c1-py2.4.egg
3752        -  demoneeded-1.1-py2.4.egg
3753        -  demoneeded-1.2c1-py2.4.egg
3754       
3755        Let's put the setting back to the default.
3756       
3757        >>> zc.buildout.easy_install.prefer_final(True)
3758        False
3759       
3760        We can supply additional distributions.  We can also supply
3761        specifications for distributions that would normally be found via
3762        dependencies.  We might do this to specify a specific version.
3763       
3764        >>> ws = zc.buildout.easy_install.install(
3765        ...     ['demo', 'other', 'demoneeded==1.0'], dest,
3766        ...     links=[link_server], index=link_server+'index/')
3767       
3768        >>> for dist in ws:
3769        ...     print dist
3770        demo 0.3
3771        other 1.0
3772        demoneeded 1.0
3773       
3774        >>> ls(dest)
3775        -  demo-0.2-py2.4.egg
3776        -  demo-0.3-py2.4.egg
3777        -  demo-0.4c1-py2.4.egg
3778        -  demoneeded-1.0-py2.4.egg
3779        -  demoneeded-1.1-py2.4.egg
3780        -  demoneeded-1.2c1-py2.4.egg
3781        d  other-1.0-py2.4.egg
3782       
3783        We can request that eggs be unzipped even if they are zip safe.  This
3784        can be useful when debugging.
3785       
3786        >>> rmdir(dest)
3787        >>> dest = tmpdir('sample-install')
3788        >>> ws = zc.buildout.easy_install.install(
3789        ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
3790        ...     always_unzip=True)
3791       
3792        >>> ls(dest)
3793        d  demo-0.3-py2.4.egg
3794        d  demoneeded-1.1-py2.4.egg
3795       
3796        >>> rmdir(dest)
3797        >>> dest = tmpdir('sample-install')
3798        >>> ws = zc.buildout.easy_install.install(
3799        ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
3800        ...     always_unzip=False)
3801       
3802        >>> ls(dest)
3803        -  demo-0.3-py2.4.egg
3804        -  demoneeded-1.1-py2.4.egg
3805       
3806        We can also set a default by calling the always_unzip function:
3807       
3808        >>> zc.buildout.easy_install.always_unzip(True)
3809        False
3810       
3811        The old default is returned:
3812       
3813        >>> rmdir(dest)
3814        >>> dest = tmpdir('sample-install')
3815        >>> ws = zc.buildout.easy_install.install(
3816        ...     ['demo'], dest, links=[link_server], index=link_server+'index/')
3817       
3818        >>> ls(dest)
3819        d  demo-0.3-py2.4.egg
3820        d  demoneeded-1.1-py2.4.egg
3821       
3822       
3823        >>> zc.buildout.easy_install.always_unzip(False)
3824        True
3825       
3826        >>> rmdir(dest)
3827        >>> dest = tmpdir('sample-install')
3828        >>> ws = zc.buildout.easy_install.install(
3829        ...     ['demo'], dest, links=[link_server], index=link_server+'index/')
3830       
3831        >>> ls(dest)
3832        -  demo-0.3-py2.4.egg
3833        -  demoneeded-1.1-py2.4.egg
3834       
3835        >>> rmdir(dest)
3836        >>> dest = tmpdir('sample-install')
3837        >>> ws = zc.buildout.easy_install.install(
3838        ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
3839        ...     always_unzip=True)
3840       
3841        >>> ls(dest)
3842        d  demo-0.3-py2.4.egg
3843        d  demoneeded-1.1-py2.4.egg
3844       
3845        Specifying version information independent of requirements
3846        ----------------------------------------------------------
3847       
3848        Sometimes it's useful to specify version information independent of
3849        normal requirements specifications.  For example, a buildout may need
3850        to lock down a set of versions, without having to put put version
3851        numbers in setup files or part definitions.  If a dictionary is passed
3852        to the install function, mapping project names to version numbers,
3853        then the versions numbers will be used.
3854       
3855        >>> ws = zc.buildout.easy_install.install(
3856        ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
3857        ...     versions = dict(demo='0.2', demoneeded='1.0'))
3858        >>> [d.version for d in ws]
3859        ['0.2', '1.0']
3860       
3861        In this example, we specified a version for demoneeded, even though we
3862        didn't define a requirement for it.  The versions specified apply to
3863        dependencies as well as the specified requirements.
3864       
3865        If we specify a version that's incompatible with a requirement, then
3866        we'll get an error:
3867       
3868        >>> from zope.testing.loggingsupport import InstalledHandler
3869        >>> handler = InstalledHandler('zc.buildout.easy_install')
3870        >>> import logging
3871        >>> logging.getLogger('zc.buildout.easy_install').propagate = False
3872       
3873        >>> ws = zc.buildout.easy_install.install(
3874        ...     ['demo >0.2'], dest, links=[link_server],
3875        ...     index=link_server+'index/',
3876        ...     versions = dict(demo='0.2', demoneeded='1.0'))
3877        Traceback (most recent call last):
3878        ...
3879        IncompatibleVersionError: Bad version 0.2
3880       
3881        >>> print handler
3882        zc.buildout.easy_install DEBUG
3883        Installing 'demo >0.2'.
3884        zc.buildout.easy_install ERROR
3885        The version, 0.2, is not consistent with the requirement, 'demo>0.2'.
3886       
3887        >>> handler.clear()
3888       
3889        If no versions are specified, a debugging message will be output
3890        reporting that a version was picked automatically:
3891       
3892        >>> ws = zc.buildout.easy_install.install(
3893        ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
3894        ...     )
3895       
3896        >>> print handler
3897        zc.buildout.easy_install DEBUG
3898        Installing 'demo'.
3899        zc.buildout.easy_install DEBUG
3900        We have the best distribution that satisfies 'demo'.
3901        zc.buildout.easy_install DEBUG
3902        Picked: demo = 0.3
3903        zc.buildout.easy_install DEBUG
3904        Getting required 'demoneeded'
3905        zc.buildout.easy_install DEBUG
3906        required by demo 0.3.
3907        zc.buildout.easy_install DEBUG
3908        We have the best distribution that satisfies 'demoneeded'.
3909        zc.buildout.easy_install DEBUG
3910        Picked: demoneeded = 1.1
3911       
3912        >>> handler.uninstall()
3913        >>> logging.getLogger('zc.buildout.easy_install').propagate = True
3914       
3915        We can request that we get an error if versions are picked:
3916       
3917        >>> zc.buildout.easy_install.allow_picked_versions(False)
3918        True
3919       
3920        (The old setting is returned.)
3921       
3922        >>> ws = zc.buildout.easy_install.install(
3923        ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
3924        ...     )
3925        Traceback (most recent call last):
3926        ...
3927        UserError: Picked: demo = 0.3
3928       
3929        >>> zc.buildout.easy_install.allow_picked_versions(True)
3930        False
3931       
3932        The function default_versions can be used to get and set default
3933        version information to be used when no version information is passes.
3934        If called with an argument, it sets the default versions:
3935       
3936        >>> zc.buildout.easy_install.default_versions(dict(demoneeded='1'))
3937        {}
3938       
3939        It always returns the previous default versions.  If called without an
3940        argument, it simply returns the default versions without changing
3941        them:
3942       
3943        >>> zc.buildout.easy_install.default_versions()
3944        {'demoneeded': '1'}
3945       
3946        So with the default versions set, we'll get the requested version even
3947        if the versions option isn't used:
3948       
3949        >>> ws = zc.buildout.easy_install.install(
3950        ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
3951        ...     )
3952       
3953        >>> [d.version for d in ws]
3954        ['0.3', '1.0']
3955       
3956        Of course, we can unset the default versions by passing an empty
3957        dictionary:
3958       
3959        >>> zc.buildout.easy_install.default_versions({})
3960        {'demoneeded': '1'}
3961       
3962        >>> ws = zc.buildout.easy_install.install(
3963        ...     ['demo'], dest, links=[link_server], index=link_server+'index/',
3964        ...     )
3965       
3966        >>> [d.version for d in ws]
3967        ['0.3', '1.1']
3968       
3969        Dependency links
3970        ----------------
3971       
3972        Setuptools allows metadata that describes where to search for package
3973        dependencies. This option is called dependency_links. Buildout has its
3974        own notion of where to look for dependencies, but it also uses the
3975        setup tools dependency_links information if it's available.
3976       
3977        Let's demo this by creating an egg that specifies dependency_links.
3978       
3979        To begin, let's create a new egg repository. This repository hold a
3980        newer version of the 'demoneeded' egg than the sample repository does.
3981       
3982        >>> repoloc = tmpdir('repo')
3983        >>> from zc.buildout.tests import create_egg
3984        >>> create_egg('demoneeded', '1.2', repoloc)
3985        >>> link_server2 = start_server(repoloc)
3986       
3987        Turn on logging on this server so that we can see when eggs are pulled
3988        from it.
3989       
3990        >>> get(link_server2 + 'enable_server_logging')
3991        GET 200 /enable_server_logging
3992        ''
3993       
3994        Now we can create an egg that specifies that its dependencies are
3995        found on this server.
3996       
3997        >>> repoloc = tmpdir('repo2')
3998        >>> create_egg('hasdeps', '1.0', repoloc,
3999        ...            install_requires = "'demoneeded'",
4000        ...            dependency_links = [link_server2])
4001       
4002        Let's add the egg to another repository.
4003       
4004        >>> link_server3 = start_server(repoloc)
4005       
4006        Now let's install the egg.
4007       
4008        >>> example_dest = tmpdir('example-install')
4009        >>> workingset = zc.buildout.easy_install.install(
4010        ...     ['hasdeps'], example_dest,
4011        ...     links=[link_server3], index=link_server3+'index/')
4012        GET 200 /
4013        GET 200 /demoneeded-1.2-pyN.N.egg
4014       
4015        The server logs show that the dependency was retrieved from the server
4016        specified in the dependency_links.
4017       
4018        Now let's see what happens if we provide two different ways to retrieve
4019        the dependencies.
4020       
4021        >>> rmdir(example_dest)
4022        >>> example_dest = tmpdir('example-install')
4023        >>> workingset = zc.buildout.easy_install.install(
4024        ...     ['hasdeps'], example_dest, index=link_server+'index/',
4025        ...     links=[link_server, link_server3])
4026        GET 200 /
4027        GET 200 /demoneeded-1.2-pyN.N.egg
4028       
4029        Once again the dependency is fetched from the logging server even
4030        though it is also available from the non-logging server. This is
4031        because the version on the logging server is newer and buildout
4032        normally chooses the newest egg available.
4033       
4034        If you wish to control where dependencies come from regardless of
4035        dependency_links setup metadata use the 'use_dependency_links' option
4036        to zc.buildout.easy_install.install().
4037       
4038        >>> rmdir(example_dest)
4039        >>> example_dest = tmpdir('example-install')
4040        >>> workingset = zc.buildout.easy_install.install(
4041        ...     ['hasdeps'], example_dest, index=link_server+'index/',
4042        ...     links=[link_server, link_server3],
4043        ...     use_dependency_links=False)
4044       
4045        Notice that this time the dependency egg is not fetched from the
4046        logging server. When you specify not to use dependency_links, eggs
4047        will only be searched for using the links you explicitly provide.
4048       
4049        Another way to control this option is with the
4050        zc.buildout.easy_install.use_dependency_links() function. This
4051        function sets the default behavior for the zc.buildout.easy_install()
4052        function.
4053       
4054        >>> zc.buildout.easy_install.use_dependency_links(False)
4055        True
4056       
4057        The function returns its previous setting.
4058       
4059        >>> rmdir(example_dest)
4060        >>> example_dest = tmpdir('example-install')
4061        >>> workingset = zc.buildout.easy_install.install(
4062        ...     ['hasdeps'], example_dest, index=link_server+'index/',
4063        ...     links=[link_server, link_server3])
4064       
4065        It can be overridden by passing a keyword argument to the install
4066        function.
4067       
4068        >>> rmdir(example_dest)
4069        >>> example_dest = tmpdir('example-install')
4070        >>> workingset = zc.buildout.easy_install.install(
4071        ...     ['hasdeps'], example_dest, index=link_server+'index/',
4072        ...     links=[link_server, link_server3],
4073        ...         use_dependency_links=True)
4074        GET 200 /demoneeded-1.2-pyN.N.egg
4075       
4076        To return the dependency_links behavior to normal call the function again.
4077       
4078        >>> zc.buildout.easy_install.use_dependency_links(True)
4079        False
4080        >>> rmdir(example_dest)
4081        >>> example_dest = tmpdir('example-install')
4082        >>> workingset = zc.buildout.easy_install.install(
4083        ...     ['hasdeps'], example_dest, index=link_server+'index/',
4084        ...     links=[link_server, link_server3])
4085        GET 200 /demoneeded-1.2-pyN.N.egg
4086       
4087       
4088        Script generation
4089        -----------------
4090       
4091        The easy_install module provides support for creating scripts from
4092        eggs.  It provides a function similar to setuptools except that it
4093        provides facilities for baking a script's path into the script.  This
4094        has two advantages:
4095       
4096        - The eggs to be used by a script are not chosen at run time, making
4097        startup faster and, more importantly, deterministic.
4098       
4099        - The script doesn't have to import pkg_resources because the logic
4100        that pkg_resources would execute at run time is executed at
4101        script-creation time.
4102       
4103        The scripts method can be used to generate scripts. Let's create a
4104        destination directory for it to place them in:
4105       
4106        >>> import tempfile
4107        >>> bin = tmpdir('bin')
4108       
4109        Now, we'll use the scripts method to generate scripts in this directory
4110        from the demo egg:
4111       
4112        >>> import sys
4113        >>> scripts = zc.buildout.easy_install.scripts(
4114        ...     ['demo'], ws, sys.executable, bin)
4115       
4116        the four arguments we passed were:
4117       
4118        1. A sequence of distribution requirements.  These are of the same
4119        form as setuptools requirements.  Here we passed a single
4120        requirement, for the version 0.1 demo distribution.
4121       
4122        2. A working set,
4123       
4124        3. The Python executable to use, and
4125       
4126        3. The destination directory.
4127       
4128        The bin directory now contains a generated script:
4129       
4130        >>> ls(bin)
4131        -  demo
4132       
4133        The return value is a list of the scripts generated:
4134       
4135        >>> import os, sys
4136        >>> if sys.platform == 'win32':
4137        ...     scripts == [os.path.join(bin, 'demo.exe'),
4138        ...                 os.path.join(bin, 'demo-script.py')]
4139        ... else:
4140        ...     scripts == [os.path.join(bin, 'demo')]
4141        True
4142       
4143        Note that in Windows, 2 files are generated for each script.  A script
4144        file, ending in '-script.py', and an exe file that allows the script
4145        to be invoked directly without having to specify the Python
4146        interpreter and without having to provide a '.py' suffix.
4147       
4148        The demo script run the entry point defined in the demo egg:
4149       
4150        >>> cat(bin, 'demo') # doctest: +NORMALIZE_WHITESPACE
4151        #!/usr/local/bin/python2.4
4152        <BLANKLINE>
4153        import sys
4154        sys.path[0:0] = [
4155        '/sample-install/demo-0.3-py2.4.egg',
4156        '/sample-install/demoneeded-1.1-py2.4.egg',
4157        ]
4158        <BLANKLINE>
4159        import eggrecipedemo
4160        <BLANKLINE>
4161        if __name__ == '__main__':
4162        eggrecipedemo.main()
4163       
4164        Some things to note:
4165       
4166        - The demo and demoneeded eggs are added to the beginning of sys.path.
4167       
4168        - The module for the script entry point is imported and the entry
4169        point, in this case, 'main', is run.
4170       
4171        Rather than requirement strings, you can pass tuples containing 3
4172        strings:
4173       
4174        - A script name,
4175       
4176        - A module,
4177       
4178        - An attribute expression for an entry point within the module.
4179       
4180        For example, we could have passed entry point information directly
4181        rather than passing a requirement:
4182       
4183        >>> scripts = zc.buildout.easy_install.scripts(
4184        ...     [('demo', 'eggrecipedemo', 'main')],
4185        ...     ws, sys.executable, bin)
4186       
4187        >>> cat(bin, 'demo') # doctest: +NORMALIZE_WHITESPACE
4188        #!/usr/local/bin/python2.4
4189        <BLANKLINE>
4190        import sys
4191        sys.path[0:0] = [
4192        '/sample-install/demo-0.3-py2.4.egg',
4193        '/sample-install/demoneeded-1.1-py2.4.egg',
4194        ]
4195        <BLANKLINE>
4196        import eggrecipedemo
4197        <BLANKLINE>
4198        if __name__ == '__main__':
4199        eggrecipedemo.main()
4200       
4201        Passing entry-point information directly is handy when using eggs (or
4202        distributions) that don't declare their entry points, such as
4203        distributions that aren't based on setuptools.
4204       
4205        The interpreter keyword argument can be used to generate a script that can
4206        be used to invoke the Python interactive interpreter with the path set
4207        based on the working set.  This generated script can also be used to
4208        run other scripts with the path set on the working set:
4209       
4210        >>> scripts = zc.buildout.easy_install.scripts(
4211        ...     ['demo'], ws, sys.executable, bin, interpreter='py')
4212       
4213       
4214        >>> ls(bin)
4215        -  demo
4216        -  py
4217       
4218        >>> if sys.platform == 'win32':
4219        ...     scripts == [os.path.join(bin, 'demo.exe'),
4220        ...                 os.path.join(bin, 'demo-script.py'),
4221        ...                 os.path.join(bin, 'py.exe'),
4222        ...                 os.path.join(bin, 'py-script.py')]
4223        ... else:
4224        ...     scripts == [os.path.join(bin, 'demo'),
4225        ...                 os.path.join(bin, 'py')]
4226        True
4227       
4228        The py script simply runs the Python interactive interpreter with
4229        the path set:
4230       
4231        >>> cat(bin, 'py') # doctest: +NORMALIZE_WHITESPACE
4232        #!/usr/local/bin/python2.4
4233        import sys
4234        <BLANKLINE>
4235        sys.path[0:0] = [
4236        '/sample-install/demo-0.3-py2.4.egg',
4237        '/sample-install/demoneeded-1.1-py2.4.egg',
4238        ]
4239        <BLANKLINE>
4240        _interactive = True
4241        if len(sys.argv) > 1:
4242        import getopt
4243        _options, _args = getopt.getopt(sys.argv[1:], 'ic:')
4244        _interactive = False
4245        for (_opt, _val) in _options:
4246        if _opt == '-i':
4247        _interactive = True
4248        elif _opt == '-c':
4249        exec _val
4250        <BLANKLINE>
4251        if _args:
4252        sys.argv[:] = _args
4253        execfile(sys.argv[0])
4254        <BLANKLINE>
4255        if _interactive:
4256        import code
4257        code.interact(banner="", local=globals())
4258       
4259        If invoked with a script name and arguments, it will run that script, instead.
4260       
4261        An additional argument can be passed to define which scripts to install
4262        and to provide script names. The argument is a dictionary mapping
4263        original script names to new script names.
4264       
4265        >>> bin = tmpdir('bin2')
4266        >>> scripts = zc.buildout.easy_install.scripts(
4267        ...    ['demo'], ws, sys.executable, bin, dict(demo='run'))
4268       
4269        >>> if sys.platform == 'win32':
4270        ...     scripts == [os.path.join(bin, 'run.exe'),
4271        ...                 os.path.join(bin, 'run-script.py')]
4272        ... else:
4273        ...     scripts == [os.path.join(bin, 'run')]
4274        True
4275        >>> ls(bin)
4276        -  run
4277       
4278        >>> print system(os.path.join(bin, 'run')),
4279        3 1
4280       
4281        Including extra paths in scripts
4282        --------------------------------
4283       
4284        We can pass a keyword argument, extra paths, to cause additional paths
4285        to be included in the a generated script:
4286       
4287        >>> scripts = zc.buildout.easy_install.scripts(
4288        ...    ['demo'], ws, sys.executable, bin, dict(demo='run'),
4289        ...    extra_paths=['/foo/bar'])
4290       
4291        >>> cat(bin, 'run') # doctest: +NORMALIZE_WHITESPACE
4292        #!/usr/local/bin/python2.4
4293        <BLANKLINE>
4294        import sys
4295        sys.path[0:0] = [
4296        '/sample-install/demo-0.3-py2.4.egg',
4297        '/sample-install/demoneeded-1.1-py2.4.egg',
4298        '/foo/bar',
4299        ]
4300        <BLANKLINE>
4301        import eggrecipedemo
4302        <BLANKLINE>
4303        if __name__ == '__main__':
4304        eggrecipedemo.main()
4305       
4306        Providing script arguments
4307        --------------------------
4308       
4309        An "argument" keyword argument can be used to pass arguments to an
4310        entry point.  The value passed is a source string to be placed between the
4311        parentheses in the call:
4312       
4313        >>> scripts = zc.buildout.easy_install.scripts(
4314        ...    ['demo'], ws, sys.executable, bin, dict(demo='run'),
4315        ...    arguments='1, 2')
4316       
4317        >>> cat(bin, 'run') # doctest: +NORMALIZE_WHITESPACE
4318        #!/usr/local/bin/python2.4
4319        import sys
4320        sys.path[0:0] = [
4321        '/sample-install/demo-0.3-py2.4.egg',
4322        '/sample-install/demoneeded-1.1-py2.4.egg',
4323        ]
4324        <BLANKLINE>
4325        import eggrecipedemo
4326        <BLANKLINE>
4327        if __name__ == '__main__':
4328        eggrecipedemo.main(1, 2)
4329       
4330        Passing initialization code
4331        ---------------------------
4332       
4333        You can also pass script initialization code:
4334       
4335        >>> scripts = zc.buildout.easy_install.scripts(
4336        ...    ['demo'], ws, sys.executable, bin, dict(demo='run'),
4337        ...    arguments='1, 2',
4338        ...    initialization='import os\nos.chdir("foo")')
4339       
4340        >>> cat(bin, 'run') # doctest: +NORMALIZE_WHITESPACE
4341        #!/usr/local/bin/python2.4
4342        import sys
4343        sys.path[0:0] = [
4344        '/sample-install/demo-0.3-py2.4.egg',
4345        '/sample-install/demoneeded-1.1-py2.4.egg',
4346        ]
4347        <BLANKLINE>
4348        import os
4349        os.chdir("foo")
4350        <BLANKLINE>
4351        import eggrecipedemo
4352        <BLANKLINE>
4353        if __name__ == '__main__':
4354        eggrecipedemo.main(1, 2)
4355       
4356        Relative paths
4357        --------------
4358       
4359        Sometimes, you want to be able to move a buildout directory around and
4360        have scripts still work without having to rebuild them.  We can
4361        control this using the relative_paths option to install.  You need
4362        to pass a common base directory of the scripts and eggs:
4363       
4364        >>> bo = tmpdir('bo')
4365        >>> mkdir(bo, 'eggs')
4366        >>> mkdir(bo, 'bin')
4367        >>> mkdir(bo, 'other')
4368       
4369        >>> ws = zc.buildout.easy_install.install(
4370        ...     ['demo'], join(bo, 'eggs'), links=[link_server],
4371        ...     index=link_server+'index/')
4372       
4373        >>> scripts = zc.buildout.easy_install.scripts(
4374        ...    ['demo'], ws, sys.executable, join(bo, 'bin'), dict(demo='run'),
4375        ...    extra_paths=[os.path.sep+'foo', join(bo, 'bar')],
4376        ...    interpreter='py',
4377        ...    relative_paths=bo)
4378       
4379        >>> cat(bo, 'bin', 'run')
4380        #!/usr/local/bin/python2.4
4381        <BLANKLINE>
4382        import os
4383        <BLANKLINE>
4384        join = os.path.join
4385        base = os.path.dirname(__file__)
4386        base = os.path.dirname(base)
4387        <BLANKLINE>
4388        import sys
4389        sys.path[0:0] = [
4390        join(base, 'eggs/demo-0.3-pyN.N.egg'),
4391        join(base, 'eggs/demoneeded-1.1-pyN.N.egg'),
4392        '/foo',
4393        join(base, 'bar'),
4394        ]
4395        <BLANKLINE>
4396        import eggrecipedemo
4397        <BLANKLINE>
4398        if __name__ == '__main__':
4399        eggrecipedemo.main()
4400       
4401        Note that the extra path we specified that was outside the directory
4402        passed as relative_paths wasn't converted to a relative path.
4403       
4404        Of course, running the script works:
4405       
4406        >>> print system(join(bo, 'bin', 'run')),
4407        3 1
4408       
4409        We specified an interpreter and its paths are adjusted too:
4410       
4411        >>> cat(bo, 'bin', 'py')
4412        #!/usr/local/bin/python2.4
4413        <BLANKLINE>
4414        import os
4415        <BLANKLINE>
4416        join = os.path.join
4417        base = os.path.dirname(__file__)
4418        base = os.path.dirname(base)
4419        <BLANKLINE>
4420        import sys
4421        <BLANKLINE>
4422        sys.path[0:0] = [
4423        join(base, 'eggs/demo-0.3-pyN.N.egg'),
4424        join(base, 'eggs/demoneeded-1.1-pyN.N.egg'),
4425        '/foo',
4426        join(base, 'bar'),
4427        ]
4428        <BLANKLINE>
4429        _interactive = True
4430        if len(sys.argv) > 1:
4431        import getopt
4432        _options, _args = getopt.getopt(sys.argv[1:], 'ic:')
4433        _interactive = False
4434        for (_opt, _val) in _options:
4435        if _opt == '-i':
4436        _interactive = True
4437        elif _opt == '-c':
4438        exec _val
4439        <BLANKLINE>
4440        if _args:
4441        sys.argv[:] = _args
4442        execfile(sys.argv[0])
4443        <BLANKLINE>
4444        if _interactive:
4445        import code
4446        code.interact(banner="", local=globals())
4447       
4448       
4449        Handling custom build options for extensions provided in source distributions
4450        -----------------------------------------------------------------------------
4451       
4452        Sometimes, we need to control how extension modules are built.  The
4453        build function provides this level of control.  It takes a single
4454        package specification, downloads a source distribution, and builds it
4455        with specified custom build options.
4456       
4457        The build function takes 3 positional arguments:
4458       
4459        spec
4460        A package specification for a source distribution
4461       
4462        dest
4463        A destination directory
4464       
4465        build_ext
4466        A dictionary of options to be passed to the distutils build_ext
4467        command when building extensions.
4468       
4469        It supports a number of optional keyword arguments:
4470       
4471        links
4472        a sequence of URLs, file names, or directories to look for
4473        links to distributions,
4474       
4475        index
4476        The URL of an index server, or almost any other valid URL. :)
4477       
4478        If not specified, the Python Package Index,
4479        http://pypi.python.org/simple/, is used.  You can specify an
4480        alternate index with this option.  If you use the links option and
4481        if the links point to the needed distributions, then the index can
4482        be anything and will be largely ignored.  In the examples, here,
4483        we'll just point to an empty directory on our link server.  This
4484        will make our examples run a little bit faster.
4485       
4486        executable
4487        A path to a Python executable.  Distributions will be installed
4488        using this executable and will be for the matching Python version.
4489       
4490        path
4491        A list of additional directories to search for locally-installed
4492        distributions.
4493       
4494        newest
4495        A boolean value indicating whether to search for new distributions
4496        when already-installed distributions meet the requirement.  When
4497        this is true, the default, and when the destination directory is
4498        not None, then the install function will search for the newest
4499        distributions that satisfy the requirements.
4500       
4501        versions
4502        A dictionary mapping project names to version numbers to be used
4503        when selecting distributions.  This can be used to specify a set of
4504        distribution versions independent of other requirements.
4505       
4506       
4507        Our link server included a source distribution that includes a simple
4508        extension, extdemo.c::
4509       
4510        #include <Python.h>
4511        #include <extdemo.h>
4512       
4513        static PyMethodDef methods[] = {};
4514       
4515        PyMODINIT_FUNC
4516        initextdemo(void)
4517        {
4518        PyObject *m;
4519        m = Py_InitModule3("extdemo", methods, "");
4520        #ifdef TWO
4521        PyModule_AddObject(m, "val", PyInt_FromLong(2));
4522        #else
4523        PyModule_AddObject(m, "val", PyInt_FromLong(EXTDEMO));
4524        #endif
4525        }
4526       
4527        The extension depends on a system-dependent include file, extdemo.h,
4528        that defines a constant, EXTDEMO, that is exposed by the extension.
4529       
4530        We'll add an include directory to our sample buildout and add the
4531        needed include file to it:
4532       
4533        >>> mkdir('include')
4534        >>> write('include', 'extdemo.h',
4535        ... """
4536        ... #define EXTDEMO 42
4537        ... """)
4538       
4539        Now, we can use the build function to create an egg from the source
4540        distribution:
4541       
4542        >>> zc.buildout.easy_install.build(
4543        ...   'extdemo', dest,
4544        ...   {'include-dirs': os.path.join(sample_buildout, 'include')},
4545        ...   links=[link_server], index=link_server+'index/')
4546        ['/sample-install/extdemo-1.4-py2.4-unix-i686.egg']
4547       
4548        The function returns the list of eggs
4549       
4550        Now if we look in our destination directory, we see we have an extdemo egg:
4551       
4552        >>> ls(dest)
4553        -  demo-0.2-py2.4.egg
4554        d  demo-0.3-py2.4.egg
4555        -  demoneeded-1.0-py2.4.egg
4556        d  demoneeded-1.1-py2.4.egg
4557        d  extdemo-1.4-py2.4-unix-i686.egg
4558       
4559        Let's update our link server with a new version of extdemo:
4560       
4561        >>> update_extdemo()
4562        >>> print get(link_server),
4563        <html><body>
4564        <a href="bigdemo-0.1-py2.4.egg">bigdemo-0.1-py2.4.egg</a><br>
4565        <a href="demo-0.1-py2.4.egg">demo-0.1-py2.4.egg</a><br>
4566        <a href="demo-0.2-py2.4.egg">demo-0.2-py2.4.egg</a><br>
4567        <a href="demo-0.3-py2.4.egg">demo-0.3-py2.4.egg</a><br>
4568        <a href="demo-0.4c1-py2.4.egg">demo-0.4c1-py2.4.egg</a><br>
4569        <a href="demoneeded-1.0.zip">demoneeded-1.0.zip</a><br>
4570        <a href="demoneeded-1.1.zip">demoneeded-1.1.zip</a><br>
4571        <a href="demoneeded-1.2c1.zip">demoneeded-1.2c1.zip</a><br>
4572        <a href="extdemo-1.4.zip">extdemo-1.4.zip</a><br>
4573        <a href="extdemo-1.5.zip">extdemo-1.5.zip</a><br>
4574        <a href="index/">index/</a><br>
4575        <a href="other-1.0-py2.4.egg">other-1.0-py2.4.egg</a><br>
4576        </body></html>
4577       
4578        The easy_install caches information about servers to reduce network
4579        access. To see the update, we have to call the clear_index_cache
4580        function to clear the index cache:
4581       
4582        >>> zc.buildout.easy_install.clear_index_cache()
4583       
4584        If we run build with newest set to False, we won't get an update:
4585       
4586        >>> zc.buildout.easy_install.build(
4587        ...   'extdemo', dest,
4588        ...   {'include-dirs': os.path.join(sample_buildout, 'include')},
4589        ...   links=[link_server], index=link_server+'index/',
4590        ...   newest=False)
4591        ['/sample-install/extdemo-1.4-py2.4-linux-i686.egg']
4592       
4593        >>> ls(dest)
4594        -  demo-0.2-py2.4.egg
4595        d  demo-0.3-py2.4.egg
4596        -  demoneeded-1.0-py2.4.egg
4597        d  demoneeded-1.1-py2.4.egg
4598        d  extdemo-1.4-py2.4-unix-i686.egg
4599       
4600        But if we run it with the default True setting for newest, then we'll
4601        get an updated egg:
4602       
4603        >>> zc.buildout.easy_install.build(
4604        ...   'extdemo', dest,
4605        ...   {'include-dirs': os.path.join(sample_buildout, 'include')},
4606        ...   links=[link_server], index=link_server+'index/')
4607        ['/sample-install/extdemo-1.5-py2.4-unix-i686.egg']
4608       
4609        >>> ls(dest)
4610        -  demo-0.2-py2.4.egg
4611        d  demo-0.3-py2.4.egg
4612        -  demoneeded-1.0-py2.4.egg
4613        d  demoneeded-1.1-py2.4.egg
4614        d  extdemo-1.4-py2.4-unix-i686.egg
4615        d  extdemo-1.5-py2.4-unix-i686.egg
4616       
4617        The versions option also influences the versions used.  For example,
4618        if we specify a version for extdemo, then that will be used, even
4619        though it isn't the newest.  Let's clean out the destination directory
4620        first:
4621       
4622        >>> import os
4623        >>> for name in os.listdir(dest):
4624        ...     remove(dest, name)
4625       
4626        >>> zc.buildout.easy_install.build(
4627        ...   'extdemo', dest,
4628        ...   {'include-dirs': os.path.join(sample_buildout, 'include')},
4629        ...   links=[link_server], index=link_server+'index/',
4630        ...   versions=dict(extdemo='1.4'))
4631        ['/sample-install/extdemo-1.4-py2.4-unix-i686.egg']
4632       
4633        >>> ls(dest)
4634        d  extdemo-1.4-py2.4-unix-i686.egg
4635       
4636        Handling custom build options for extensions in develop eggs
4637        ------------------------------------------------------------
4638       
4639        The develop function is similar to the build function, except that,
4640        rather than building an egg from a source directory containing a
4641        setup.py script.
4642       
4643        The develop function takes 2 positional arguments:
4644       
4645        setup
4646        The path to a setup script, typically named "setup.py", or a
4647        directory containing a setup.py script.
4648       
4649        dest
4650        The directory to install the egg link to
4651       
4652        It supports some optional keyword argument:
4653       
4654        build_ext
4655        A dictionary of options to be passed to the distutils build_ext
4656        command when building extensions.
4657       
4658        executable
4659        A path to a Python executable.  Distributions will be installed
4660        using this executable and will be for the matching Python version.
4661       
4662        We have a local directory containing the extdemo source:
4663       
4664        >>> ls(extdemo)
4665        -  MANIFEST
4666        -  MANIFEST.in
4667        -  README
4668        -  extdemo.c
4669        -  setup.py
4670       
4671        Now, we can use the develop function to create a develop egg from the source
4672        distribution:
4673       
4674        >>> zc.buildout.easy_install.develop(
4675        ...   extdemo, dest,
4676        ...   {'include-dirs': os.path.join(sample_buildout, 'include')})
4677        '/sample-install/extdemo.egg-link'
4678       
4679        The name of the egg link created is returned.
4680       
4681        Now if we look in our destination directory, we see we have an extdemo
4682        egg link:
4683       
4684        >>> ls(dest)
4685        d  extdemo-1.4-py2.4-unix-i686.egg
4686        -  extdemo.egg-link
4687       
4688        And that the source directory contains the compiled extension:
4689       
4690        >>> ls(extdemo)
4691        -  MANIFEST
4692        -  MANIFEST.in
4693        -  README
4694        d  build
4695        -  extdemo.c
4696        d  extdemo.egg-info
4697        -  extdemo.so
4698        -  setup.py
4699       
4700        Download cache
4701        --------------
4702       
4703        Normally, when distributions are installed, if any processing is
4704        needed, they are downloaded from the internet to a temporary directory
4705        and then installed from there.  A download cache can be used to avoid
4706        the download step.  This can be useful to reduce network access and to
4707        create source distributions of an entire buildout.
4708       
4709        A download cache is specified by calling the download_cache
4710        function.  The function always returns the previous setting. If no
4711        argument is passed, then the setting is unchanged.  If an argument is
4712        passed, the download cache is set to the given path, which must point
4713        to an existing directory.  Passing None clears the cache setting.
4714       
4715        To see this work, we'll create a directory and set it as the cache
4716        directory:
4717       
4718        >>> cache = tmpdir('cache')
4719        >>> zc.buildout.easy_install.download_cache(cache)
4720       
4721        We'll recreate our destination directory:
4722       
4723        >>> remove(dest)
4724        >>> dest = tmpdir('sample-install')
4725       
4726        We'd like to see what is being fetched from the server, so we'll
4727        enable server logging:
4728       
4729        >>> get(link_server+'enable_server_logging')
4730        GET 200 /enable_server_logging
4731        ''
4732       
4733        Now, if we install demo, and extdemo:
4734       
4735        >>> ws = zc.buildout.easy_install.install(
4736        ...     ['demo==0.2'], dest,
4737        ...     links=[link_server], index=link_server+'index/',
4738        ...     always_unzip=True)
4739        GET 200 /
4740        GET 404 /index/demo/
4741        GET 200 /index/
4742        GET 200 /demo-0.2-py2.4.egg
4743        GET 404 /index/demoneeded/
4744        GET 200 /demoneeded-1.1.zip
4745        GET 404 /index/setuptools/
4746       
4747        >>> zc.buildout.easy_install.build(
4748        ...   'extdemo', dest,
4749        ...   {'include-dirs': os.path.join(sample_buildout, 'include')},
4750        ...   links=[link_server], index=link_server+'index/')
4751        GET 404 /index/extdemo/
4752        GET 200 /extdemo-1.5.zip
4753        ['/sample-install/extdemo-1.5-py2.4-linux-i686.egg']
4754       
4755        Not only will we get eggs in our destination directory:
4756       
4757        >>> ls(dest)
4758        d  demo-0.2-py2.4.egg
4759        d  demoneeded-1.1-py2.4.egg
4760        d  extdemo-1.5-py2.4-linux-i686.egg
4761       
4762        But we'll get distributions in the cache directory:
4763       
4764        >>> ls(cache)
4765        -  demo-0.2-py2.4.egg
4766        -  demoneeded-1.1.zip
4767        -  extdemo-1.5.zip
4768       
4769        The cache directory contains uninstalled distributions, such as zipped
4770        eggs or source distributions.
4771       
4772        Let's recreate our destination directory and clear the index cache:
4773       
4774        >>> remove(dest)
4775        >>> dest = tmpdir('sample-install')
4776        >>> zc.buildout.easy_install.clear_index_cache()
4777       
4778        Now when we install the distributions:
4779       
4780        >>> ws = zc.buildout.easy_install.install(
4781        ...     ['demo==0.2'], dest,
4782        ...     links=[link_server], index=link_server+'index/',
4783        ...     always_unzip=True)
4784        GET 200 /
4785        GET 404 /index/demo/
4786        GET 200 /index/
4787        GET 404 /index/demoneeded/
4788        GET 404 /index/setuptools/
4789       
4790        >>> zc.buildout.easy_install.build(
4791        ...   'extdemo', dest,
4792        ...   {'include-dirs': os.path.join(sample_buildout, 'include')},
4793        ...   links=[link_server], index=link_server+'index/')
4794        GET 404 /index/extdemo/
4795        ['/sample-install/extdemo-1.5-py2.4-linux-i686.egg']
4796       
4797        >>> ls(dest)
4798        d  demo-0.2-py2.4.egg
4799        d  demoneeded-1.1-py2.4.egg
4800        d  extdemo-1.5-py2.4-linux-i686.egg
4801       
4802        Note that we didn't download the distributions from the link server.
4803       
4804        If we remove the restriction on demo, we'll download a newer version
4805        from the link server:
4806       
4807        >>> ws = zc.buildout.easy_install.install(
4808        ...     ['demo'], dest,
4809        ...     links=[link_server], index=link_server+'index/',
4810        ...     always_unzip=True)
4811        GET 200 /demo-0.3-py2.4.egg
4812       
4813        Normally, the download cache is the preferred source of downloads, but
4814        not the only one.
4815       
4816        Installing solely from a download cache
4817        ---------------------------------------
4818       
4819        A download cache can be used as the basis of application source
4820        releases.  In an application source release, we want to distribute an
4821        application that can be built without making any network accesses.  In
4822        this case, we distribute a download cache and tell the easy_install
4823        module to install from the download cache only, without making network
4824        accesses.  The install_from_cache function can be used to signal that
4825        packages should be installed only from the download cache.  The
4826        function always returns the previous setting.  Calling it with no
4827        arguments returns the current setting without changing it:
4828       
4829        >>> zc.buildout.easy_install.install_from_cache()
4830        False
4831       
4832        Calling it with a boolean value changes the setting and returns the
4833        previous setting:
4834       
4835        >>> zc.buildout.easy_install.install_from_cache(True)
4836        False
4837       
4838        Let's remove demo-0.3-py2.4.egg from the cache, clear the index cache,
4839        recreate the destination directory, and reinstall demo:
4840       
4841        >>> for  f in os.listdir(cache):
4842        ...     if f.startswith('demo-0.3-'):
4843        ...         remove(cache, f)
4844       
4845        >>> zc.buildout.easy_install.clear_index_cache()
4846        >>> remove(dest)
4847        >>> dest = tmpdir('sample-install')
4848       
4849        >>> ws = zc.buildout.easy_install.install(
4850        ...     ['demo'], dest,
4851        ...     links=[link_server], index=link_server+'index/',
4852        ...     always_unzip=True)
4853       
4854        >>> ls(dest)
4855        d  demo-0.2-py2.4.egg
4856        d  demoneeded-1.1-py2.4.egg
4857       
4858        This time, we didn't download from or even query the link server.
4859       
4860        .. Disable the download cache:
4861       
4862        >>> zc.buildout.easy_install.download_cache(None)
4863        '/cache'
4864       
4865        >>> zc.buildout.easy_install.install_from_cache(False)
4866        True
4867       
4868        Status
4869        ******
4870       
4871        Change History
4872        **************
4873       
4874        1.2.1 (2009-03-18)
4875        ==================
4876       
4877        - Refactored generation of relative egg paths to generate simpler code.
4878       
4879        1.2.0 (2009-03-17)
4880        ==================
4881       
4882        - Added a relative_paths option to zc.buildout.easy_install.script to
4883        generate egg paths relative to the script they're used in.
4884       
4885        1.1.2 (2009-03-16)
4886        ==================
4887       
4888        - Added Python 2.6 support. Removed Python 2.3 support.
4889       
4890        - Fixed remaining deprecation warnings under Python 2.6, both when running
4891        our tests and when using the package.
4892       
4893        - Switched from using os.popen* to subprocess.Popen, to avoid a deprecation
4894        warning in Python 2.6.  See:
4895       
4896        http://docs.python.org/library/subprocess.html#replacing-os-popen-os-popen2-os-popen3
4897       
4898        - Made sure the 'redo_pyc' function and the doctest checkers work with Python
4899        executable paths containing spaces.
4900       
4901        - Expand shell patterns when processing the list of paths in `develop`, e.g::
4902       
4903        [buildout]
4904        develop = ./local-checkouts/*
4905       
4906        - Conditionally import and use hashlib.md5 when it's available instead
4907        of md5 module, which is deprecated in Python 2.6.
4908       
4909        - Added Jython support for bootstrap, development bootstrap
4910        and zc.buildout support on Jython
4911       
4912        - Fixed a bug that would cause buildout to break while computing a
4913        directory hash if it found a broken symlink (Launchpad #250573)
4914       
4915        1.1.1 (2008-07-28)
4916        ==================
4917       
4918        - Fixed a bug that caused buildouts to fail when variable
4919        substitutions are used to name standard directories, as in::
4920       
4921        [buildout]
4922        eggs-directory = ${buildout:directory}/develop-eggs
4923       
4924        1.1.0 (2008-07-19)
4925        ==================
4926       
4927        - Added a buildout-level unzip option tp change the default policy for
4928        unzipping zip-safe eggs.
4929       
4930        - Tracebacks are now printed for internal errors (as opposed to user
4931        errors) even without the -D option.
4932       
4933        - pyc and pyo files are regenerated for installed eggs so that the
4934        stored path in code objects matches the the install location.
4935       
4936        1.0.6 (2008-06-13)
4937        ==================
4938       
4939        - Manually reverted the changeset for the fix for
4940        https://bugs.launchpad.net/zc.buildout/+bug/239212 to verify thet the test
4941        actually fails with the changeset:
4942        http://svn.zope.org/zc.buildout/trunk/src/zc/buildout/buildout.py?rev=87309&r1=87277&r2=87309
4943        Thanks tarek for pointing this out. (seletz)
4944       
4945        - fixed the test for the += -= syntax in buildout.txt as the test
4946        was actually wronng. The original implementation did a split/join
4947        on whitespace, and later on that was corrected to respect the original
4948        EOL setting, the test was not updated, though. (seletz)
4949       
4950        - added a test to verify against https://bugs.launchpad.net/zc.buildout/+bug/239212
4951        in allowhosts.txt (seletz)
4952       
4953        - further fixes for """AttributeError: Buildout instance has no
4954        attribute '_logger'""" by providing reasonable defaults
4955        within the Buildout constructor (related to the new 'allow-hosts' option)
4956        (patch by Gottfried Ganssauge) (ajung)
4957       
4958       
4959        1.0.5 (2008-06-10)
4960        ==================
4961       
4962        - Fixed wrong split when using the += and -= syntax (mustapha)
4963       
4964        1.0.4 (2008-06-10)
4965        ==================
4966       
4967        - Added the `allow-hosts` option (tarek)
4968       
4969        - Quote the 'executable' argument when trying to detect the python
4970        version using popen4. (sidnei)
4971       
4972        - Quote the 'spec' argument, as in the case of installing an egg from
4973        the buildout-cache, if the filename contains spaces it would fail (sidnei)
4974       
4975        - Extended configuration syntax to allow -= and += operators (malthe, mustapha).
4976       
4977        1.0.3 (2008-06-01)
4978        ==================
4979       
4980        - fix for """AttributeError: Buildout instance has no attribute '_logger'"""
4981        by providing reasonable defaults within the Buildout constructor.
4982        (patch by Gottfried Ganssauge) (ajung)
4983       
4984        1.0.2 (2008-05-13)
4985        ==================
4986       
4987        - More fixes for Windows. A quoted sh-bang is now used on Windows to make the
4988        .exe files work with a Python executable in 'program files'.
4989       
4990        - Added "-t <timeout_in_seconds>" option for specifying the socket timeout.
4991        (ajung)
4992       
4993        1.0.1 (2008-04-02)
4994        ==================
4995       
4996        - Made easy_install.py's _get_version accept non-final releases of Python,
4997        like 2.4.4c0. (hannosch)
4998       
4999        - Applied various patches for Windows (patch by Gottfried Ganssauge). (ajung)
5000       
5001        - Applied patch fixing rmtree issues on Windows (patch by
5002        Gottfried Ganssauge).  (ajung)
5003       
5004        1.0.0 (2008-01-13)
5005        ==================
5006       
5007        - Added a French translation of the buildout tutorial.
5008       
5009        1.0.0b31 (2007-11-01)
5010        =====================
5011       
5012        Feature Changes
5013        ---------------
5014       
5015        - Added a configuration option that allows buildouts to ignore
5016        dependency_links metadata specified in setup. By default
5017        dependency_links in setup are used in addition to buildout specified
5018        find-links. This can make it hard to control where eggs come
5019        from. Here's how to tell buildout to ignore URLs in
5020        dependency_links::
5021       
5022        [buildout]
5023        use-dependency-links = false
5024       
5025        By default use-dependency-links is true, which matches the behavior
5026        of previous versions of buildout.
5027       
5028        - Added a configuration option that causes buildout to error if a
5029        version is picked. This is a nice safety belt when fixing all
5030        versions is intended, especially when creating releases.
5031       
5032        Bugs Fixed
5033        ----------
5034       
5035        - 151820: Develop failed if the setup.py script imported modules in
5036        the distribution directory.
5037       
5038        - Verbose logging of the develop command was omitting detailed
5039        output.
5040       
5041        - The setup command wasn't documented.
5042       
5043        - The setup command failed if run in a directory without specifying a
5044        configuration file.
5045       
5046        - The setup command raised a stupid exception if run without arguments.
5047       
5048        - When using a local find links or index, distributions weren't copied
5049        to the download cache.
5050       
5051        - When installing from source releases, a version specification (via a
5052        buildout versions section) for setuptools was ignored when deciding
5053        which setuptools to use to build an egg from the source release.
5054       
5055        1.0.0b30 (2007-08-20)
5056        =====================
5057       
5058        Feature Changes
5059        ---------------
5060       
5061        - Changed the default policy back to what it was to avoid breakage in
5062        existing buildouts.  Use::
5063       
5064        [buildout]
5065        prefer-final = true
5066       
5067        to get the new policy.  The new policy will go into effect in
5068        buildout 2.
5069       
5070        1.0.0b29 (2007-08-20)
5071        =====================
5072       
5073        Feature Changes
5074        ---------------
5075       
5076        - Now, final distributions are prefered over non-final versions.  If
5077        both final and non-final versions satisfy a requirement, then the
5078        final version will be used even if it is older.  The normal way to
5079        override this for specific packages is to specifically require a
5080        non-final version, either specifically or via a lower bound.
5081       
5082        - There is a buildout prefer-final version that can be used with a
5083        value of "false"::
5084       
5085        prefer-final = false
5086       
5087        To prefer newer versions, regardless of whether or not they are
5088        final, buildout-wide.
5089       
5090        - The new simple Python index, http://cheeseshop.python.org/simple, is
5091        used as the default index.  This will provide better performance
5092        than the human package index interface,
5093        http://pypi.python.org/pypi. More importantly, it lists hidden
5094        distributions, so buildouts with fixed distribution versions will be
5095        able to find old distributions even if the distributions have been
5096        hidden in the human PyPI interface.
5097       
5098        Bugs Fixed
5099        ----------
5100       
5101        - 126441: Look for default.cfg in the right place on Windows.
5102       
5103        1.0.0b28 (2007-07-05)
5104        =====================
5105       
5106        Bugs Fixed
5107        ----------
5108       
5109        - When requiring a specific version, buildout looked for new versions
5110        even if that single version was already installed.
5111       
5112        1.0.0b27 (2007-06-20)
5113        =====================
5114       
5115        Bugs Fixed
5116        ----------
5117       
5118        - Scripts were generated incorrectly on Windows.  This included the
5119        buildout script itself, making buildout completely unusable.
5120       
5121        1.0.0b26 (2007-06-19)
5122        =====================
5123       
5124        Feature Changes
5125        ---------------
5126       
5127        - Thanks to recent fixes in setuptools, I was able to change buildout
5128        to use find-link and index information when searching extensions.
5129       
5130        Sadly, this work, especially the timing, was motivated my the need
5131        to use alternate indexes due to performance problems in the cheese
5132        shop (http://www.python.org/pypi/).  I really home we can address
5133        these performance problems soon.
5134       
5135        1.0.0b25 (2007-05-31)
5136        =====================
5137       
5138        Feature Changes
5139        ---------------
5140       
5141        - buildout now changes to the buildout directory before running recipe
5142        install and update methods.
5143       
5144        - Added a new init command for creating a new buildout. This creates
5145        an empty configuration file and then bootstraps.
5146       
5147        - Except when using the new init command, it is now an error to run
5148        buildout without a configuration file.
5149       
5150        - In verbose mode, when adding distributions to fulful requirements of
5151        already-added distributions, we now show why the new distributions
5152        are being added.
5153       
5154        - Changed the logging format to exclude the logger name for the
5155        zc.buildout logger.  This reduces noise in the output.
5156       
5157        - Clean up lots of messages, adding missing periods and adding quotes around
5158        requirement strings and file paths.
5159       
5160        Bugs Fixed
5161        ----------
5162       
5163        - 114614: Buildouts could take a very long time if there were
5164        dependency problems in large sets of pathologically interdependent
5165        packages.
5166       
5167        - 59270: Buggy recipes can cause failures in later recipes via chdir
5168       
5169        - 61890: file:// urls don't seem to work in find-links
5170       
5171        setuptools requires that file urls that point to directories must
5172        end in a "/".  Added a workaround.
5173       
5174        - 75607: buildout should not run if it creates an empty buildout.cfg
5175       
5176        1.0.0b24 (2007-05-09)
5177        =====================
5178       
5179        Feature Changes
5180        ---------------
5181       
5182        - Improved error reporting by showing which packages require other
5183        packages that can't be found or that cause version conflicts.
5184       
5185        - Added an API for use by recipe writers to clean up created files
5186        when recipe errors occur.
5187       
5188        - Log installed scripts.
5189       
5190        Bugs Fixed
5191        ----------
5192       
5193        - 92891: bootstrap crashes with recipe option in buildout section.
5194       
5195        - 113085: Buildout exited with a zero exist status when internal errors
5196        occured.
5197       
5198       
5199        1.0.0b23 (2007-03-19)
5200        =====================
5201       
5202        Feature Changes
5203        ---------------
5204       
5205        - Added support for download caches.  A buildout can specify a cache
5206        for distribution downloads.  The cache can be shared among buildouts
5207        to reduce network access and to support creating source
5208        distributions for applications allowing install without network
5209        access.
5210       
5211        - Log scripts created, as suggested in:
5212        https://bugs.launchpad.net/zc.buildout/+bug/71353
5213       
5214        Bugs Fixed
5215        ----------
5216       
5217        - It wasn't possible to give options on the command line for sections
5218        not defined in a configuration file.
5219       
5220        1.0.0b22 (2007-03-15)
5221        =====================
5222       
5223        Feature Changes
5224        ---------------
5225       
5226        - Improved error reporting and debugging support:
5227       
5228        - Added "logical tracebacks" that show functionally what the buildout
5229        was doing when an error occurs.  Don't show a Python traceback
5230        unless the -D option is used.
5231       
5232        - Added a -D option that causes the buildout to print a traceback and
5233        start the pdb post-mortem debugger when an error occurs.
5234       
5235        - Warnings are printed for unused options in the buildout section and
5236        installed-part sections.  This should make it easier to catch option
5237        misspellings.
5238       
5239        - Changed the way the installed database (.installed.cfg) is handled
5240        to avoid database corruption when a user breaks out of a buildout
5241        with control-c.
5242       
5243        - Don't save an installed database if there are no installed parts or
5244        develop egg links.
5245       
5246        1.0.0b21 (2007-03-06)
5247        =====================
5248       
5249        Feature Changes
5250        ---------------
5251       
5252        - Added support for repeatable buildouts by allowing egg versions to
5253        be specified in a versions section.
5254       
5255        - The easy_install module install and build functions now accept a
5256        versions argument that supplied to mapping from project name to
5257        version numbers.  This can be used to fix version numbers for
5258        required distributions and their depenencies.
5259       
5260        When a version isn't fixed, using either a versions option or using
5261        a fixed version number in a requirement, then a debug log message is
5262        emitted indicating the version picked.  This is useful for setting
5263        versions options.
5264       
5265        A default_versions function can be used to set a default value for
5266        this option.
5267       
5268        - Adjusted the output for verbosity levels.  Using a single -v option
5269        no longer causes voluminous setuptools output.  Uisng -vv and -vvv
5270        now triggers extra setuptools output.
5271       
5272        - Added a remove testing helper function that removes files or directories.
5273       
5274        1.0.0b20 (2007-02-08)
5275        =====================
5276       
5277        Feature Changes
5278        ---------------
5279       
5280        - Added a buildout newest option, to control whether the newest
5281        distributions should be sought to meet requirements.  This might
5282        also provide a hint to recipes that don't deal with
5283        distributions. For example, a recipe that manages subversion
5284        checkouts might not update a checkout if newest is set to "false".
5285       
5286        - Added a *newest* keyword parameter to the
5287        zc.buildout.easy_install.install and zc.buildout.easy_install.build
5288        functions to control whether the newest distributions that meed
5289        given requirements should be sought.  If a false value is provided
5290        for this parameter and already installed eggs meet the given
5291        requirements, then no attempt will be made to search for newer
5292        distributions.
5293       
5294        - The recipe-testing support setUp function now adds the name
5295        *buildout* to the test namespace with a value that is the path to
5296        the buildout script in the sample buildout.  This allows tests to
5297        use
5298       
5299        >>> print system(buildout),
5300       
5301        rather than:
5302       
5303        >>> print system(join('bin', 'buildout')),
5304       
5305       
5306        Bugs Fixed
5307        ----------
5308       
5309        - Paths returned from update methods replaced lists of installed files
5310        rather than augmenting them.
5311       
5312        1.0.0b19 (2007-01-24)
5313        =====================
5314       
5315        Bugs Fixed
5316        ----------
5317       
5318        - Explicitly specifying a Python executable failed if the output of
5319        running Python with the -V option included a 2-digit (rather than a
5320        3-digit) version number.
5321       
5322        1.0.0b18 (2007-01-22)
5323        =====================
5324       
5325        Feature Changes
5326        ---------------
5327       
5328        - Added documentation for some previously undocumented features of the
5329        easy_install APIs.
5330       
5331        - By popular demand, added a -o command-line option that is a short
5332        hand for the assignment buildout:offline=true.
5333       
5334        Bugs Fixed
5335        ----------
5336       
5337        - When deciding whether recipe develop eggs had changed, buildout
5338        incorrectly considered files in .svn and CVS directories.
5339       
5340        1.0.0b17 (2006-12-07)
5341        =====================
5342       
5343        Feature Changes
5344        ---------------
5345       
5346        - Configuration files can now be loaded from URLs.
5347       
5348        Bugs Fixed
5349        ----------
5350       
5351        - https://bugs.launchpad.net/products/zc.buildout/+bug/71246
5352       
5353        Buildout extensions installed as eggs couldn't be loaded in offline
5354        mode.
5355       
5356       
5357        1.0.0b16 (2006-12-07)
5358        =====================
5359       
5360        Feature Changes
5361        ---------------
5362       
5363        - A new command-line argument, -U, suppresses reading user defaults.
5364       
5365        - You can now suppress use of an installed-part database
5366        (e.g. .installed.cfg) by sprifying an empty value for the buildout
5367        installed option.
5368       
5369        Bugs Fixed
5370        ----------
5371       
5372        - When the install command is used with a list of parts, only
5373        those parts are supposed to be installed, but the buildout was also
5374        building parts that those parts depended on.
5375       
5376        1.0.0b15 (2006-12-06)
5377        =====================
5378       
5379        Bugs Fixed
5380        ----------
5381       
5382        - Uninstall recipes weren't loaded correctly in cases where
5383        no parts in the (new) configuration used the recipe egg.
5384       
5385        1.0.0b14 (2006-12-05)
5386        =====================
5387       
5388        Feature Changes
5389        ---------------
5390       
5391        - Added uninstall recipes for dealing with complex uninstallation
5392        scenarios.
5393       
5394        Bugs Fixed
5395        ----------
5396       
5397        - Automatic upgrades weren't performed on Windows due to a bug that
5398        caused buildout to incorrectly determine that it wasn't running
5399        locally in a buildout.
5400       
5401        - Fixed some spurious test failures on Windows.
5402       
5403        1.0.0b13 (2006-12-04)
5404        =====================
5405       
5406        Feature Changes
5407        ---------------
5408       
5409        - Variable substitutions now reflect option data written by recipes.
5410       
5411        - A part referenced by a part in a parts list is now added to the parts
5412        list before the referencing part.  This means that you can omit
5413        parts from the parts list if they are referenced by other parts.
5414       
5415        - Added a develop function to the easy_install module to aid in
5416        creating develop eggs with custom build_ext options.
5417       
5418        - The build and develop functions in the easy_install module now
5419        return the path of the egg or egg link created.
5420       
5421        - Removed the limitation that parts named in the install command can
5422        only name configured parts.
5423       
5424        - Removed support ConfigParser-style variable substitutions
5425        (e.g. %(foo)s). Only the string-template style of variable
5426        (e.g. ${section:option}) substitutions will be supported.
5427        Supporting both violates "there's only one way to do it".
5428       
5429        - Deprecated the buildout-section extendedBy option.
5430       
5431        Bugs Fixed
5432        ----------
5433       
5434        - We treat setuptools as a dependency of any distribution that
5435        (declares that it) uses namespace packages, whether it declares
5436        setuptools as a dependency or not.  This wasn't working for eggs
5437        intalled by virtue of being dependencies.
5438       
5439       
5440        1.0.0b12 (2006-10-24)
5441        =====================
5442       
5443        Feature Changes
5444        ---------------
5445       
5446        - Added an initialization argument to the
5447        zc.buildout.easy_install.scripts function to include initialization
5448        code in generated scripts.
5449       
5450        1.0.0b11 (2006-10-24)
5451        =====================
5452       
5453        Bugs Fixed
5454        ----------
5455       
5456        `67737 <https://launchpad.net/products/zc.buildout/+bug/67737>`_
5457        Verbose and quite output options caused errors when the
5458        develop buildout option was used to create develop eggs.
5459       
5460        `67871 <https://launchpad.net/products/zc.buildout/+bug/67871>`_
5461        Installation failed if the source was a (local) unzipped
5462        egg.
5463       
5464        `67873 <https://launchpad.net/products/zc.buildout/+bug/67873>`_
5465        There was an error in producing an error message when part names
5466        passed to the install command weren't included in the
5467        configuration.
5468       
5469        1.0.0b10 (2006-10-16)
5470        =====================
5471       
5472        Feature Changes
5473        ---------------
5474       
5475        - Renamed the runsetup command to setup. (The old name still works.)
5476       
5477        - Added a recipe update method. Now install is only called when a part
5478        is installed for the first time, or after an uninstall. Otherwise,
5479        update is called.  For backward compatibility, recipes that don't
5480        define update methiods are still supported.
5481       
5482        - If a distribution defines namespace packages but fails to declare
5483        setuptools as one of its dependencies, we now treat setuptools as an
5484        implicit dependency.  We generate a warning if the distribution
5485        is a develop egg.
5486       
5487        - You can now create develop eggs for setup scripts that don't use setuptools.
5488       
5489        Bugs Fixed
5490        ----------
5491       
5492        - Egg links weren't removed when corresponding entries were removed
5493        from develop sections.
5494       
5495        - Running a non-local buildout command (one not installed in the
5496        buildout) ket to a hang if there were new versions of zc.buildout or
5497        setuptools were available.  Now we issue a warning and don't
5498        upgrade.
5499       
5500        - When installing zip-safe eggs from local directories, the eggs were
5501        moved, rather than copied, removing them from the source directory.
5502       
5503        1.0.0b9 (2006-10-02)
5504        ====================
5505       
5506        Bugs Fixed
5507        ----------
5508       
5509        Non-zip-safe eggs were not unzipped when they were installed.
5510       
5511        1.0.0b8 (2006-10-01)
5512        ====================
5513       
5514        Bugs Fixed
5515        ----------
5516       
5517        - Installing source distributions failed when using alternate Python
5518        versions (depending on the versions of Python used.)
5519       
5520        - Installing eggs wasn't handled as efficiently as possible due to a
5521        bug in egg URL parsing.
5522       
5523        - Fixed a bug in runsetup that caused setup scripts that introspected
5524        __file__ to fail.
5525       
5526        1.0.0b7
5527        =======
5528       
5529        Added a documented testing framework for use by recipes. Refactored
5530        the buildout tests to use it.
5531       
5532        Added a runsetup command run a setup script.  This is handy if, like
5533        me, you don't install setuptools in your system Python.
5534       
5535        1.0.0b6
5536        =======
5537       
5538        Fixed https://launchpad.net/products/zc.buildout/+bug/60582
5539        Use of extension options caused bootstrapping to fail if the eggs
5540        directory didn't already exist.  We no longer use extensions for
5541        bootstrapping.  There really isn't any reason to anyway.
5542       
5543       
5544        1.0.0b5
5545        =======
5546       
5547        Refactored to do more work in buildout and less work in easy_install.
5548        This makes things go a little faster, makes errors a little easier to
5549        handle, and allows extensions (like the sftp extension) to influence
5550        more of the process. This was done to fix a problem in using the sftp
5551        support.
5552       
5553        1.0.0b4
5554        =======
5555       
5556        - Added an **experimental** extensions mechanism, mainly to support
5557        adding sftp support to buildouts that need it.
5558       
5559        - Fixed buildout self-updating on Windows.
5560       
5561        1.0.0b3
5562        =======
5563       
5564        - Added a help option (-h, --help)
5565       
5566        - Increased the default level of verbosity.
5567       
5568        - Buildouts now automatically update themselves to new versions of
5569        zc.buildout and setuptools.
5570       
5571        - Added Windows support.
5572       
5573        - Added a recipe API for generating user errors.
5574       
5575        - No-longer generate a py_zc.buildout script.
5576       
5577        - Fixed some bugs in variable substitutions.
5578       
5579        The characters "-", "." and " ", weren't allowed in section or
5580        option names.
5581       
5582        Substitutions with invalid names were ignored, which caused
5583        missleading failures downstream.
5584       
5585        - Improved error handling.  No longer show tracebacks for user errors.
5586       
5587        - Now require a recipe option (and therefore a section) for every part.
5588       
5589        - Expanded the easy_install module API to:
5590       
5591        - Allow extra paths to be provided
5592       
5593        - Specify explicit entry points
5594       
5595        - Specify entry-point arguments
5596       
5597        1.0.0b2
5598        =======
5599       
5600        Added support for specifying some build_ext options when installing eggs
5601        from source distributions.
5602       
5603        1.0.0b1
5604        =======
5605       
5606        - Changed the bootstrapping code to only install setuptools and
5607        zc.buildout. The bootstrap code no-longer runs the buildout itself.
5608        This was to fix a bug that caused parts to be recreated
5609        unnecessarily because the recipe signature in the initial buildout
5610        reflected temporary locations for setuptools and zc.buildout.
5611       
5612        - Now create a minimal setup.py if it doesn't exist and issue a
5613        warning that it is being created.
5614       
5615        - Fixed bug in saving installed configuration data.  %'s and extra
5616        spaces weren't quoted.
5617       
5618        1.0.0a1
5619        =======
5620       
5621        Initial public version
5622       
5623        Download
5624        **********************
5625       
5626Keywords: development build
5627Platform: UNKNOWN
5628Classifier: Intended Audience :: Developers
5629Classifier: License :: OSI Approved :: Zope Public License
5630Classifier: Topic :: Software Development :: Build Tools
5631Classifier: Topic :: Software Development :: Libraries :: Python Modules
Note: See TracBrowser for help on using the repository browser.