Collection distributions contain one or more other distributions and the necessary support for installing all of the contained distributions. The zpkg utility can build collection distributions containing package and collection distributions based on dependency information.
Collection distributions are laid out as a directory tree with a specific form. If the primary resource being packaged is ZopeX3, and the release tag is ZopeX3-1_0, we get a tree that looks like this (assuming it has the zope package as a dependency):
ZopeX3-1.0/
Makefile.in
MANIFEST
README.txt
configure
install.py
setup.py
Dependencies/
zope-ZopeX3-1_0/
MANIFEST
setup.cfg
setup.py
zope/
__init__.py
README.txt
version.txt
Support/
setuptools/
__init__.py
...
zpkgtools/
__init__.py
...
ZopeX3/
bin/
mkzeoinstance
mkzopeinstance
zsync
doc/
...
The support packages aren't shown in their entirety, both for brevity and because they really aren't the meaningful part of the payload. The dependency list is assumed to be shorter than actually expected for ZopeX3 as well.
The top-level directory tree is populated by the zpkg tool itself, and does not contain any of the distributed materials. Rather, it contains support material generated by zpkg to make the resulting distribution play the distutils game so it's easy to work with. Additional directories under the top-level directory contain the material being distributed. The distutils support files there (install.py, setup.cfg, MANIFEST) are all generated by zpkg. (The install.py file shown here is simply setup.py renamed to avoid a casual Python programmer using the distutils model when that's not the intention.)
Within the top-level directory, a Dependencies/ directory is created which contains the packages that define the collection. Each component is equivalent to a non-collection package of just the one component.
Collections are defined by a set of metadata files similar to packages. These include:
Additional information on these files can be found in Metadata Descriptions for Distributions.
For each dependency that can be fulfilled (a location is specified in the resource maps loaded by zpkg), an additional directory is added to the Packages/ directory. The new directory will have the same name as the resource being included, with the release tag for component appended following a hyphen; this will normally be the same as the release tag for the collection as a whole. For collections, this directory will have the collection content and any distutils support files needed. For packages, the contents of the directory are exactly the same as they would be for a separate package distribution build with zpkg.
The following issues are known to exist with the current structure of a collection distribution:
In theory, the namespaces for different types of resources are separate, so collections and packages with the same name should be able to coexist. This directory structure doesn't distinguish between them, so that remains theory. The only case we currently need to deal with like this is ZODB: there is a Python package named ZODB, and there's a collection that contains that and a handful of other packages that are normally distributed as part of a separate ZODB distribution (ZEO, zLOG, ZConfig, and a few others). Given this limitation, the collection would need to have a different name (ZODB3 comes to mind).
This isn't enough of a problem to worry about at this point; we just need to keep this in mind when naming components.
We're currently only supporting a limited amount of "package information" for collections, but this is largely a software issue, not a design problem. The information file will be called SETUP.cfg.