1 Metadata-Version: 1.0

     2 Name: zc.recipe.egg

     3 Version: 1.3.2

     4 Summary: Recipe for installing Python package distributions as eggs

     5 Home-page: http://cheeseshop.python.org/pypi/zc.recipe.egg

     6 Author: Jim Fulton

     7 Author-email: jim@zope.com

     8 License: ZPL 2.1

     9 Description: ********************************

    10         Buildout Egg-Installation Recipe

    11         ********************************

    12         

    13         .. contents::

    14         

    15         The egg-installation recipe installs eggs into a buildout eggs

    16         directory.  It also generates scripts in a buildout bin directory with 

    17         egg paths baked into them.

    18         

    19         

    20         Change History

    21         **************

    22         

    23         1.3.2 (2010-08-23)

    24         ==================

    25         

    26         - Bugfix for the change introduced in 1.3.1.

    27         

    28         1.3.1 (2010-08-23)

    29         ==================

    30         

    31         - Support recipes that are using zc.recipe.egg by passing in a dict, rather

    32           than a zc.buildout.buildout.Options object as was expected/tested.

    33         

    34         1.3.0 (2010-08-23)

    35         ==================

    36         

    37         - Small further refactorings past 1.2.3b1 to be compatible with zc.buildout

    38           1.5.0.

    39         

    40         1.2.3b1 (2010-04-29)

    41         ====================

    42         

    43         - Refactored to be used with z3c.recipe.scripts and zc.buildout 1.5.0.  No

    44           new user-visible features.

    45         

    46         1.2.2 (2009-03-18)

    47         ==================

    48         

    49         - Fixed a dependency information. zc.buildout >1.2.0 is required.

    50         

    51         1.2.1 (2009-03-18)

    52         ==================

    53         

    54         - Refactored generation of relative egg paths to generate simpler code.

    55         

    56         1.2.0 (2009-03-17)

    57         ==================

    58         

    59         - Added the `dependent-scripts` option.  When set to `true`, scripts will

    60           be generated for all required eggs in addition to the eggs named

    61           specifically.  This idea came from two forks of this recipe,

    62           `repoze.recipe.egg` and `pylons_sandbox`, but the option name is

    63           spelled with a dash instead of underscore and it defaults to `false`.

    64         

    65         - Added a relative-paths option. When true, egg paths in scripts are generated

    66           relative to the script names.

    67         

    68         1.1.0 (2008-07-19)

    69         ==================

    70         

    71         - Refactored to work honor the new buildout-level unzip option.

    72         

    73         

    74         1.1.0b1 (2008-06-27)

    75         ====================

    76         

    77         - Added `environment` option to custom extension building options.

    78         

    79         1.0.0 (2007-11-03)

    80         ==================

    81         

    82         - No code changes from last beta, just some small package meta-data

    83           improvements.

    84         

    85         1.0.0b5 (2007-02-08)

    86         ====================

    87         

    88         Feature Changes

    89         ---------------

    90         

    91         - Added support for the buildout newest option.

    92         

    93         1.0.0b4 (2007-01-17)

    94         ====================

    95         

    96         Feature Changes

    97         ---------------

    98         

    99         - Added initialization and arguments options to the scripts recipe.

   100         

   101         - Added an eggs recipe that *just* installes eggs.

   102         

   103         - Advertized the scripts recipe for creating scripts.

   104         

   105         1.0.0b3 (2006-12-04)

   106         ====================

   107         

   108         Feature Changes

   109         ---------------

   110         

   111         - Added a develop recipe for creating develop eggs.

   112         

   113           This is useful to:

   114         

   115           - Specify custom extension building options,

   116         

   117           - Specify a version of Python to use, and to

   118         

   119           - Cause develop eggs to be created after other parts.

   120         

   121         - The develop and build recipes now return the paths created, so that

   122           created eggs or egg links are removed when a part is removed (or

   123           changed).

   124         

   125         

   126         1.0.0b2 (2006-10-16)

   127         ====================

   128         

   129         Updated to work with (not get a warning from) zc.buildout 1.0.0b10.

   130         

   131         1.0.0b1

   132         =======

   133         

   134         Updated to work with zc.buildout 1.0.0b3.

   135         

   136         1.0.0a3

   137         =======

   138         

   139         - Extra path elements to be included in generated scripts can now be

   140           set via the extra-paths option.

   141         

   142         - No longer implicitly generate py\_ scripts fo reach egg. There is

   143           now an interpreter option to generate a script that, when run

   144           without arguments, launches the Python interactive interpreter with

   145           the path set based on a parts eggs and extra paths.  If this script

   146           is run with the name of a Python script and arguments, then the

   147           given script is run with the path set.

   148         

   149         - You can now specify explicit entry points.  This is useful for use

   150           with packages that don't declare their own entry points.

   151         

   152         - Added Windows support.

   153         

   154         - Now-longer implicitly generate "py\_" scripts for each egg.  You can

   155           now generate a script for launching a Python interpreter or for

   156           running scripts based on the eggs defined for an egg part.

   157         

   158         - You can now specify custom entry points for packages that don't

   159           declare their entry points.

   160         

   161         - You can now specify extra-paths to be included in generated scripts.

   162         

   163         

   164         1.0.0a2

   165         =======

   166         

   167         Added a custom recipe for building custom eggs using custom distrutils

   168         build_ext arguments.

   169         

   170         1.0.0a1

   171         =======

   172         

   173         Initial public version

   174         

   175         Detailed Documentation

   176         **********************

   177         

   178         Installation of distributions as eggs

   179         =====================================

   180         

   181         The zc.recipe.egg:eggs recipe can be used to install various types if

   182         distutils distributions as eggs.  It takes a number of options:

   183         

   184         eggs

   185             A list of eggs to install given as one or more setuptools

   186             requirement strings.  Each string must be given on a separate

   187             line.

   188         

   189         find-links

   190            A list of URLs, files, or directories to search for distributions.

   191         

   192         index

   193            The URL of an index server, or almost any other valid URL. :)

   194         

   195            If not specified, the Python Package Index,

   196            http://cheeseshop.python.org/pypi, is used.  You can specify an

   197            alternate index with this option.  If you use the links option and

   198            if the links point to the needed distributions, then the index can

   199            be anything and will be largely ignored.  In the examples, here,

   200            we'll just point to an empty directory on our link server.  This

   201            will make our examples run a little bit faster.

   202         

   203         python

   204            The name of a section to get the Python executable from.

   205            If not specified, then the buildout python option is used.  The

   206            Python executable is found in the executable option of the named

   207            section.

   208         

   209         We have a link server that has a number of distributions:

   210         

   211             >>> print get(link_server),

   212             <html><body>

   213             <a href="bigdemo-0.1-py2.3.egg">bigdemo-0.1-py2.3.egg</a><br>

   214             <a href="demo-0.1-py2.3.egg">demo-0.1-py2.3.egg</a><br>

   215             <a href="demo-0.2-py2.3.egg">demo-0.2-py2.3.egg</a><br>

   216             <a href="demo-0.3-py2.3.egg">demo-0.3-py2.3.egg</a><br>

   217             <a href="demo-0.4c1-py2.3.egg">demo-0.4c1-py2.3.egg</a><br>

   218             <a href="demoneeded-1.0.zip">demoneeded-1.0.zip</a><br>

   219             <a href="demoneeded-1.1.zip">demoneeded-1.1.zip</a><br>

   220             <a href="demoneeded-1.2c1.zip">demoneeded-1.2c1.zip</a><br>

   221             <a href="extdemo-1.4.zip">extdemo-1.4.zip</a><br>

   222             <a href="index/">index/</a><br>

   223             <a href="other-1.0-py2.3.egg">other-1.0-py2.3.egg</a><br>

   224             </body></html>

   225         

   226         We have a sample buildout.  Let's update its configuration file to

   227         install the demo package.

   228         

   229             >>> write(sample_buildout, 'buildout.cfg',

   230             ... """

   231             ... [buildout]

   232             ... parts = demo

   233             ...

   234             ... [demo]

   235             ... recipe = zc.recipe.egg:eggs

   236             ... eggs = demo<0.3

   237             ... find-links = %(server)s

   238             ... index = %(server)s/index

   239             ... """ % dict(server=link_server))

   240         

   241         In this example, we limited ourselves to revisions before 0.3. We also

   242         specified where to find distributions using the find-links option.

   243         

   244         Let's run the buildout:

   245         

   246             >>> import os

   247             >>> print system(buildout),

   248             Installing demo.

   249             Getting distribution for 'demo<0.3'.

   250             Got demo 0.2.

   251             Getting distribution for 'demoneeded'.

   252             Got demoneeded 1.2c1.

   253         

   254         Now, if we look at the buildout eggs directory:

   255         

   256             >>> ls(sample_buildout, 'eggs')

   257             -  demo-0.2-py2.3.egg

   258             -  demoneeded-1.2c1-py2.3.egg

   259             -  setuptools-0.6-py2.3.egg

   260             -  zc.buildout-1.0-py2.3.egg

   261         

   262         We see that we got an egg for demo that met the requirement, as well

   263         as the egg for demoneeded, which demo requires.  (We also see an egg

   264         link for the recipe in the develop-eggs directory.  This egg link was

   265         actually created as part of the sample buildout setup. Normally, when

   266         using the recipe, you'll get a regular egg installation.)

   267         

   268         Script generation

   269         -----------------

   270         

   271         The demo egg defined a script, but we didn't get one installed:

   272         

   273             >>> ls(sample_buildout, 'bin')

   274             -  buildout

   275         

   276         If we want scripts provided by eggs to be installed, we should use the

   277         scripts recipe:

   278         

   279             >>> write(sample_buildout, 'buildout.cfg',

   280             ... """

   281             ... [buildout]

   282             ... parts = demo

   283             ...

   284             ... [demo]

   285             ... recipe = zc.recipe.egg:scripts

   286             ... eggs = demo<0.3

   287             ... find-links = %(server)s

   288             ... index = %(server)s/index

   289             ... """ % dict(server=link_server))

   290         

   291             >>> print system(buildout),

   292             Uninstalling demo.

   293             Installing demo.

   294             Generated script '/sample-buildout/bin/demo'.

   295         

   296         Now we also see the script defined by the demo script:

   297         

   298             >>> ls(sample_buildout, 'bin')

   299             -  buildout

   300             -  demo

   301         

   302         The scripts recipe defines some additional options:

   303         

   304         entry-points

   305            A list of entry-point identifiers of the form:

   306         

   307            name=module:attrs

   308         

   309            where name is a script name, module is a dotted name resolving to a

   310            module name, and attrs is a dotted name resolving to a callable

   311            object within a module.

   312         

   313            This option is useful when working with distributions that don't

   314            declare entry points, such as distributions not written to work

   315            with setuptools.

   316         

   317            Examples can be seen in the section "Specifying entry points" below.

   318         

   319         scripts

   320            Control which scripts are generated.  The value should be a list of

   321            zero or more tokens.  Each token is either a name, or a name

   322            followed by an '=' and a new name.  Only the named scripts are

   323            generated.  If no tokens are given, then script generation is

   324            disabled.  If the option isn't given at all, then all scripts

   325            defined by the named eggs will be generated.

   326         

   327         dependent-scripts

   328            If set to the string "true", scripts will be generated for all

   329            required eggs in addition to the eggs specifically named.

   330         

   331         interpreter

   332            The name of a script to generate that allows access to a Python

   333            interpreter that has the path set based on the eggs installed.

   334            (See the ``z3c.recipe.scripts`` recipe for a more full-featured

   335            interpreter.)

   336         

   337         extra-paths

   338            Extra paths to include in a generated script.

   339         

   340         initialization

   341            Specify some Python initialization code.  This is very limited.  In

   342            particular, be aware that leading whitespace is stripped from the

   343            code given.

   344         

   345         arguments

   346            Specify some arguments to be passed to entry points as Python source.

   347         

   348         relative-paths

   349            If set to true, then egg paths will be generated relative to the

   350            script path.  This allows a buildout to be moved without breaking

   351            egg paths.  This option can be set in either the script section or

   352            in the buildout section.

   353         

   354         Let's add an interpreter option:

   355         

   356             >>> write(sample_buildout, 'buildout.cfg',

   357             ... """

   358             ... [buildout]

   359             ... parts = demo

   360             ...

   361             ... [demo]

   362             ... recipe = zc.recipe.egg

   363             ... eggs = demo<0.3

   364             ... find-links = %(server)s

   365             ... index = %(server)s/index

   366             ... interpreter = py-demo

   367             ... """ % dict(server=link_server))

   368         

   369         Note that we omitted the entry point name from the recipe

   370         specification. We were able to do this because the scripts recipe is

   371         the default entry point for the zc.recipe.egg egg.

   372         

   373            >>> print system(buildout),

   374            Uninstalling demo.

   375            Installing demo.

   376            Generated script '/sample-buildout/bin/demo'.

   377            Generated interpreter '/sample-buildout/bin/py-demo'.

   378         

   379         Now we also get a py-demo script for giving us a Python prompt with

   380         the path for demo and any eggs it depends on included in sys.path.

   381         This is useful for debugging and testing.

   382         

   383             >>> ls(sample_buildout, 'bin')

   384             -  buildout

   385             -  demo

   386             -  py-demo

   387         

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

   389         

   390             >>> print system(join(sample_buildout, 'bin', 'demo')),

   391             2 2

   392         

   393         The value it prints out happens to be some values defined in the

   394         modules installed.

   395         

   396         We can also run the py-demo script.  Here we'll just print out

   397         the bits if the path added to reflect the eggs:

   398         

   399             >>> print system(join(sample_buildout, 'bin', 'py-demo'),

   400             ... """import os, sys

   401             ... for p in sys.path:

   402             ...     if 'demo' in p:

   403             ...         print os.path.basename(p)

   404             ...

   405             ... """).replace('>>> ', '').replace('... ', ''),

   406             ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE

   407             demo-0.2-py2.4.egg

   408             demoneeded-1.2c1-py2.4.egg

   409         

   410         Egg updating

   411         ------------

   412         

   413         The recipe normally gets the most recent distribution that satisfies the

   414         specification.  It won't do this is the buildout is either in

   415         non-newest mode or in offline mode.  To see how this works, we'll

   416         remove the restriction on demo:

   417         

   418             >>> write(sample_buildout, 'buildout.cfg',

   419             ... """

   420             ... [buildout]

   421             ... parts = demo

   422             ...

   423             ... [demo]

   424             ... recipe = zc.recipe.egg

   425             ... find-links = %(server)s

   426             ... index = %(server)s/index

   427             ... """ % dict(server=link_server))

   428         

   429         and run the buildout in non-newest mode:

   430         

   431             >>> print system(buildout+' -N'),

   432             Uninstalling demo.

   433             Installing demo.

   434             Generated script '/sample-buildout/bin/demo'.

   435         

   436         Note that we removed the eggs option, and the eggs defaulted to the

   437         part name. Because we removed the eggs option, the demo was

   438         reinstalled.

   439         

   440         We'll also run the buildout in off-line mode:

   441         

   442             >>> print system(buildout+' -o'),

   443             Updating demo.

   444         

   445         We didn't get an update for demo:

   446         

   447             >>> ls(sample_buildout, 'eggs')

   448             -  demo-0.2-py2.3.egg

   449             -  demoneeded-1.2c1-py2.3.egg

   450             -  setuptools-0.6-py2.3.egg

   451             -  zc.buildout-1.0-py2.3.egg

   452         

   453         If we run the buildout on the default online and newest modes,

   454         we'll get an update for demo:

   455         

   456             >>> print system(buildout),

   457             Updating demo.

   458             Getting distribution for 'demo'.

   459             Got demo 0.4c1.

   460             Generated script '/sample-buildout/bin/demo'.

   461         

   462         Then we'll get a new demo egg:

   463         

   464             >>> ls(sample_buildout, 'eggs')

   465             -  demo-0.2-py2.3.egg

   466             -  demo-0.4c1-py2.3.egg

   467             -  demoneeded-1.2c1-py2.3.egg

   468             -  setuptools-0.6-py2.4.egg

   469             -  zc.buildout-1.0-py2.4.egg

   470         

   471         The script is updated too:

   472         

   473             >>> print system(join(sample_buildout, 'bin', 'demo')),

   474             4 2

   475         

   476         Controlling script generation

   477         -----------------------------

   478         

   479         You can control which scripts get generated using the scripts option.

   480         For example, to suppress scripts, use the scripts option without any

   481         arguments:

   482         

   483             >>> write(sample_buildout, 'buildout.cfg',

   484             ... """

   485             ... [buildout]

   486             ... parts = demo

   487             ...

   488             ... [demo]

   489             ... recipe = zc.recipe.egg

   490             ... find-links = %(server)s

   491             ... index = %(server)s/index

   492             ... scripts =

   493             ... """ % dict(server=link_server))

   494         

   495         

   496             >>> print system(buildout),

   497             Uninstalling demo.

   498             Installing demo.

   499         

   500             >>> ls(sample_buildout, 'bin')

   501             -  buildout

   502         

   503         You can also control the name used for scripts:

   504         

   505             >>> write(sample_buildout, 'buildout.cfg',

   506             ... """

   507             ... [buildout]

   508             ... parts = demo

   509             ...

   510             ... [demo]

   511             ... recipe = zc.recipe.egg

   512             ... find-links = %(server)s

   513             ... index = %(server)s/index

   514             ... scripts = demo=foo

   515             ... """ % dict(server=link_server))

   516         

   517             >>> print system(buildout),

   518             Uninstalling demo.

   519             Installing demo.

   520             Generated script '/sample-buildout/bin/foo'.

   521         

   522             >>> ls(sample_buildout, 'bin')

   523             -  buildout

   524             -  foo

   525         

   526         Specifying extra script paths

   527         -----------------------------

   528         

   529         If we need to include extra paths in a script, we can use the

   530         extra-paths option:

   531         

   532             >>> write(sample_buildout, 'buildout.cfg',

   533             ... """

   534             ... [buildout]

   535             ... parts = demo

   536             ...

   537             ... [demo]

   538             ... recipe = zc.recipe.egg

   539             ... find-links = %(server)s

   540             ... index = %(server)s/index

   541             ... scripts = demo=foo

   542             ... extra-paths =

   543             ...    /foo/bar

   544             ...    ${buildout:directory}/spam

   545             ... """ % dict(server=link_server))

   546         

   547             >>> print system(buildout),

   548             Uninstalling demo.

   549             Installing demo.

   550             Generated script '/sample-buildout/bin/foo'.

   551         

   552         Let's look at the script that was generated:

   553         

   554             >>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE

   555             #!/usr/local/bin/python2.4

   556             <BLANKLINE>

   557             import sys

   558             sys.path[0:0] = [

   559               '/sample-buildout/eggs/demo-0.4c1-py2.4.egg',

   560               '/sample-buildout/eggs/demoneeded-1.2c1-py2.4.egg',

   561               '/foo/bar',

   562               '/sample-buildout/spam',

   563               ]

   564             <BLANKLINE>

   565             import eggrecipedemo

   566             <BLANKLINE>

   567             if __name__ == '__main__':

   568                 eggrecipedemo.main()

   569         

   570         Relative egg paths

   571         ------------------

   572         

   573         If the relative-paths option is specified with a true value, then

   574         paths will be generated relative to the script. This is useful when

   575         you want to be able to move a buildout directory around without

   576         breaking scripts.

   577         

   578             >>> write(sample_buildout, 'buildout.cfg',

   579             ... """

   580             ... [buildout]

   581             ... parts = demo

   582             ...

   583             ... [demo]

   584             ... recipe = zc.recipe.egg

   585             ... find-links = %(server)s

   586             ... index = %(server)s/index

   587             ... scripts = demo=foo

   588             ... relative-paths = true

   589             ... extra-paths =

   590             ...    /foo/bar

   591             ...    ${buildout:directory}/spam

   592             ... """ % dict(server=link_server))

   593         

   594             >>> print system(buildout),

   595             Uninstalling demo.

   596             Installing demo.

   597             Generated script '/sample-buildout/bin/foo'.

   598         

   599         Let's look at the script that was generated:

   600         

   601             >>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE

   602             #!/usr/local/bin/python2.4

   603             <BLANKLINE>

   604             import os

   605             <BLANKLINE>

   606             join = os.path.join

   607             base = os.path.dirname(os.path.abspath(os.path.realpath(__file__)))

   608             base = os.path.dirname(base)

   609             <BLANKLINE>

   610             import sys

   611             sys.path[0:0] = [

   612               join(base, 'eggs/demo-0.4c1-pyN.N.egg'),

   613               join(base, 'eggs/demoneeded-1.2c1-pyN.N.egg'),

   614               '/foo/bar',

   615               join(base, 'spam'),

   616               ]

   617             <BLANKLINE>

   618             import eggrecipedemo

   619             <BLANKLINE>

   620             if __name__ == '__main__':

   621                 eggrecipedemo.main()

   622         

   623         You can specify relative paths in the buildout section, rather than in

   624         each individual script section:

   625         

   626         

   627             >>> write(sample_buildout, 'buildout.cfg',

   628             ... """

   629             ... [buildout]

   630             ... parts = demo

   631             ... relative-paths = true

   632             ...

   633             ... [demo]

   634             ... recipe = zc.recipe.egg

   635             ... find-links = %(server)s

   636             ... index = %(server)s/index

   637             ... scripts = demo=foo

   638             ... extra-paths =

   639             ...    /foo/bar

   640             ...    ${buildout:directory}/spam

   641             ... """ % dict(server=link_server))

   642         

   643             >>> print system(buildout),

   644             Uninstalling demo.

   645             Installing demo.

   646             Generated script '/sample-buildout/bin/foo'.

   647         

   648             >>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE

   649             #!/usr/local/bin/python2.4

   650             <BLANKLINE>

   651             import os

   652             <BLANKLINE>

   653             join = os.path.join

   654             base = os.path.dirname(os.path.abspath(os.path.realpath(__file__)))

   655             base = os.path.dirname(base)

   656             <BLANKLINE>

   657             import sys

   658             sys.path[0:0] = [

   659               join(base, 'eggs/demo-0.4c1-pyN.N.egg'),

   660               join(base, 'eggs/demoneeded-1.2c1-pyN.N.egg'),

   661               '/foo/bar',

   662               join(base, 'spam'),

   663               ]

   664             <BLANKLINE>

   665             import eggrecipedemo

   666             <BLANKLINE>

   667             if __name__ == '__main__':

   668                 eggrecipedemo.main()

   669         

   670         Specifying initialialization code and arguments

   671         -----------------------------------------------

   672         

   673         Sometimes, we need to do more than just calling entry points.  We can

   674         use the initialialization and arguments options to specify extra code

   675         to be included in generated scripts:

   676         

   677         

   678             >>> write(sample_buildout, 'buildout.cfg',

   679             ... """

   680             ... [buildout]

   681             ... parts = demo

   682             ...

   683             ... [demo]

   684             ... recipe = zc.recipe.egg

   685             ... find-links = %(server)s

   686             ... index = %(server)s/index

   687             ... scripts = demo=foo

   688             ... extra-paths =

   689             ...    /foo/bar

   690             ...    ${buildout:directory}/spam

   691             ... initialization = a = (1, 2

   692             ...                       3, 4)

   693             ... arguments = a, 2

   694             ... """ % dict(server=link_server))

   695         

   696             >>> print system(buildout),

   697             Uninstalling demo.

   698             Installing demo.

   699             Generated script '/sample-buildout/bin/foo'.

   700         

   701             >>> cat(sample_buildout, 'bin', 'foo') # doctest: +NORMALIZE_WHITESPACE

   702             #!/usr/local/bin/python2.4

   703             <BLANKLINE>

   704             import sys

   705             sys.path[0:0] = [

   706               '/sample-buildout/eggs/demo-0.4c1-py2.4.egg',

   707               '/sample-buildout/eggs/demoneeded-1.2c1-py2.4.egg',

   708               '/foo/bar',

   709               '/sample-buildout/spam',

   710               ]

   711             <BLANKLINE>

   712             a = (1, 2

   713             3, 4)

   714             <BLANKLINE>

   715             import eggrecipedemo

   716             <BLANKLINE>

   717             if __name__ == '__main__':

   718                 eggrecipedemo.main(a, 2)

   719         

   720         Here we see that the initialization code we specified was added after

   721         setting the path.  Note, as mentioned above, that leading whitespace

   722         has been stripped.  Similarly, the argument code we specified was

   723         added in the entry point call (to main).

   724         

   725         Specifying entry points

   726         -----------------------

   727         

   728         Scripts can be generated for entry points declared explicitly.  We can

   729         declare entry points using the entry-points option:

   730         

   731             >>> write(sample_buildout, 'buildout.cfg',

   732             ... """

   733             ... [buildout]

   734             ... parts = demo

   735             ...

   736             ... [demo]

   737             ... recipe = zc.recipe.egg

   738             ... find-links = %(server)s

   739             ... index = %(server)s/index

   740             ... extra-paths =

   741             ...    /foo/bar

   742             ...    ${buildout:directory}/spam

   743             ... entry-points = alt=eggrecipedemo:alt other=foo.bar:a.b.c

   744             ... """ % dict(server=link_server))

   745         

   746             >>> print system(buildout),

   747             Uninstalling demo.

   748             Installing demo.

   749             Generated script '/sample-buildout/bin/demo'.

   750             Generated script '/sample-buildout/bin/alt'.

   751             Generated script '/sample-buildout/bin/other'.

   752         

   753             >>> ls(sample_buildout, 'bin')

   754             -  alt

   755             -  buildout

   756             -  demo

   757             -  other

   758         

   759             >>> cat(sample_buildout, 'bin', 'other') # doctest: +NORMALIZE_WHITESPACE

   760             #!/usr/local/bin/python2.4

   761             <BLANKLINE>

   762             import sys

   763             sys.path[0:0] = [

   764               '/sample-buildout/eggs/demo-0.4c1-py2.4.egg',

   765               '/sample-buildout/eggs/demoneeded-1.2c1-py2.4.egg',

   766               '/foo/bar',

   767               '/sample-buildout/spam',

   768               ]

   769             <BLANKLINE>

   770             import foo.bar

   771             <BLANKLINE>

   772             if __name__ == '__main__':

   773                 foo.bar.a.b.c()

   774         

   775         Generating all scripts

   776         ----------------------

   777         

   778         The `bigdemo` package doesn't have any scripts, but it requires the `demo`

   779         package, which does have a script.  Specify `dependent-scripts = true` to

   780         generate all scripts in required packages:

   781         

   782             >>> write(sample_buildout, 'buildout.cfg',

   783             ... """

   784             ... [buildout]

   785             ... parts = bigdemo

   786             ...

   787             ... [bigdemo]

   788             ... recipe = zc.recipe.egg

   789             ... find-links = %(server)s

   790             ... index = %(server)s/index

   791             ... dependent-scripts = true

   792             ... """ % dict(server=link_server))

   793             >>> print system(buildout+' -N'),

   794             Uninstalling demo.

   795             Installing bigdemo.

   796             Getting distribution for 'bigdemo'.

   797             Got bigdemo 0.1.

   798             Generated script '/sample-buildout/bin/demo'.

   799         

   800         Offline mode

   801         ------------

   802         

   803         If the buildout offline option is set to "true", then no attempt will

   804         be made to contact an index server:

   805         

   806             >>> write(sample_buildout, 'buildout.cfg',

   807             ... """

   808             ... [buildout]

   809             ... parts = demo

   810             ... offline = true

   811             ...

   812             ... [demo]

   813             ... recipe = zc.recipe.egg

   814             ... index = eek!

   815             ... scripts = demo=foo

   816             ... """ % dict(server=link_server))

   817         

   818             >>> print system(buildout),

   819             Uninstalling bigdemo.

   820             Installing demo.

   821             Generated script '/sample-buildout/bin/foo'.

   822         

   823         

   824         Controlling which Python to use

   825         -------------------------------

   826         

   827         The following assumes that you have Python 2.4 installed.

   828         

   829         We can specify the python to use by specifying the name of a section

   830         to read the Python executable from.  The default is the section

   831         defined by the python buildout option.

   832         

   833         We have a link server:

   834         

   835             >>> print get(link_server),

   836             <html><body>

   837             <a href="bigdemo-0.1-py2.4.egg">bigdemo-0.1-py2.4.egg</a><br>

   838             <a href="demo-0.1-py2.4.egg">demo-0.1-py2.4.egg</a><br>

   839             <a href="demo-0.2-py2.4.egg">demo-0.2-py2.4.egg</a><br>

   840             <a href="demo-0.3-py2.4.egg">demo-0.3-py2.4.egg</a><br>

   841             <a href="demo-0.4c1-py2.4.egg">demo-0.4c1-py2.4.egg</a><br>

   842             <a href="demoneeded-1.0.zip">demoneeded-1.0.zip</a><br>

   843             <a href="demoneeded-1.1.zip">demoneeded-1.1.zip</a><br>

   844             <a href="demoneeded-1.2c1.zip">demoneeded-1.2c1.zip</a><br>

   845             <a href="extdemo-1.4.zip">extdemo-1.4.zip</a><br>

   846             <a href="index/">index/</a><br>

   847             <a href="other-1.0-py2.4.egg">other-1.0-py2.4.egg</a><br>

   848             </body></html>

   849         

   850         We have a sample buildout.  Let's update its configuration file to

   851         install the demo package using Python 2.4.

   852         

   853             >>> write(sample_buildout, 'buildout.cfg',

   854             ... """

   855             ... [buildout]

   856             ... parts = demo

   857             ... eggs-directory = eggs

   858             ... index = http://www.python.org/pypi/

   859             ...

   860             ... [python2.4]

   861             ... executable = %(python24)s

   862             ...

   863             ... [demo]

   864             ... recipe = zc.recipe.egg

   865             ... eggs = demo <0.3

   866             ... find-links = %(server)s

   867             ... python = python2.4

   868             ... interpreter = py-demo

   869             ... """ % dict(server=link_server, python24=other_executable))

   870         

   871         Now, if we run the buildout:

   872         

   873            >>> import os

   874            >>> os.chdir(sample_buildout)

   875            >>> buildout = os.path.join(sample_buildout, 'bin', 'buildout')

   876            >>> print system(buildout),

   877            Installing demo.

   878            Getting distribution for 'demo<0.3'.

   879            Got demo 0.2.

   880            Getting distribution for 'demoneeded'.

   881            Got demoneeded 1.2c1.

   882            Generated script '/sample-buildout/bin/demo'.

   883            Generated interpreter '/sample-buildout/bin/py-demo'.

   884         

   885         we'll get the Python 2.4 eggs for demo and demoneeded:

   886         

   887             >>> ls(sample_buildout, 'eggs')

   888             -  demo-0.2-py2.4.egg

   889             -  demoneeded-1.2c1-py2.4.egg

   890             d  setuptools-0.6-py2.5.egg

   891             -  zc.buildout-1.0-py2.5.egg

   892         

   893         And the generated scripts invoke Python 2.4:

   894         

   895             >>> import sys

   896             >>> if sys.platform == 'win32':

   897             ...    script_name = 'demo-script.py'

   898             ... else:

   899             ...    script_name = 'demo'

   900             >>> f = open(os.path.join(sample_buildout, 'bin', script_name))

   901             >>> shebang = f.readline().strip()

   902             >>> if shebang[:3] == '#!"' and shebang[-1] == '"':

   903             ...     shebang = '#!'+shebang[3:-1]

   904             >>> shebang == '#!' + other_executable

   905             True

   906             >>> print f.read(), # doctest: +NORMALIZE_WHITESPACE

   907             <BLANKLINE>

   908             import sys

   909             sys.path[0:0] = [

   910               '/sample-buildout/eggs/demo-0.2-py2.4.egg',

   911               '/sample-buildout/eggs/demoneeded-1.2c1-py2.4.egg',

   912               ]

   913             <BLANKLINE>

   914             import eggrecipedemo

   915             <BLANKLINE>

   916             if __name__ == '__main__':

   917                 eggrecipedemo.main()

   918         

   919             >>> if sys.platform == 'win32':

   920             ...     f = open(os.path.join(sample_buildout, 'bin', 'py-demo-script.py'))

   921             ... else:

   922             ...     f = open(os.path.join(sample_buildout, 'bin', 'py-demo'))

   923         

   924             >>> shebang = f.readline().strip()

   925             >>> if shebang[:3] == '#!"' and shebang[-1] == '"':

   926             ...     shebang = '#!'+shebang[3:-1]

   927             >>> shebang == '#!' + other_executable

   928             True

   929             >>> print f.read(), # doctest: +NORMALIZE_WHITESPACE

   930             <BLANKLINE>

   931             import sys

   932             <BLANKLINE>

   933             sys.path[0:0] = [

   934               '/sample-buildout/eggs/demo-0.2-py2.4.egg',

   935               '/sample-buildout/eggs/demoneeded-1.2c1-py2.4.egg',

   936               ]

   937             <BLANKLINE>

   938             _interactive = True

   939             if len(sys.argv) > 1:

   940                 _options, _args = __import__("getopt").getopt(sys.argv[1:], 'ic:m:')

   941                 _interactive = False

   942                 for (_opt, _val) in _options:

   943                     if _opt == '-i':

   944                         _interactive = True

   945                     elif _opt == '-c':

   946                         exec _val

   947                     elif _opt == '-m':

   948                         sys.argv[1:] = _args

   949                         _args = []

   950                         __import__("runpy").run_module(

   951                              _val, {}, "__main__", alter_sys=True)

   952             <BLANKLINE>

   953                 if _args:

   954                     sys.argv[:] = _args

   955                     __file__ = _args[0]

   956                     del _options, _args

   957                     execfile(__file__)

   958             <BLANKLINE>

   959             if _interactive:

   960                 del _interactive

   961                 __import__("code").interact(banner="", local=globals())

   962         

   963             >>> f.close()

   964         

   965         Creating eggs with extensions needing custom build settings

   966         =============================================================

   967         

   968         Sometimes, It's necessary to provide extra control over how an egg is

   969         created.  This is commonly true for eggs with extension modules that

   970         need to access libraries or include files.

   971         

   972         The zc.recipe.egg:custom recipe can be used to define an egg with

   973         custom build parameters.  The currently defined parameters are:

   974         

   975         include-dirs

   976            A new-line separated list of directories to search for include

   977            files.

   978         

   979         library-dirs

   980            A new-line separated list of directories to search for libraries

   981            to link with.

   982         

   983         rpath

   984            A new-line separated list of directories to search for dynamic libraries

   985            at run time.

   986         

   987         define

   988            A comma-separated list of names of C preprocessor variables to

   989            define.

   990         

   991         undef

   992            A comman separated list of names of C preprocessor variables to

   993            undefine.

   994         

   995         libraries

   996            The name of an additional library to link with.  Due to limitations

   997            in distutils and desprite the option name, only a single library

   998            can be specified.

   999         

  1000         link-objects

  1001            The name of an link object to link against.  Due to limitations

  1002            in distutils and desprite the option name, only a single link object

  1003            can be specified.

  1004         

  1005         debug

  1006            Compile/link with debugging information

  1007         

  1008         force

  1009            Forcibly build everything (ignore file timestamps)

  1010         

  1011         compiler

  1012            Specify the compiler type

  1013         

  1014         swig

  1015            The path to the swig executable

  1016         

  1017         swig-cpp

  1018            Make SWIG create C++ files (default is C)

  1019         

  1020         swig-opts

  1021            List of SWIG command line options

  1022         

  1023         In addition, the following options can be used to specify the egg:

  1024         

  1025         egg

  1026             An specification for the egg to be created, to install given as a

  1027             setuptools requirement string.  This defaults to the part name.

  1028         

  1029         find-links

  1030            A list of URLs, files, or directories to search for distributions.

  1031         

  1032         index

  1033            The URL of an index server, or almost any other valid URL. :)

  1034         

  1035            If not specified, the Python Package Index,

  1036            http://cheeseshop.python.org/pypi, is used.  You can specify an

  1037            alternate index with this option.  If you use the links option and

  1038            if the links point to the needed distributions, then the index can

  1039            be anything and will be largely ignored.  In the examples, here,

  1040            we'll just point to an empty directory on our link server.  This

  1041            will make our examples run a little bit faster.

  1042         

  1043         python

  1044            The name of a section to get the Python executable from.

  1045            If not specified, then the buildout python option is used.  The

  1046            Python executable is found in the executable option of the named

  1047            section.

  1048         

  1049         environment

  1050            The name of a section with additional environment variables. The

  1051            environment variables are set before the egg is built.

  1052         

  1053         To illustrate this, we'll define a buildout that builds an egg for a

  1054         package that has a simple extension module::

  1055         

  1056           #include <Python.h>

  1057           #include <extdemo.h>

  1058         

  1059           static PyMethodDef methods[] = {};

  1060         

  1061           PyMODINIT_FUNC

  1062           initextdemo(void)

  1063           {

  1064               PyObject *m;

  1065               m = Py_InitModule3("extdemo", methods, "");

  1066           #ifdef TWO

  1067               PyModule_AddObject(m, "val", PyInt_FromLong(2));

  1068           #else

  1069               PyModule_AddObject(m, "val", PyInt_FromLong(EXTDEMO));

  1070           #endif

  1071           }

  1072         

  1073         The extension depends on a system-dependent include file, extdemo.h,

  1074         that defines a constant, EXTDEMO, that is exposed by the extension.

  1075         

  1076         The extension module is available as a source distribution,

  1077         extdemo-1.4.tar.gz, on a distribution server.

  1078         

  1079         We have a sample buildout that we'll add an include directory to with

  1080         the necessary include file:

  1081         

  1082             >>> mkdir('include')

  1083             >>> write('include', 'extdemo.h',

  1084             ... """

  1085             ... #define EXTDEMO 42

  1086             ... """)

  1087         

  1088         We'll also update the buildout configuration file to define a part for

  1089         the egg:

  1090         

  1091             >>> write(sample_buildout, 'buildout.cfg',

  1092             ... """

  1093             ... [buildout]

  1094             ... parts = extdemo

  1095             ...

  1096             ... [extdemo]

  1097             ... recipe = zc.recipe.egg:custom

  1098             ... find-links = %(server)s

  1099             ... index = %(server)s/index

  1100             ... include-dirs = include

  1101             ...

  1102             ... """ % dict(server=link_server))

  1103         

  1104             >>> print system(buildout),

  1105             Installing extdemo.

  1106             zip_safe flag not set; analyzing archive contents...

  1107         

  1108         We got the zip_safe warning because the source distribution we used

  1109         wasn't setuptools based and thus didn't set the option.

  1110         

  1111         The egg is created in the develop-eggs directory *not* the eggs

  1112         directory because it depends on buildout-specific parameters and the

  1113         eggs directory can be shared across multiple buildouts.

  1114         

  1115             >>> ls(sample_buildout, 'develop-eggs')

  1116             d  extdemo-1.4-py2.4-unix-i686.egg

  1117             -  z3c.recipe.scripts.egg-link

  1118             -  zc.recipe.egg.egg-link

  1119         

  1120         Note that no scripts or dependencies are installed.  To install

  1121         dependencies or scripts for a custom egg, define another part and use

  1122         the zc.recipe.egg recipe, listing the custom egg as one of the eggs to

  1123         be installed.  The zc.recipe.egg recipe will use the installed egg.

  1124         

  1125         Let's define a script that uses out ext demo:

  1126         

  1127             >>> mkdir('demo')

  1128             >>> write('demo', 'demo.py',

  1129             ... """

  1130             ... import extdemo

  1131             ... def main():

  1132             ...     print extdemo.val

  1133             ... """)

  1134         

  1135             >>> write('demo', 'setup.py',

  1136             ... """