Saturday, July 10, 2010

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

  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) ['']:
Enter url (URL of homepage) ['']:
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 to ./buildout_example/buildout_example/
  Copying setup.cfg to ./buildout_example/setup.cfg
  Copying setup.py_tmpl to ./buildout_example/
Running /home/lowks/virtualenv/pylons/bin/python 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 Your now will look something like this:

from setuptools import setup, find_packages
import sys, os

version = '0.1'

      description="Buildout Example",
Buildout Example""",
      classifiers=[], # Get strings from
      keywords='buildout example',
      author='Low Kian Seong',
      packages=find_packages(exclude=['ez_setup', 'examples', 'tests']),
          # -*- Extra requirements: -*-
      # -*- Entry points: -*-

Wow! How did that just happen ?? Well the paster script as promised did all the heavy lifting and filled up the 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.

1 comment:

Anonymous said...

Thing is, to go this route you already have to have a virtualenv with paster and buildout installed. Which is a very sensible thing to have, I suppose.

I like starting from a blank slate: system python, with just python-setuptools installed (which contains Distribute rather than setuptools in Ubuntu nowadays). Then it goes like this:

mkdir newpkg
cd newpkg
bzr init (or the equivalent git/hg incantation)
mkdir -p src/newpkg
touch src/newpkg/
vim (cargo-cult from another package)
vim buildout.cfg (cargo-cult again)
wget (Google it)
bzr add
python && bin/buildout
bzr ignore bin parts eggs and other nonsense

I'm almost at the point where I could write a simple buildout.cfg without cargo-culting; I strongly believe is impossible for mere mortals to write without referring to documentation. And don't get me started on