=========================
Running the **zpkg** tool
=========================

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

Configuration of **zpkg** is generally required since **zpkg** always
refers to a `resource map` to provide information about the resource
its packaging.

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

The following command line options are provided:

-a, --application
  Generate an "application" distribution instead of a typical
  distutils distribution.  An application does not have a `setup.py`
  file for distutils, but has a more conventional **configure** /
  **make** / **make install** build process that creates an
  application-specific installation tree (for example,
  `/usr/local/Zope`).

-c, --collection
  Collect dependencies as well as the resource named on the command
  line into a "collection" distribution; the dependencies will be
  installed in addition to the named resource.

-C FILE, --configuraion=FILE
  Load the configuration file `FILE` instead of the default
  configuration file.  No more than one configuration file will ever
  be loaded.  `FILE` must exist.

--distribution CLASS
  Set the distribution class to be used by distutils.  By default, the
  ``zpkgsetup.dist.ZPkgDistribution`` class is used, but this allows
  an alternate class to be used instead.  Alternate classes should be
  very careful that everything initialized in the default class is
  also properly initialized, either by subclassing or implementing the
  required commands directly.

-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 in the configuration file.

-n NAME, --name=NAME
  Use `NAME` as the unversioned name of the resulting distribution.
  If not specified, the name portion of the resource being distributed
  is used for the package name.

-r TAG, --revision-tag=TAG
  Generate the distribution using the revision control tag `TAG`
  instead of the ``HEAD`` tag.  The revision tag is used to generate
  the release version if that's not specified directly and the tag
  follows the Zope Corporation tagging convention (see below).  Note
  that tags are handled according to the typical conventions of the
  revision control system identified by the corresponding resource
  URL.

-s
  Include required support packages in the distribution.  This is the
  default.

-S
  Don't include the required support packages in the distribution.
  This can be used to generate smaller distributions when the
  ``zpkgsetup`` and ``ZConfig`` packages are known to be available on
  target systems.

--support RESOURCE
  Include an additional resource in the Support/ directory of the
  distribution, if the Support/ directory is included at all.  The
  additional resource should normally be a top-level Python package.
  This can be used to provide additional software to be used when
  distutils is running for the distributed package.

-t, --tree
  Build the distribution tree only, but don't create a tarball.  The
  distribution tree will be created in the current directory and will
  be given the same name it would have in the tarball.  A directory of
  that name must not already exist; if it does, it is considered an
  error.

-v VERSION
  Set the version number of the release to `VERSION`.

--version
  Print the version number of **zpkg** and exit.

-x PACKAGE, --exclude=PACKAGE
  Name a resource (usually a Python package) to exclude the from
  distribution.  Dependencies of the named package will be included
  due to `PACKAGE` needing them, but may be included due to an another
  dependency.  This option may be given as many times as needed.
  Package wildcards are not supported.

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.

If the **-f** option is used to disallow reading the configuration
file, the only way to initialize the resource map is by using the
**-m** option.

The command line can include the name of the resource to be packaged
simply by naming it.  If this is not specified on the command line, it
must be specified in the configuration file using the
**default-collection** setting.  Only one resource can be specified
for a single distribution.


Configuration File
------------------

The configuration files used by **zpkg** use the `ZConfig`_
configuration language.  By default, **zpkg** looks for a
configuration file at *~/.zkpg/zpkg.conf* on Unix or *zpkg\\zpkg.conf*
in the *\\Documents and Settings\\username* folder on Windows.  The
exact name of the folder on Windows depends on the native language
settings; you can determine the actual location using the Python
interpreter::

  >>> import os
  >>> os.path.expanduser('~')
  'C:\\Documents and Settings\\username'

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

There are several keys and sections which can be used in the
configuration file.  Everything is optional.

The following settings are available in **zpkg** configuration files:

**build-application** (boolean)
  If set to **true**, then an application distribution is constructed
  instead of a conventional distutils distribution; this is equivalent
  to specifying **-a** on the command line.

**collect-dependencies** (boolean)
  Setting to **true** causes dependencies to be added to the
  distribution if they can be located.  This is the same as using the
  **-c** option on the command line.

**default-collection** (resource name)
  Name of the resource to package by default; a resource named on the
  command line overrides this setting.

**distribution-class** (class name)
  Use the class identified by this dotted name to create the
  ``distutils`` distribution object.  **zpkg** provides one that
  supports the **zpkg** extensions, but an alternate or further
  extended version can be used by setting this.  This is equivalent to
  the **--distribution** command-line option.

**include-support-code** (boolean)
  Controls whether **zpkg** bundles the support code along with the
  resulting distribution.  The value is a boolean, where the strings
  **true** and **false** can be used in the configuration file.  If
  true (the default), copies of the ``zpkgsetup`` and ``ZConfig``
  packages and any additionally configured support packages will be
  included in the distribution; this is equivalent to the **-s**
  command-line option.  If false, the right versions of these
  packages will be assumed to be available for import on target
  systems; this is equivalent to the **-S** command-line option.

**release-name** (string)
  This name specifies the external name of the release, which can
  differ from the name of the resource being released.  This is
  equivalent to the **-n** and **--name** command-line options.  This
  should normally be used only in configuration files used to create
  distribution for a single product.

**resource-map** (URL reference)
  This is a path or URL (including URLs for revision-controlled
  resources) 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.  This is equivalent to the
  **-m** command-line option.

