Install multiple Grok apps using zc.buildout

Might be outdated! This document hasn't been reviewed for Grok 1.0 and may be outdated. If you would like to review the document, please read this post. 

Before you start

You will need a clean installation of Python 2.6 (or 2.5) to use. You can either build your own Python from source, or use an existing system Python install and isolate yourself from any system-wide packages using VirtualEnv.

Install a Grok application using zc.buildout

Almost all Grok applications are developed using zc.buildout. You will know if a Grok application has been developed using zc.buildout if you see a file named buildout.cfg at the top level of a project's development directory.

If you see a buildout.cfg file you will also often see a scripot named bootstrap.py or a directory named bootstrap with this file in it. If you don't find this program you can download a copy.

Let's walk through the process of installing the Adder application.

$ svn co svn://svn.zope.org/repos/main/grokapps/Adder Adder
...
$ cd Adder
$ python bootstrap.py
...
$ ./bin/buildout
$ ./bin/zopectl fg

That's it! You should have a complete, running Grok application with just five commands.

Sharing Eggs: Installing multiple Grok applications

Grok requires quite a few Python eggs to be installed. Every Grok application that you try out will require a complete set of eggs to be downloaded over the internet. This can be quite time consuming and takes up disk space. Fortunately, zc.buildout can be configured to put all of the eggs in a common shared directory. When you install your second Grok application using a shared eggs directory it will install very quickly. Running ./bin/buildout to install a new Grok application on a modern computer should only take about five seconds.

To tell zc.buildout that you would like it to use a shared eggs directory, you will need to create a file called default.cfg in the top level of your home directory inside a directory named .buildout. Then you will need to add this text to the file:

[buildout]
eggs-directory = <path-to-shared-eggs>

This path can be to anywhere on your system, the default for grokproject is to use a directory named <your-home-directory>/buildout-eggs, but you can place this anywhere you like.

Faster, buildout, faster!

You can increase the speed of running buildout a little bit more by adding two more options to your ~/.buildout/default.cfg file. The download-cache option will tell buildout to cache the files it downloads from the internet before unpacking them into your eggs directory. The newest option can tell buildout that upon subsequent reruns of the ./bin/buildout command not to use the internet to automatically check for and fetch the newest versions of eggs.

Your final buildout file may look something like this:

[buildout]
newest = false
eggs-directory = /Users/kteague/buildouts/shared/eggs
download-cache = /Users/kteague/buildouts/shared/cache

Keeping bootstrap.py close at hand

If you work frequently with zc.buildout, you may find it handy to keep a single copy of bootstrap.py at hand. You can place this file somewhere on your system, and then on UNIX-like systems create a shell alias to allow you to quickly run bootstrap with your current development version of Python. Place a line such as the following in your shell profile (this is found at ~/.bashrc on Linux, or ~/.profile on Mac OS X):

alias bootit="/Users/kteague/buildouts/shared/python-2.6.0/bin/python \
/Users/kteague/buildouts/shared/bootstrap.py"