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