My easy buildout example Pt. 1

For a long time I could not make heads or tails of buildouts just that I kept on hearing that it's supposed to be very easy to make packages and distribute them. So finally this week end I sat down, rolled up the sleeves and decided to really try and understand what I was missing.

My aim, create the world's easiest package with absolutely nothing in it. All I wanted to do was just understand what is going on.

Firstly I needed to create my own package, for this I let the great python paste script do all the heavy lifting for me:

[lowks@bobot-mdv-ng pylons]$ ./bin/paster create -t basic_package buildout_example
Selected and implied templates:
  PasteScript#basic_package  A basic setuptools-enabled package

Variables:
  egg:      buildout_example
  package:  buildout_example
  project:  buildout_example
Enter version (Version (like 0.1)) ['']: 0.1
Enter description (One-line description of the package) ['']: Buildout Example
Enter long_description (Multi-line description (in reST)) ['']: Buildout Example
Enter keywords (Space-separated keywords/tags) ['']: buildout example
Enter author (Author name) ['']: Low Kian Seong
Enter author_email (Author email) ['']: kianseong@gmail.com
Enter url (URL of homepage) ['']: www.lowkster.com
Enter license_name (License name) ['']: BSD
Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]:
Creating template basic_package
Creating directory ./buildout_example
  Recursing into +package+
    Creating ./buildout_example/buildout_example/
    Copying __init__.py to ./buildout_example/buildout_example/__init__.py
  Copying setup.cfg to ./buildout_example/setup.cfg
  Copying setup.py_tmpl to ./buildout_example/setup.py
Running /home/lowks/virtualenv/pylons/bin/python setup.py egg_info

What the paste script will do is it will ask you a bunch of questions where all the answers is used to fill up your setup.py. Your setup.py now will look something like this:

from setuptools import setup, find_packages
import sys, os

version = '0.1'

setup(name='buildout_example',
      version=version,
      description="Buildout Example",
      long_description="""\
Buildout Example""",
      classifiers=[], # Get strings from http://pypi.python.org/pypi?%3Aaction=list_classifiers
      keywords='buildout example',
      author='Low Kian Seong',
      author_email='kianseong@gmail.com',
      url='www.lowkster.com',
      license='BSD',
      packages=find_packages(exclude=['ez_setup', 'examples', 'tests']),
      include_package_data=True,
      zip_safe=False,
      install_requires=[
          # -*- Extra requirements: -*-
      ],
      entry_points="""
      # -*- Entry points: -*-
      """,
      )

Wow! How did that just happen ?? Well the paster script as promised did all the heavy lifting and filled up the setup.py with all the input you just put in just now. Isn't that magical ?

If you are doing in a virtualenv, do a 'easy_install zc.buildout' to get started on getting all the buildout stuff. Remember that you will definitely find other guides somewhere else to do this. I am just writing this down as an exercise and a reminder to myself.

After you finish installing zc.buildout, to sprinkle the buildout magic in your current source directory, cd into the source directory which for this example would be the buildout_example and then all you have to do is run '../bin/builout init'. It is really really easy!

[lowks@bobot-mdv-ng buildout_example]$ ../bin/buildout init
Creating '/home/lowks/virtualenv/pylons/buildout_example/buildout.cfg'.
Creating directory '/home/lowks/virtualenv/pylons/buildout_example/bin'.
Creating directory '/home/lowks/virtualenv/pylons/buildout_example/parts'.
Creating directory '/home/lowks/virtualenv/pylons/buildout_example/develop-eggs'.
Generated script '/home/lowks/virtualenv/pylons/buildout_example/bin/buildout'.

That's almost it! Thanks to your fairy god mother buildout script, you will find a bunch stuff already created. Most of the guides I read was too heavy as it tried to get too much stuff done now ... so I am going to cover more in the second part. For now just pat your back in that you are 3/4 done! Go have a great cup of puerh tea!

For the next part we will see what each part in the buildout.cfg and at the end we will see how to finish the buildout process plus create a section for nosetests.