How to install a new third-party products will depend on whether it is packaged as an egg, or a traditional Zope 2 product.

Installing a traditional Zope 2 product

The easiest way to try out a traditional Zope 2 product is to extract it into the products/ folder inside the buildout. If you see documentation referring to the Products/ folder in a Zope instance, this is the same thing.

However, this approach makes it harder to redistribute your project and share it with other developers. It is often more predictable to let buildout download and install the package for you. You can do this with the [productdistros] section of buildout.cfg. For example, here is how you might install DocFinderTab and CacheFu for your project:

[productdistros]
recipe = plone.recipe.distros
urls =
    http://www.zope.org/Members/shh/DocFinderTab/1.0.2/DocFinderTab-1.0.2.tar.gz
    http://plone.org/products/cachefu/releases/1.1/CacheFu-1.1.tgz
nested-packages =
    CacheFu-1.1.tgz
version-suffix-packages =

Note that CacheFu is distributed as a single directory containing a number of products in sub-directories, so we list it under nested-packages.

As always, if you change buildout.cfg, you must re-run buildout:

$ ./bin/buildout

Installing an egg

So long as an egg has a release in the Cheese Shop or elsewhere, buildout can download and install it, including any explicitly specified dependencies. Simply list the egg, and optionally a version (otherwise, you get the latest available), in the eggs option.

[buildout]
...
eggs = 
    elementtree
    borg.project>=1.0b1,<2.0dev

If you want buildout to search an index other than the Cheese Shop's, you can add a URL to find-links that contains download links for the eggs. In fact, we have already seen an example of this: elementtree is found at http://effbot.org/downloads, not in the Cheese Shop directly. Thus, we have:

[buildout]
...

find-links =
    http://dist.plone.org
    http://download.zope.org/ppix/
    http://download.zope.org/distribution/
    http://effbot.org/downloads

eggs =
    elementtree

We have also listed some of the download locations for Zope and Plone eggs.

Again - re-run buildout for the changes to take effect:

$ ./bin/buildout

Development eggs

If there is not a release for your egg, or you want to track an egg in Subversion, check it out to the src/ directory. Make sure you get the full egg, including the top-level setup.py file. For example, to get the plone.portlets trunk development, egg do:

$ cd src
$ svn co https://svn.plone.org/svn/plone/plone.portlets/trunk plone.portlets

Then, add the following to buildout.cfg:

[buildout]
...
eggs =
    ...
    plone.portlets

develop =
    src/plone.portlets

Note that:

• The develop option contains a relative path to where the source egg is installed. Buildout will expect to find a suitable setup.py in this directory.
  
• Development eggs always take precedence over regular eggs.
• You still need to list the egg name  in the eggs option for it to be installed.
• If you are overriding an egg that ships with Plone, you may need to list it in the eggs section of the [plone] part instead:

[buildout]
...
develop =
    src/plone.portlets

...

[plone]
recipe = plone.recipe.plone
eggs = 
    plone.portlets

This is because plone.recipe.plone is very expilcit about which versions of its various eggs to use, to ensure Plone keeps running as it was released.

Buildout recipes (such as plone.recipe.plone) are distributed as eggs. You can use a development egg of a recipe by listing it under the develop option. There is no need to explicitly list it under the eggs option, since it is referenced by the recipe option of the relevant part.

Managing ZCML files

It is important to realize that Zope will not load configure.zcml files automatically for packages that are not in the Products.* namespace. Instead, you must explicitly reference the package. Buildout can create such a reference (known as a ZCML slug) with the zcml option under the [instance] part. Here is how to ensure that borg.project is available to Zope:

[buildout]
...
eggs =
    elementtree
    borg.project

...

[instance]
...
zcml = 
    borg.project

Should you need to load an overrides.zcml or a meta.zcml, you can use a syntax like:

zcml =
    some.package
    some.package-overrides
    some.package-meta

Policy products

Many developers prefer to create a single "policy product" (also known as a "deployment product") that orchestrates various dependencies. If you have such a product, you may want to include various dependencies directly from the policy product's configure.zcml file, with lines such as:

<configure xmlns="http://namespace.zope.org/zope">

    <include package="borg.project" />

</configure>

In this case, you may still need one slug (using the zcml option as above) for the policy product.