========================
Collection Distributions
========================

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 ``Zope``,
and the release tag is ``Zope-3.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/
          ZConfig/
              __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 Zope 3 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 the same set of metadata files as any other
packages.  Additional information on these files can be found in
`Metadata Descriptions for Distributions <metadata.html>`_.  For
components that aren't Python packages, at least one of
`DEPENDENCIES.cfg`, `PACKAGE.cfg`, or `SETUP.cfg` is required.
                    
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|_.


.. include:: links.rst
