========================
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 <metadata.html>`_.

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:

- 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`.


.. include:: links.rst
