initial commit
[zope-bootstrap.git] / README.txt
1 =======================
2 Using a custom buildout
3 =======================
4
5 Note: If you are using Windows, if you do not have PIL installed, or you are
6 not using Python 2.4 as your main system Python, please see the relevant
7 sections below.
8
9 You probably got here by running something like:
10
11  $ paster create -t plone3_buildout
12
13 Now, you need to run:
14
15  $ python bootstrap.py
16
17 This will install zc.buildout for you.
18
19 To create an instance immediately, run:
20
21  $ bin/buildout
22
23 This will download Plone's eggs and products for you, as well as other
24 dependencies, create a new Zope 2 installation (unless you specified
25 an existing one when you ran "paster create"), and create a new Zope instance
26 configured with these products.
27
28 You can start your Zope instance by running:
29
30  $ bin/instance start
31
32 or, to run in foreground mode:
33
34  $ bin/instance fg
35
36 To run unit tests, you can use:
37
38  $ bin/instance test -s my.package
39
40 Installing PIL
41 --------------
42
43 To use Plone, you need PIL, the Python Imaging Library. If you don't already
44 have this, download and install it from http://www.pythonware.com/products/pil.
45
46 Using a different Python installation
47 --------------------------------------
48
49 Buildout will use your system Python installation by default. However, Zope
50 2.10 (and by extension, Plone) will only work with Python 2.4. You can verify
51 which version of Python you have, by running:
52
53  $ python -V
54
55 If that is not a 2.4 version, you need to install Python 2.4 from
56 http://python.org. If you wish to keep another version as your main system
57 Python, edit buildout.cfg and add an 'executable' option to the "[buildout]"
58 section, pointing to a python interpreter binary:
59
60  [buildout]
61  ...
62  executable = /path/to/python
63
64 Working with buildout.cfg
65 -------------------------
66
67 You can change any option in buildout.cfg and re-run bin/buildout to reflect
68 the changes. This may delete things inside the 'parts' directory, but should
69 keep your Data.fs and source files intact.
70
71 To save time, you can run buildout in "offline" (-o) and non-updating (-N)
72 mode, which will prevent it from downloading things and checking for new
73 versions online:
74
75  $ bin/buildout -Nov
76
77 Creating new eggs
78 -----------------
79
80 New packages you are working on (but which are not yet released as eggs and
81 uploaded to the Python Package Index, aka PYPI) should be placed in src. You can do:
82
83  $ cd src/
84  $ paster create -t plone my.package
85
86 Use "paster create --list-templates" to see all available templates. Answer
87 the questions and you will get a new egg. Then tell buildout about your egg
88 by editing buildout.cfg and adding your source directory to 'develop':
89
90  [buildout]
91  ...
92  develop =
93     src/my.package
94
95 You can list multiple packages here, separated by whitespace or indented
96 newlines.
97
98 You probably also want the Zope instance to know about the package. Add its
99 package name to the list of eggs in the "[instance]" section, or under the
100 main "[buildout]" section:
101
102  [instance]
103  ...
104  eggs =
105     ${buildout:eggs}
106     ${plone:eggs}
107     my.package
108
109 Leave the ${buildout:eggs} part in place - it tells the instance to use the
110 eggs that buildout will have downloaded from the Python Package Index
111 previously.
112
113 If you also require a ZCML slug for your package, buildout can create one
114 automatically. Just add the package to the 'zcml' option:
115
116  [instance]
117  ...
118  zcml =
119     my.package
120
121 When you are finished, re-run buildout. Offline, non-updating mode should
122 suffice:
123
124  $ bin/buildout -Nov
125
126 Developing old-style products
127 -----------------------------
128
129 If you are developing old-style Zope 2 products (not eggs) then you can do so
130 by placing the product code in the top-level 'products' directory. This is
131 analogous to the 'Products/' directory inside a normal Zope 2 instance and is
132 scanned on start-up for new products.
133
134 Depending on a new egg
135 ----------------------
136
137 If you want to use a new egg that is in the Python Package Index, all you need
138 to do is to add it to the "eggs" option under the main "[buildout]" section:
139
140  [buildout]
141  ...
142  eggs =
143     my.package
144
145 If it's listed somewhere else than the Python Package Index, you can add a link
146 telling buildout where to find it in the 'find-links' option:
147
148  [buildout]
149  ...
150  find-links =
151     http://dist.plone.org
152     http://download.zope.org/distribution/
153     http://effbot.org/downloads
154     http://some.host.com/packages
155
156 Using existing old-style products
157 ---------------------------------
158
159 If you are using an old-style (non-egg) product, you can either add it as an
160 automatically downloaded archive or put it in the top-level "products" folder.
161 The former is probably better, because it means you can redistribute your
162 buildout.cfg more easily:
163
164  [productdistros]
165  recipe = plone.recipe.distros
166  urls =
167     http://plone.org/products/someproduct/releases/1.3/someproduct-1.3.tar.gz
168
169 If someproduct-1.3.tar.gz extracts into several products inside a top-level
170 directory, e.g. SomeProduct-1.3/PartOne and SomeProduct-1.3/PartTwo, then
171 add it as a "nested package":
172
173  [productdistros]
174  recipe = plone.recipe.distros
175  urls =
176     http://plone.org/products/someproduct/releases/1.3/someproduct-1.3.tar.gz
177  nested-packages =
178     someproduct-1.3.tar.gz
179
180 Alternatively, if it extracts to a directory which contains the version
181 number, add it as a "version suffix package":
182
183  [productdistros]
184  recipe = plone.recipe.distros
185  urls =
186     http://plone.org/products/someproduct/releases/1.3/someproduct-1.3.tar.gz
187  version-suffix-packages =
188     someproduct-1.3.tar.gz
189
190 You can also track products by adding a new bundle checkout part. It
191 doesn't strictly have to be an svn bundle at all, any svn location will do,
192 and cvs is also supported:
193
194  [buildout]
195  ...
196  parts =
197     plone
198     zope2
199     productdistros
200     myproduct
201     instance
202     zopepy
203
204 Note that "myproduct" comes before the "instance" part. You then
205 need to add a new section to buildout.cfg:
206
207  [myproduct]
208  recipe = plone.recipe.bundlecheckout
209  url = http://svn.plone.org/svn/collective/myproduct/trunk
210
211 Finally, you need to tell Zope to find this new checkout and add it to its
212 list of directories that are scanned for products:
213
214  [instance]
215  ...
216  products =
217     ${buildout:directory}/products
218     ${productdistros:location}
219     ${plonebundle:location}
220     ${myproduct:location}
221
222 Without this last step, the "myproduct" part is simply managing an svn
223 checkout and could potentially be used for something else instead.
224
225 =============
226 Using Windows
227 =============
228
229 To use buildout on Windows, you will need to install a few dependencies which
230 other platforms manage on their own.
231
232 Here are the steps you need to follow (thanks to Hanno Schlichting for these):
233
234 Python (http://python.org)
235 --------------------------
236
237   - Download and install Python 2.4.4 using the Windows installer from
238     http://www.python.org/ftp/python/2.4.4/python-2.4.4.msi
239     Select 'Install for all users' and it will put Python into the
240     "C:\Python24" folder by default.
241
242   - You also want the pywin32 extensions available from
243     http://downloads.sourceforge.net/pywin32/pywin32-210.win32-py2.4.exe?modtime=1159009237&big_mirror=0
244
245   - And as a last step you want to download the Python imaging library available
246     from http://effbot.org/downloads/PIL-1.1.6.win32-py2.4.exe
247
248   - If you develop Zope based applications you will usually only need Python 2.4
249     at the moment, so it's easiest to put the Python binary on the systems PATH,
250     so you don't need to specify its location manually each time you call it.
251
252     Thus, put "C:\Python24" and "C:\Python24\Scripts" onto the PATH. You can
253     find the PATH definition in the control panel under system preferences on
254     the advanced tab at the bottom. The button is called environment variables.
255     You want to add it at the end of the already existing PATH in the system
256     section. Paths are separated by a semicolons.
257
258   - You can test if this was successful by opening a new shell (cmd) and type
259     in 'python -V'. It should report version 2.4.4 (or whichever version you
260     installed).
261
262     Opening a new shell can be done quickly by using the key combination
263     'Windows-r' or if you are using Parallels on a Mac 'Apple-r'. Type in 'cmd'
264     into the popup box that opens up and hit enter.
265
266
267 Subversion (http://subversion.tigris.org)
268 -----------------------------------------
269
270   - Download the nice installer from
271     http://subversion.tigris.org/files/documents/15/35379/svn-1.4.2-setup.exe
272
273   - Run the installer. It defaults to installing into
274     "C:\Program Files\Subversion".
275
276   - Now put the install locations bin subfolder (for example
277     "C:\Program Files\Subversion\bin") on your system PATH in the same way you
278     put Python on it.
279
280   - Open a new shell again and type in: 'svn --version' it should report
281     version 1.4.2 or newer.
282
283
284 MinGW (http://www.mingw.org/)
285 -----------------------------
286
287   This is a native port of the gcc compiler and its dependencies for Windows.
288   There are other approaches enabling you to compile Python C extensions on
289   Windows including Cygwin and using the official Microsoft C compiler, but this
290   is a lightweight approach that uses only freely available tools. As
291   it's used by a lot of people chances are high it will work for you and there's
292   plenty of documentation out there to help you in troubleshooting problems.
293
294   - Download the MinGW installer from
295     http://downloads.sourceforge.net/mingw/MinGW-5.1.3.exe?modtime=1168794334&big_mirror=1
296
297   - The installer will ask you which options you would like to install. Choose
298     base and make here. It will install into "C:\MinGW" by default. The install
299     might take some time as it's getting files from sourceforge.net and you
300     might need to hit 'retry' a couple of times.
301
302   - Now put the install location's bin subfolder (for example "C:\MinGW\bin") on
303     your system PATH in the same way you put Python on it.
304
305   - Test this again by typing in: 'gcc --version' on a newly opened shell and
306     it should report version 3.4.2 or newer.
307
308
309 Configure Distutils to use MinGW
310 --------------------------------
311
312   Some general information are available from
313   http://www.mingw.org/MinGWiki/index.php/Python%20extensions for example but
314   you don't need to read them all.
315
316   - Create a file called 'distutils.cfg' in "C:\Python24\Lib\distutils". Open it
317     with a text editor ('notepad distutils.cfg') and fill in the following lines:
318
319     [build]
320     compiler=mingw32
321
322     This will tell distutils to use MinGW as the default compiler, so you don't
323     need to specify it manually using "--compiler=mingw32" while calling a
324     package's setup.py with a command that involves building C extensions. This
325     is extremely useful if the build command is written down in a buildout
326     recipe where you cannot change the options without hacking the recipe
327     itself. The z2c.recipe.zope2install used in ploneout is one such example.