source: TI12-security/trunk/NDGSecurity/python/buildout/ndgsecurity/eggs/zc.buildout-1.2.1-py2.5.egg/README.txt @ 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/README.txt@7081
Revision 7081, 5.9 KB checked in by pjkersha, 11 years ago (diff)
  • Property svn:keywords set to Id
Line 
1********
2Buildout
3********
4
5.. contents::
6
7The Buildout project provides support for creating applications,
8especially Python applications.  It provides tools for assembling
9applications from multiple parts, Python or otherwise.  An application
10may actually contain multiple programs, processes, and configuration
11settings.
12
13The word "buildout" refers to a description of a set of parts and the
14software to create and assemble them.  It is often used informally to
15refer to an installed system based on a buildout definition.  For
16example, if we are creating an application named "Foo", then "the Foo
17buildout" is the collection of configuration and application-specific
18software that allows an instance of the application to be created.  We
19may refer to such an instance of the application informally as "a Foo
20buildout".
21
22To get a feel for some of the things you might use buildouts for, see
23the `Buildout examples`_.
24
25To lean more about using buildouts, see `Detailed Documentation`_.
26
27Recipes
28*******
29
30Existing recipes include:
31
32`zc.recipe.egg <http://pypi.python.org/pypi/zc.recipe.egg>`_
33   The egg recipe installes one or more eggs, with their
34   dependencies.  It installs their console-script entry points with
35   the needed eggs included in their paths.
36
37`zc.recipe.testrunner <http://pypi.python.org/pypi/zc.recipe.testrunner>`_
38   The testrunner egg creates a test runner script for one or
39   more eggs.
40
41`zc.recipe.zope3checkout <http://pypi.python.org/pypi/zc.recipe.zope3checkout>`_
42   The zope3checkout recipe installs a Zope 3 checkout into a
43   buildout.
44
45`zc.recipe.zope3instance <http://pypi.python.org/pypi/zc.recipe.zope3instance>`_
46   The zope3instance recipe sets up a Zope 3 instance.
47
48`zc.recipe.filestorage <http://pypi.python.org/pypi/zc.recipe.filestorage>`_
49   The filestorage recipe sets up a ZODB file storage for use in a
50   Zope 3 instance created by the zope3instance recipe.
51
52Buildout examples
53*****************
54
55Here are a few examples of what you can do with buildouts.  We'll
56present these as a set of use cases.
57
58Try out an egg
59==============
60
61Sometimes you want to try an egg (or eggs) that someone has released.
62You'd like to get a Python interpreter that lets you try things
63interactively or run sample scripts without having to do path
64manipulations.  If you can and don't mind modifying your Python
65installation, you could use easy_install, otherwise, you could create
66a directory somewhere and create a buildout.cfg file in that directory
67containing::
68
69  [buildout]
70  parts = mypython
71
72  [mypython]
73  recipe = zc.recipe.egg
74  interpreter = mypython
75  eggs = theegg
76
77where theegg is the name of the egg you want to try out.
78
79Run buildout in this directory.  It will create a bin subdirectory
80that includes a mypython script.  If you run mypython without any
81arguments you'll get an interactive interpreter with the egg in the
82path. If you run it with a script and script arguments, the script
83will run with the egg in its path.  Of course, you can specify as many
84eggs as you want in the eggs option.
85
86If the egg provides any scripts (console_scripts entry points), those
87will be installed in your bin directory too.
88
89Work on a package
90=================
91
92I often work on packages that are managed separately.  They don't have
93scripts to be installed, but I want to be able to run their tests
94using the `zope.testing test runner
95<http://www.python.org/pypi/zope.testing>`_.  In this kind of
96application, the program to be installed is the test runner.  A good
97example of this is `zc.ngi <http://svn.zope.org/zc.ngi/trunk/>`_.
98
99Here I have a subversion project for the zc.ngi package.  The software
100is in the src directory.  The configuration file is very simple::
101
102  [buildout]
103  develop = .
104  parts = test
105
106  [test]
107  recipe = zc.recipe.testrunner
108  eggs = zc.ngi
109
110I use the develop option to create a develop egg based on the current
111directory.  I request a test script named "test" using the
112zc.recipe.testrunner recipe.  In the section for the test script, I
113specify that I want to run the tests in the zc.ngi package.
114
115When I check out this project into a new sandbox, I run bootstrap.py
116to get setuptools and zc.buildout and to create bin/buildout.  I run
117bin/buildout, which installs the test script, bin/test, which I can
118then use to run the tests.
119
120This is probably the most common type of buildout.
121
122The `zc.buildout project <http://svn.zope.org/zc.buildout/trunk>`_
123is a slightly more complex example of this type of buildout.
124
125Install egg-based scripts
126=========================
127
128A variation of the `Try out an egg`_ use case is to install scripts
129into your ~/bin directory (on Unix, of course).  My ~/bin directory is
130a buildout with a configuration file that looks like::
131
132
133  [buildout]
134  parts = foo bar
135  bin-directory = .
136
137  [foo]
138  ...
139
140where foo and bar are packages with scripts that I want available.  As
141I need new scripts, I can add additional sections.  The bin-directory
142option specified that scripts should be installed into the current
143directory.
144
145Multi-program multi-machine systems
146===================================
147
148Using an older prototype version of the buildout, we've build a number
149of systems involving multiple programs, databases, and machines.  One
150typical example consists of:
151
152- Multiple Zope instances
153
154- Multiple ZEO servers
155
156- An LDAP server
157
158- Cache-invalidation and Mail delivery servers
159
160- Dozens of add-on packages
161
162- Multiple test runners
163
164- Multiple deployment modes, including dev, stage, and prod,
165  with prod deployment over multiple servers
166
167Parts installed include:
168
169- Application software installs, including Zope, ZEO and LDAP
170  software
171
172- Add-on packages
173
174- Bundles of configuration that define Zope, ZEO and LDAP instances
175
176- Utility scripts such as test runners, server-control
177  scripts, cron jobs.
178
179Questions and Bug Reporting
180***************************
181
182Please send questions and comments to the
183`distutils SIG mailing list <mailto://distutils-sig@python.org>`_.
184
185Report bugs using the `zc.buildout Launchpad Bug Tracker
186<https://launchpad.net/products/zc.buildout/+bugs>`_.
187
Note: See TracBrowser for help on using the repository browser.