README.txt 6.07 KB
Newer Older
Jim Fulton's avatar
Jim Fulton committed
1 2 3
********
Buildout
********
4

5 6
.. contents::

Jim Fulton's avatar
Jim Fulton committed
7
The Buildout project provides support for creating applications,
8
especially Python applications.  It provides tools for assembling
9 10 11 12 13
applications from multiple parts, Python or otherwise.  An application
may actually contain multiple programs, processes, and configuration
settings.

The word "buildout" refers to a description of a set of parts and the
Jim Fulton's avatar
Jim Fulton committed
14
software to create and assemble them.  It is often used informally to
15 16 17 18 19 20 21
refer to an installed system based on a buildout definition.  For
example, if we are creating an application named "Foo", then "the Foo
buildout" is the collection of configuration and application-specific
software that allows an instance of the application to be created.  We
may refer to such an instance of the application informally as "a Foo
buildout".  

Jim Fulton's avatar
Jim Fulton committed
22 23
To get a feel for some of the things you might use buildouts for, see
the `Buildout examples`_.
24

Jim Fulton's avatar
Jim Fulton committed
25
To lean more about using buildouts, see `Detailed Documentation`_.
Jim Fulton's avatar
Jim Fulton committed
26

27
Download
Jim Fulton's avatar
Jim Fulton committed
28
********
29 30 31 32 33

You can download zc.buildout and many buildout recipes from the
`Python Package Index <http://www.python.org/pypi>`_.

Recipes
Jim Fulton's avatar
Jim Fulton committed
34
*******
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58

Existing recipes include:

`zc.recipe.egg <http://dev.zope.org/Buildout/egg.html>`_
   The egg recipe installes one or more eggs, with their
   dependencies.  It installs their console-script entry points with
   the needed eggs included in their paths.

`zc.recipe.testrunner <http://dev.zope.org/Buildout/testrunner.html>`_
   The testrunner egg installs creates a test runner script for one or
   more eggs.

`zc.recipe.zope3checkout <http://dev.zope.org/Buildout/zope3checkout.html>`_
   The zope3checkout recipe installs a Zope 3 checkout into a
   buildout.

`zc.recipe.zope3instance <http://dev.zope.org/Buildout/zope3instance.html>`_
   The zope3instance recipe sets up a Zope 3 instance.

`zc.recipe.filestorage <http://dev.zope.org/Buildout/filestorage.html>`_
   The filestorage recipe sets up a ZODB file storage for use in a
   Zope 3 instance creayed by the zope3instance recipe.

Buildout examples
Jim Fulton's avatar
Jim Fulton committed
59
*****************
60

Jim Fulton's avatar
Jim Fulton committed
61 62 63 64 65
Here are a few examples of what you can do with buildouts.  We'll
present these as a set of use cases.

Try out an egg
==============
66

Jim Fulton's avatar
Jim Fulton committed
67 68 69 70 71 72 73
Sometimes you want to try an egg (or eggs) that someone has released.
You'd like to get a Python interpreter that lets you try things
interactively or run sample scripts without having to do path
manipulations.  If you can and don't mind modifying your Python
installation, you could use easy_install, otherwise, you could create
a directory somewhere and create a buildout.cfg file in that directory
containing::
74

Jim Fulton's avatar
Jim Fulton committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183
  [buildout]
  parts = mypython

  [mypython]
  recipe = zc.recipe.egg
  interpreter = mypython
  eggs = theegg

where theegg is the name of the egg you want to try out.

Run buildout in this directory.  It will create a bin subdirectory
that includes a mypython script.  If you run mypython without any
arguments you'll get an interactive interpreter with the egg in the
path. If you run it with a script and script arguments, the script
will run with the egg in its path.  Of course, you can specify as many
eggs as you want in the eggs option.

If the egg provides any scripts (console_scripts entry points), those
will be installed in your bin directory too.

Work on a package
=================

I often work on packages that are managed separately.  They don't have
scripts to be installed, but I want to be able to run their tests
using the `zope.testing test runner
<http://www.python.org/pypi/zope.testing>`_.  In this kind of
application, the program to be instaleld is the test runner.  A good
example of this is `zc.ngi <http://svn.zope.org/zc.ngi/trunk/>`_.

Here I have a subversion project for the zc.ngi package.  The software
is in the src directory.  The configuration file is very simple::

  [buildout]
  develop = .
  parts = test

  [test]
  recipe = zc.recipe.testrunner
  eggs = zc.ngi

I use the develop option to create a develop egg based on the current
directory.  I request a test script named "test" using the
zc.recipe.testrunner recipe.  In the section for the test script, I
specify that I want to run the tests in the zc.ngi package.  

When I check out this project into a new sandbox, I run bootstrap.py
to get setuptools and zc.buildout and create bin/buildout.  I run
bin/buildout, which installs the test script, bin/test, which I can
then use to run the tests.

This is probably the most common type of buildout.

The `zc.buildout project <http://svn.zope.org/zc.buildout/trunk>`_
is a slightly more complex example of this type of buildout.

Install egg-based scripts
=========================

A variation of the `Try out an egg`_ use case is to install scripts
into your ~/bin directory (on Unix, of course).  My ~/bin directory is
a buildout with a configuration file that looks like::


  [buildout]
  parts = foo bar
  bin-directory = .

  [foo]
  ...

whwre foo and bar are packages with scripts that I want available.  As
I need new scripts, I can add additional sections.  The bin-directory
option specified that scripts should be installed into the current
directory. 

Multi-program multi-machine systems
===================================

Using an older prototype version of the buildout, we've build a number
of systems involving multiple programs, databases, and machines.  One
typical example consists of:

- Multiple Zope instances

- Multiple ZEO servers

- An LDAP server

- Cache-invalidation and Mail delivery servers

- Dozens of add-on packages

- Multiple test runners

- Multiple deployment modes, including dev, stage, and prod, 
  with prod deployment over multiple servers

Parts installed include:

- Application software installs, including Zope, ZEO and LDAP
  software

- Add-on packages

- Bundles of configuration that define Zope, ZEO and LDAP instances

- Utility scripts such as test runners, server-control
  scripts, cron jobs.
184

Jim Fulton's avatar
Jim Fulton committed
185 186
Questions and Bug Reporting
***************************
187

Jim Fulton's avatar
Jim Fulton committed
188 189
Please send questions and comments to the  
`distutils SIG mailing list <mailto://distutils-sig@python.org>`_.
190

Jim Fulton's avatar
Jim Fulton committed
191 192
Report bugs using the `zc.buildout Launchpad Bug Tracker
<https://launchpad.net/products/zc.buildout/+bugs>`_.
193