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

[Fred L. Drake, Jr.]

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

Added Files:
	zpkg.txt 
Log Message:
document zpkg configuration


=== Added File Packages/zpkgtools/doc/zpkg.txt ===
====================
Configuring **zpkg**
====================

Overview and the Command Line
-----------------------------

Configuration of **zpkg** is required since **zpkg** always refers to
a `resource map` to provide information about the resource its
packaging.  Regardless of the availability of an appropriate checkout,
**zpkg** always uses the resource map to locate the components it's
adding to the release.

The **zpkg** command provides some command line options to control
configuration, and a very simple configuration file to allow
configurations to be saved.

The following command line options are provided:

-C FILE, --configuraion=FILE
  Load the configuration file FILE instead of the default
  configuration file.  FILE must exist.

-f
  Don't load any configuration file, not even the default.

-m MAP, --resource-map=MAP
  Load the resource map MAP before loading any map files identified in
  the configuration file.  Maps identified using **-m** take
  precedence over any identified inthe configuration file.

If neither **-C** nor **-f** is specified on the command line, a
default configuration file is loaded if it exists.  This is
`~/.zpkg/zpkg.conf` on Unix and `~/zpkg/zpkg.conf` on Windows (note
that there's no dot in the directory name for Windows).  The directory
containing the default configuration file can be used to store
resource maps.


Configuration File Format
-------------------------

The configuration files used by **zpkg** use a subset of the
`ZConfig`_ configuration language.

Blank lines and comments (lines that start with ``#`` as the first
non-blank character) are ignored.

The only key currently defined for the configuration file is
``resource-map``.  The value for this key is a path or URL (including
``cvs:`` URLs) for a file that defines the map.  Relative paths are
interpreted as relative to the directory containing the configuration
file.  The ``resource-map`` key may be given any number of times;
entries in the first named map take precedence over entries of the
same name in later maps.

For example, if the configuration file `/home/fdrake/zpkg.conf`
contains::

  resource-map  local.map
  resource-map  cvs://cvs.zope.org/cvs-repository:Packages2/packages.map

**zpkg** will first load the maps in the order:

1. ``/home/fdrake/local.map``
2. ``cvs://cvs.zope.org/cvs-repository:Packages2/packages.map``


Resource Maps
-------------

A `resource map` is a mapping of typed resource names to URLs.  The
URLs will most often be ``cvs:`` or ``repository:`` URLs, but do not
have to be (well, they do for now, but presumably not forever).

Resources are identified by strings of the form:

  [ `type` ":" ] `name`

The optional `type` defaults to ``package``.

The only types known to **zpkg** are ``package`` and ``collection``.
The `name` portion may be used to represent different resources of
different types.  For example, ``collection:ZConfig`` and
``package:ZConfig`` represent two different resources.

A file representing a resource map is a simple two-column table with
the fields separated by writespace.  Blank lines and comments (lines
that start with ``#`` as the first non-blank character) are ignored.

The first field is the name of a resource, and the second field is the
URL by which it can be accessed.

Resource maps which have CVS locations of their own can contain
``repository:`` URLs; the ``cvs:`` URL of the directory containing the
map itself is used as the base for resolving ``repository:`` URLs.


. _ZConfig: http://www.zope.org/Members/fdrake/zconfig/