.. _ref-buildout:

========
Buildout
========

Intro
=====

The de facto Pinax_ build process has a couple manual steps but the
bulk of the work is done by the ``pinax-boot.py`` script. The 0.7
series introduced the use of pip_ which installs python parts into the
``site-packages`` directory, presuming a virtualenv_ to avoid
polluting the system python.

Many folks like using `zc.buildout`_, a generic tool frequently used to
build projects, especially when there are a number of components
involved. It came from the Zope_ world and is heavily used by the Plone_
community for building sites. Rather than installing libraries into
``site-packages``, interpreters and running systems have their sys.path
set to include all the eggs and libraries and parts as required by the
buildout definitions.

The Django_ community has typically not been big on using buildout_,
but recently Jacob Kaplan-Moss has written a couple_ enthusiastic
tutorials_ on how to use it.

Pinax has many many components so it seems a natural candidate for
buildout.

Virtualenv (optional)
=====================

In the bad old days developers installed libraries into the system
Python's ``site-packages``; your operating system packager may have
done the same thing for their own needs. This of course leads to
problems akin to "DLL Hell", with different applications needing
different libraries or versions.

Virtualenv creates a private copy of your python with its own
``site-packages`` directory so you can install as a normal user and each
project can have it's own set of libraries.

I tend to install a very minimal set of critical tools into my system
python: setuptools and virtualenv.  All my application's libraries are
installed into the running code's sys.path by buildout, so I don't end
up with conflicts.

If, however, you do keep a bunch of libraries in your system
``site-packages``, they will be visible to an application you create with
buildout -- buildout doesn't isolate you from ``site-packages`` [`why
not?`_].  It's safest to create a virtual environment::

  virtualenv --no-site-packages .

The dot indicates to create the virtualenv in this current directory,
where our Pinax build will be done. Then activate it::

  source bin/activate

Now when you say "python" it should get your private python.

Building
========

Before you can start to bootstrap the buildout you need to get the necessary
files by cloning the Git repository `pinax-buildout`_::

    $ git clone git://github.com/pinax/pinax-buildout.git

Since it's a good idea to create a new buildout for each Pinax based project
don't hesitate to rename the ``pinax-buildout`` directory to your liking.

.. _pinax-buildout: http://github.com/pinax/pinax-buildout/

Bootstrap
---------

If you created and activated a virtual python, or want to use the
system one that's on your PATH, bootstrap the buildout::

  $ python bootstrap.py

If you create a private python or need to use a specific one (e.g., a
non-default python version) do something like::

  $ /path/to/specific/python bootstrap.py

This creates the bin/buildout command used next::

  Creating directory '/path/to/pinax-buildout/bin'.
  Creating directory '/path/to/pinax-buildout/parts'.
  Creating directory '/path/to/pinax-buildout/eggs'.
  Creating directory '/path/to/pinax-buildout/develop-eggs'.
  Generated script '/path/to/pinax-buildout/bin/buildout'.

You should only need to do this once, before you run your buildout.

Buildout
--------

Now you can run the buildout. It uses the configuration ``buildout.cfg``
file to drive the build.  You can create layered buildout config files,
like for the project base then variants for development and
deployment, but we'll only worry about a single configuration here.

The ``buildout.cfg`` file specifies various parts and
dependencies. Run the buildout with a bit of verbosity like::

  $ bin/buildout -v

  Installing 'zc.buildout', 'setuptools'.
  ...
  Generated script '/path/to/pinax-buildout/bin/ipython'.
  Generated script '/path/to/pinax-buildout/bin/pinax-admin'.
  Generated script '/path/to/pinax-buildout/bin/django-admin'.

Since our ``buildout.cfg`` specifies a lot of pieces needed by Pinax,
this can take a little time the first time its run. Subsequent times
should take less time.

I've specified parts in the buildout to build pieces that can be a bit
troublesome, specifically PIL_ and the zlib_ that it depends on.

When finished, the buildout creates a ``bin/django-admin`` command that's
analogous to Django's ``django-admin.py``.  It also creates a
``bin/pinax-admin`` script to call
:ref:`clone_project <customization-cloneproject>` for example.

You will need to re-rerun this if you modify the ``buildout.cfg`` --
perhaps to add other components your application needs.

Running
=======

After your buildout completes, you can use the ``bin/django-admin`` commands
as to initialize your database and run your site.

Syncdb
------

At this point you should have the ``bin/pinax`` command and be able to
create your database from the Pinax models::

  $ bin/django-admin syncdb

Runserver
---------

Then you can run your application::

  $ bin/django-admin runserver

Python Interpreter
------------------

The buildout also creates a python interpreter that has all the eggs
and libraries configured into it, which you can run like::

  $ bin/python

.. _Pinax: http://pinaxproject.com/
.. _pip: http://pypi.python.org/pypi/pip
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _zc.buildout: http://pypi.python.org/pypi/zc.buildout
.. _Zope: http://www.zope.org/
.. _Plone: http://plone.org/
.. _Django: http://www.djangoproject.com/
.. _buildout: http://www.buildout.org/
.. _tutorials: http://jacobian.org/writing/more-buildout-notes/
.. _couple: http://jacobian.org/writing/django-apps-with-buildout/
.. _djangorecipe: http://pypi.python.org/pypi/djangorecipe
.. _why not?: http://svn.zope.org/zc.buildout/trunk/buildout.cfg?rev=97819&view=rev
.. _PIL: http://www.pythonware.com/products/pil/
.. _zlib: http://www.zlib.net/