Common Launchpad Component Hacking Tips

These hacking tips are common to all Launchpad open-sourced components (i.e., lazr.*). Additional component-specific information may be found in the HACKING.txt file for that component.

You may also want to see the Launchpad Hacking page.

Basics

To develop or run tests, first run $DESIRED_PYTHON bootstrap.py in the package's top level directory, where you replace $DESIRED_PYTHON with the python executable that want to used to build and run this project. A non-system Python is highly recommended, but not required.

Then run ./bin/buildout. (NOTE: Ubuntu Intrepid users, see the note at the bottom of this document if this generates errors.)

You can now run tests with ./bin/test. Use ./bin/test --help to read about the many options.

To gain access to a Python interpreter with the package and its dependent eggs available, use ./bin/py.

You can generate ctags and idutils files for a variety of editors using ./bin/tags (see ./bin/tags --help). The advantage of the files generated from this utility is that they include the sourcecode from the eggs used in this buildout.

To generate distributions, use ./bin/buildout setup . SETUP_CMD [...]. That is, you can use ./bin/buildout setup . as if it were python setup.py. The intended advantage is easy access to a pristine, local version of setuptools.

Global Cache

Every project using zc.buildout will keep its own collection of eggs by default. You may want to cache these eggs, and their downloaded distributions globally. This also allows you to share common eggs across multiple packages. To do this, perform the following instructions:

mkdir -p ~/.buildout/eggs
mkdir ~/.buildout/download-cache

Create ~/.buildout/default.cfg with the following content, replacing "$HOME" with the path to your home::

[buildout]
eggs-directory=$HOME/.buildout/eggs
download-cache=$HOME/.buildout/download-cache

Working with Unreleased Packages

You may want to develop with an unreleased distribution of another package. To do so, you have many options. Here are three.

Source

If you have a source package, you can add it to this buildout (temporarily or, if really appropriate, permanently) as follows.

NOTE: We'll use "this software" to refer to the software/buildout to which you want to add a source package; and "the other software" to refer to the source package that you want to add.

- Add the top-level directory (the one with the setup.py) of the other

• software to somewhere accessible to this software. You might use bzr add, symbolic links, svn externals, or whatever the appropriate tool is for the situation. A reasonable option is to add it in the top-level directory of this software.

- In this software's buildout.cfg, in the [buildout] section, look for a

• develop key. It will probably look like this: develop = .. Edit it to include the directory of the other software. For instance, if you added it at the top level of this software's tree in a folder called "lazr_foo," you would change the line in buildout.cfg to read develop = . lazr_foo.

- Rerun bin/buildout.

Barring version conflicts in your setup.py or buildout configuration (which will be reported as errors when you run bin/buildout`), you should now be using the source version of the dependency. Look at one of the scripts in bin, such as bin/test to verify, if you like.

To undo, remove the line in buildout.conf, remove the other software's directory if necessary for cleanliness, and rerun bin/buildout.

Distribution

If you have a source distribution or an egg, and you set up the download-cache as described in the Global Cache_ section above, you can put the distribution (sdist or egg) in the download-cache's dist directory. Then rerun bin/buildout.

Alternatively, if you have an egg, you can put it in your eggs directory, or in the shared eggs directory as described in the Global Cache_ section, if you are using that. The rerun bin/buildout.

In both cases, to undo, you must remove the egg from the local or shared eggs directory. If you used the download-cache/dist directory, you must also remove it from there.

Private Source

If you want to distribute a source distribution privately, see http://pypi.python.org/pypi/zc.buildoutsftp/.

References

There is much, much more to learn about zc.buildout. It works well for small packages, but is even better for big projects. For more information about zc.buildout:

- http://grok.zope.org/documentation/tutorial/introduction-to-zc.buildout

• Presentation notes of an introduction to zc.buildout by its author, Jim Fulton.

- http://pypi.python.org/pypi/zc.buildout

• The user manual.

Ubuntu Intrepid Problem

Intrepid has a bug working with buildout. You may have to hack to fix it. Here's an example of the Python 2.4 version of the hack.

$ sudo rm /usr/lib/python2.4/site-packages/GMenuSimpleEditor/*.py $ sudo ln -s /var/lib/python-support/python2.4/GMenuSimpleEditor/*.py /usr/lib/python2.4/site-packages/GMenuSimpleEditor/

Python 2.5 would need the same kind of fix (replace all three instances of "python2.4" with "python2.5" in the above).

The author of this document tried an Intrepid upgrade and an aptitude reinstall of python-gmenu to no avail before doing the rough-and-tumble change described above.

See https://bugs.edge.launchpad.net/ubuntu/+source/gnome-menus/+bug/301571 and the bug linked to it by datakid.

Bazaar Configuration

When hacking on LAZR it's useful to have the put something like this in your bazaar .location.conf file:

# This is the directory containing all the LAZR projects you are hacking on.
# This could be a shared repository, or you can make each subdirectories a
# shared repository.
[/home/<yourname>/canonical]
email = Me <me@example.com>
pqm_email = Canonical PQM <launchpad@pqm.canonical.com>
push_location = bzr+ssh://bazaar.launchpad.net/~yourlpnick
push_location:policy = appendpath
public_branch = bzr+ssh://bazaar.launchpad.net/~yourlpnick
public_branch:policy = appendpath
submit_to = merge@code.launchpad.net
mail_client = editor

# You then add the following two stanzas for each LAZR project
[/home/<yourname>/canonical/lazr.config]
submit_branch = /home/<yourname>/canonical/lazr.config/trunk

[/home/<yourname>/canonical/lazr.config/trunk]
public_branch = bzr+ssh://bazaar.launchpad.net/~launchpad-pqm/lazr.config/trunk

# You should then be able to bzr push/send in any branches.