There are also some sections that can be added to the configuration
file to provide more structured information:

**<exclude>**
  Specify resources that should not be included in the distribution.
  Every line should specify one package. This is equivalent of
  specifying **-x** or **--exclude** for every excluded package.

  If a package is excluded, dependency information is not loaded for
  that package either.  The dependencies for that package are only
  included if some other package also depends on them, unless they
  have also been excluded explicitly.

  For example, we can exclude ``zope.interface`` and
  ``zope.component`` using::

    <exclude>
      zope.interface
      zope.component
    </exclude>

  Note that neither the **<exclude>** section nor the **-x** and
  **--exclude** command-line options support wildcards.  Exclusions do
  not affect the construction of the *Support/* directory.

**<resources>**
  Provide a resource map embedded in the configuration file.  For
  example, if the configuration file `/home/fdrake/zpkg.conf`
  contains::

    resource-map  local.map

    <resources>
      somepkg  some/relative/path
    </resources>

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

    <resources>
      another  some/where/else
    </resources>

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

  1. embedded maps, in their order of appearance
  2. ``/home/fdrake/local.map``
  3. ``cvs://cvs.zope.org/cvs-repository:Packages2/packages.map``

  Note that all **<resources>** sections will be processed before any
  external maps are loaded, regardless of ordering.

**<support-packages>**
  This section can be used to add additional packages to the
  *Support/* directory of the generated distribution.  Within this
  section, each key specifies a Python package which should be added
  to the support area.  If a value is given for the key, that is used
  as the location from which the resource should be loaded.  If no
  location is specified, the global resource map is used; this is
  equivalent to using the **--support** command-line option.

  For example, using this **<support-packages>** section::

    <support-packages>
      foo
      bar  svn://svn.example.net/repo/foo/trunk/src/foo
    </support-packages>

  would cause the ``foo`` package to be located using the global
  resource map, but the ``bar`` package to be loaded from the specied
  location, without regard for the global resource map.

  Note that when using the **<support-packages>** section, packages
  are always added to the *Support/* directory (they cannot be removed
  from the command line), but the **-s** and **-S** options still
  control whether the support directory is included in the
  distribution at all.


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

A `resource map` is a mapping of resource names to URLs.  The URLs
will most often be ``cvs:``, ``svn:``, or ``file:`` URLs, but do not
have to be.  See `Resource Locations <resources.html>`_ for more
information on using URLs for specific locations.  Relative URLs are
resolved relative to the file containing the reference.

Resources are identified by names without any whitespace; if the
resource is a Python package, the resource name is the full package
name (``ZConfig`` or ``zope.app.tree`` for example).  Resource names
must be unique.

A file representing a resource map is a simple two-column table with
the fields separated by whitespace.  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.

For resources which are Python packages, a shortcut syntax can be used
to identify an entire tree of packages::

  foo    svn://svn.example.org/myproject/tags/*/src/foo
  foo.*  svn://svn.example.org/myproject/tags/*/src/foo/

allows all descendent packages of ``foo`` to be located.  Note that
``*`` alone is not accepted as a wildcard package specification.


Zope Corporation Tagging Convention
-----------------------------------

When **zpkg** is passed a **-r**/**--revision-tag** option but not a
**-v** option to explicitly set a version for the release, it will
attempt to generate a version number from the revision tag.  For this
to be successful, the revision tag must follow a convention used
within Zope Corporation.

Release tags which follow this convention all have the form:

  *name*-*encoded_version*

where *name* is the name of the package being released and
*encoded_version* is the result of a simple transformation of the
version number.  **zpkg** doesn't ever care about the name used in the
tag, only about the version information.  It is significant that the
version information follows the last hyphen in the tag name; it *must*
be the last part of the tag.  The encoding for theh version number is
very simple: any underscores in the tag name are converted to dots to
get the actual version number.  Existing dots in the encoded version
number are not changed.  This allows using a version number like
``ZConfig-2.3.1`` in Subversion, where dots are allowed in tags names
(since there's no special interpretation of names), while
``ZConfig-2_3_1`` would be required in CVS, since dots are not allowed
in version names.  The version number must conform to a pattern of two
to four numbers separated by periods, optionally followed by one or
more letters, which in turn may be optionally followed by another
number.  Reasonable examples include ``1.0``, ``0.1``, ``1.1.42``,
``2.3.4.5``, ``1.0a``, ``1.0a1``, and ``5.4.3beta2``.

For example, for the package ``mypkg``, the following tags correspond
to the following version numbers:

==================  ============
Tag                 Version
==================  ============
mypkg-1_0           1.0
mypkg-0.1           0.1
mypkg-1_1_42        1.1.42
mypackage-2_3.4_5   2.3.4.5
mypkg-1_0a          1.0a
mypkg-1_0a1         1.0a1
mypkg-5_4_3_0beta2  5.4.3.0beta2
==================  ============


Support Packages
----------------

**zpkg** creates distributions which require some additional support
packages to operate properly.  These packages are located in a similar
way to packages that go into the distribution.  An internal map is
used first, followed by the resource map based on the configuration
files.

The sources for the ``zpkgsetup`` and ``ZConfig`` packages are the
copies provided as part of the running **zpkg**; a location only needs
to be specified for additional packages that should appear in the
support directory.

.. include:: links.rst
