Collection Distributions

Overview

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.

Explanation

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:

DEPENDENCIES.cfg
Another optional file containing a list of direct dependencies, as well as any files that are specific to the collection. Each line must be a resource identifier, a comment, or blank.
PACKAGE.cfg
An optional file which describes how the collection distribution should be assembled.
PUBLICATION.cfg
Publication metadata, including many Dublin Core fields and similar information. This is required, but is not expected to change often for a distribution.
SETUP.cfg
Information about what's included in the distrubution, primarily for use by a setup.py script. For components that aren't Python packages, this file is required.

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.

Issues

The following issues are known to exist with the current structure of a collection distribution: