| 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 |
| | 5 | Building a plone 3.3.x demo site |
