[Zope-CVS] CVS: Packages/zpkgtools/doc - collections.txt:1.1
Fred L. Drake, Jr.
fred at zope.com
Fri Apr 2 16:46:00 EST 2004
Update of /cvs-repository/Packages/zpkgtools/doc
In directory cvs.zope.org:/tmp/cvs-serv12802
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 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
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
The support packages aren't listed for brevity, and because they
really aren't the meaningful part of the payload.
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 metadata, including many Dublin Core fields and similar
information. This is required, but is not expected to change often
for a distribution.
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
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.
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).
More information about the Zope-CVS