[Zope-CVS] CVS: Packages/zpkgtools/doc - collections.txt:1.1

[Fred L. Drake, Jr.]

Update of /cvs-repository/Packages/zpkgtools/doc
In directory cvs.zope.org:/tmp/cvs-serv12802

Added Files:
	collections.txt 
Log Message:
start describing what can be found in a collection distribution; this
doesn't exactly match the implementation, but this is what the
implementation *should* be doing


=== Added File Packages/zpkgtools/doc/collections.txt ===
========================
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
``Collection``, and the version number assigned is ``1.0``, we get a
tree that looks like this (assuming it has the ``zope`` package as a
dependency)::

  Collection-1.0/
      MANIFEST
      setup.cfg
      setup.py
      Collection/
          DEPENDENCIES.txt
          MANIFEST
          PUBLICATION.txt
          README.txt
          setup.cfg
          setup.py
      zope/
          MANIFEST
          PUBLICATION.txt
          setup.cfg
          setup.py
          zope/
              __init__.py
              README.txt
              version.txt

The support packages aren't listed for brevity, and because they
really aren't the meaningful part of the payload.


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
(`setup.py`, `setup.cfg`, `MANIFEST`) are all generated by **zpkg**.

Within the top-level directory, a directory is created which contains
the files of the collection itself (`Collection/` in this example).
Collections are defined by a set of metadata files similar to
packages.  These include:

`PUBLICATION.txt`
  Publication metadata, including many Dublin Core fields and similar
  information.  This is required, but is not expected to change often
  for a distribution.

`INCLUDES.txt`
  An optional file which describes what files should be added to the
  collection itself from other locations (this is normally expected to
  be documentation files or scripts).  It is also possible to specify
  that files in the collection should not be included in
  distributions.

`DEPENDENCIES.txt`
  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 or a comment.

Additional files may be present in a collection; these are copied into
the collection-specific directory directly unless `INCLUDES.txt`
indicates they should not be distributed.  The `README.txt` file in
this example is such a file.


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