[zpkg] SVN: zpkgtools/trunk/doc/ major documentation update;
includes adding a new section on concepts
Fred L. Drake, Jr.
fdrake at gmail.com
Tue Sep 20 14:19:30 EDT 2005
Log message for revision 38539:
major documentation update; includes adding a new section on concepts
and lots of general cleaning up
Changed:
U zpkgtools/trunk/doc/Makefile
A zpkgtools/trunk/doc/all.txt
U zpkgtools/trunk/doc/index.txt
A zpkgtools/trunk/doc/intro.txt
U zpkgtools/trunk/doc/metadata.txt
U zpkgtools/trunk/doc/quickstart.txt
U zpkgtools/trunk/doc/resources.txt
U zpkgtools/trunk/doc/zpkg.txt
-=-
Modified: zpkgtools/trunk/doc/Makefile
===================================================================
--- zpkgtools/trunk/doc/Makefile 2005-09-20 16:04:06 UTC (rev 38538)
+++ zpkgtools/trunk/doc/Makefile 2005-09-20 18:19:29 UTC (rev 38539)
@@ -21,6 +21,7 @@
LOCAL_HTML=\
collections.html \
index.html \
+ intro.html \
metadata.html \
quickstart.html \
resources.html \
Added: zpkgtools/trunk/doc/all.txt
===================================================================
--- zpkgtools/trunk/doc/all.txt 2005-09-20 16:04:06 UTC (rev 38538)
+++ zpkgtools/trunk/doc/all.txt 2005-09-20 18:19:29 UTC (rev 38539)
@@ -0,0 +1,27 @@
+***********************************
+**zpkg** -- The Zope Packaging Tool
+***********************************
+
+:Info: See <http://www.zope.org/Members/fdrake/zpkgtools/> for more information.
+:Author: Fred Drake <fred at zope.com>, Zope Corporation
+
+.. Alternate driver for the zpkg docs.
+ This should be used to format the zpkg docs as a single HTML file
+ for printing. To use, replace links.rst with an empty file and
+ then format this file.
+
+.. _resource maps: `Resource Locations`_
+
+.. _zpkg: `Running the zpkg tool`_
+.. |zpkg| replace:: **zpkg**
+
+.. _ZConfig: http://www.zope.org/Members/fdrake/zconfig/
+
+
+.. include:: intro.txt
+.. include:: quickstart.txt
+.. include:: zpkg.txt
+.. include:: metadata.txt
+.. include:: resources.txt
+.. include:: collections.txt
+.. include:: TODO.txt
Property changes on: zpkgtools/trunk/doc/all.txt
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Name: svn:eol-style
+ native
Modified: zpkgtools/trunk/doc/index.txt
===================================================================
--- zpkgtools/trunk/doc/index.txt 2005-09-20 16:04:06 UTC (rev 38538)
+++ zpkgtools/trunk/doc/index.txt 2005-09-20 18:19:29 UTC (rev 38539)
@@ -5,6 +5,9 @@
Overview
--------
+`zpkg -- The Zope Packaging Tool <intro.html>`_
+ What |zpkg|_ is all about.
+
`Packaging Tool Quick Start <quickstart.html>`_
How to get started with |zpkg|_.
@@ -12,7 +15,7 @@
Essentially a man page for |zpkg|_. This describes command line
options and configuration of the tool.
-`Metadata Descriptions for Distributions <metadata.html>`_
+`Metadata Descriptions for Resources <metadata.html>`_
Descriptions of the metadata files read by |zpkg|_ to allow it to
create distributions from components.
Added: zpkgtools/trunk/doc/intro.txt
===================================================================
--- zpkgtools/trunk/doc/intro.txt 2005-09-20 16:04:06 UTC (rev 38538)
+++ zpkgtools/trunk/doc/intro.txt 2005-09-20 18:19:29 UTC (rev 38539)
@@ -0,0 +1,62 @@
+========
+Overview
+========
+
+The Zope Packaging Tool, or |zpkg|_, is a tool used to build software
+distributions based on the Python ``distutils`` package. The
+generated distributions can be used like any other ``distuils``-based
+distribution.
+
+There are several terms used in this documentation that have specific
+meanings when we use them with regard to packaging. These are the
+definitions we care about here:
+
+**module distribution**
+ A collection of Python modules distributed together as a single
+ downloadable resource and meant to be installed en masse. Examples
+ of some well-known module distributions are Numeric Python, PyXML,
+ PIL (the Python Imaging Library), or mxBase. (This would be called
+ a package, except that term is already taken in the Python context:
+ a single module distribution may contain zero, one, or many Python
+ packages.) (This term is defined in the ``distutils``
+ documentation.)
+
+**collection distribution**
+ A distribution that exists primarily to express a collection of
+ other distributions through dependencies. May include modules or
+ other files, such as documentation or utility scripts.
+
+**application distribution**
+ A distribution that installs an application rather than a set of
+ packages. This distribution does not use the normal distutils
+ setup.py interface, but provides a more conventional **configure** /
+ **make** / **make install** installation pattern (for Unix), or
+ perhaps a platform-specific installer application. This will
+ install the software into an application home (what Zope 2 called
+ the "Zope home").
+
+**package distribution**
+ A distribution that is based on a package, package-contained meta
+ data, and some of the package's sub-packages. This is a
+ package-centric special case of "module distributions", as defined
+ by the distutils documentation. In particular, we will make more
+ assumptions than does distutils, about the arrangement of the
+ information that defines a package distribution.
+
+**resource**
+ A directory containing files that should be packaged as a unit.
+ Packaging metadata for the resource is included within the resource.
+ The directory need not be available on the local filesystem, but may
+ require access to a version control repository.
+
+**primary resource**
+ A resource which defines the contents of a distribution. Any given
+ resource may be primary or not, based on its use by |zpkg|_. There
+ are some additional metadata requirements for a primary resource.
+
+The task of |zpkg|_ is to create distributions based on resource
+metadata that can install the resource and the resources it depends
+on, such that they can actually be used.
+
+
+.. include:: links.rst
Property changes on: zpkgtools/trunk/doc/intro.txt
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Name: svn:eol-style
+ native
Modified: zpkgtools/trunk/doc/metadata.txt
===================================================================
--- zpkgtools/trunk/doc/metadata.txt 2005-09-20 16:04:06 UTC (rev 38538)
+++ zpkgtools/trunk/doc/metadata.txt 2005-09-20 18:19:29 UTC (rev 38539)
@@ -1,10 +1,7 @@
-=======================================
-Metadata Descriptions for Distributions
-=======================================
+===================================
+Metadata Descriptions for Resources
+===================================
-Overview
---------
-
Distributions will be described using a collection of files that
contain different aspects of the relevant metadata. Each of these
files is optional if the information in that file is not needed.
Modified: zpkgtools/trunk/doc/quickstart.txt
===================================================================
--- zpkgtools/trunk/doc/quickstart.txt 2005-09-20 16:04:06 UTC (rev 38538)
+++ zpkgtools/trunk/doc/quickstart.txt 2005-09-20 18:19:29 UTC (rev 38539)
@@ -2,9 +2,6 @@
Packaging Tool Quick Start
==========================
-Overview
---------
-
This is a very brief "getting started" guide to using the Zope 3
package tool, |zpkg|_. We'll start with simple instructions for
building a Zope-3.2.X distribution. These instructions only apply to
@@ -25,8 +22,8 @@
-----------
Before you can build a distribution, you need to have the packaging
-tool itself and at least a minimal configuration. This only needs to
-be done once.
+tool itself. For building Zope 3 distributions, no additional
+configuration is needed.
Use the following command to retrieve the ``zpkgtools`` code from
Subversion::
@@ -38,50 +35,47 @@
PATH; either allows you to simply type |zpkg|_ at the command line to
run the packager.
-You will need to define a *resource map* to tell |zpkg|_ where package
-components can be found. Resource maps can be loaded from local files
-or from remote locations specified by URL. The |zpkg|_ configuration
-file can contain a resource map as well, avoiding the need for a
-separate file. If you are primarily working with the Zope 3 packages,
-you can use a prepared map rather than defining your own.
-The resource maps can be specified from the |zpkg|_ command line or in
-a configuration file. It's generally easiest to work with a
-configuration file since that avoids always needing to use really long
-command lines. The default configuration file is *~/.zkpg/zpkg.conf*
-on Unix or *zpkg\\zpkg.conf* in the *\\Documents and Setting\\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::
+Really Quick Start: The Zope 3 Distribution
+-------------------------------------------
- >>> import os
- >>> os.path.expanduser('~')
- 'C:\\Documents and Settings\\username'
+To build distributions for Zope 3, or other distributions that are
+released from that tree, you don't need any further configuration.
-If you're working with the Zope 3 source code (for Zope 3.2 or newer),
-a sample configuration and resource map are in the checked-out sources
-as *releases/Zope.cfg* and *releases/Zope.map*. Take a look at that
-for a moderately typical configuration.
+The |zpkg|_ configuration for Zope 3 is contained within the Zope 3
+checkout; no additional material is needed. Make sure you have lots
+of disk space in */tmp/* and enough to hold the finished tarball in
+the current directory.
-Read more about resource maps in |zpkg|_, and about how resource
-locations are specified in `Resource Locations <resources.html>`_.
+Switch to the top-level directory of your Zope 3 checkout, and run
+|zpkg|_ using this command::
+ zpkg -C releases/Zope.cfg -vVERSION
-Building a Distribution
------------------------
+After a short while, you should find a very large tarball named
+*Zope-VERSION.tgz* in the current directory.
-Let's start by building a distribution using existing resources and
-metadata. Make sure you have lots of disk space in */tmp/* and enough
-to hold the finished tarball in the current directory.
+That's it.
-Run |zpkg|_ using this command::
+Adding a Windows Installer
+~~~~~~~~~~~~~~~~~~~~~~~~~~
- zpkg -C releases/Zope.cfg -vVERSION
+The recipe for a Windows installer is a bit more complicated, but not
+by much. To do this, switch to the top-level directory of your Zope 3
+checkout, and run |zpkg|_ using a slightly different command::
-After a short while, you should find a very large tarball named
-*Zope-VERSION.tgz* in the current directory.
+ zpkg -C releases/Zope.cfg -vVERSION -t
+Note the addition of the **-t** parameter; this causes |zpkg|_ to
+create an unpacked directory tree instead of a tarball. Switch to
+that directory (name *Zope-VERSION*) and use distutils to create a
+Windows installer::
+ python install.py bdist_wininst
+
+The installer will be an executable file in the *dist* directory.
+
+
Defining a New Resource
-----------------------
Modified: zpkgtools/trunk/doc/resources.txt
===================================================================
--- zpkgtools/trunk/doc/resources.txt 2005-09-20 16:04:06 UTC (rev 38538)
+++ zpkgtools/trunk/doc/resources.txt 2005-09-20 18:19:29 UTC (rev 38539)
@@ -5,9 +5,6 @@
.. This is a reStructuredText document.
.. include:: links.rst
-Overview
---------
-
The |zpkg|_ tool uses URLs to identify external resources. In most
cases, any URL type supported by Python's ``urllib2`` module is
supported if the identified resource is a simple file. (Directories
Modified: zpkgtools/trunk/doc/zpkg.txt
===================================================================
--- zpkgtools/trunk/doc/zpkg.txt 2005-09-20 16:04:06 UTC (rev 38538)
+++ zpkgtools/trunk/doc/zpkg.txt 2005-09-20 18:19:29 UTC (rev 38539)
@@ -21,7 +21,7 @@
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/ZopeX3`).
+ `/usr/local/Zope`).
-c, --collection
Collect dependencies as well as the resource named on the command
@@ -30,7 +30,8 @@
-C FILE, --configuraion=FILE
Load the configuration file `FILE` instead of the default
- configuration file. `FILE` must exist.
+ 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
@@ -117,132 +118,155 @@
for a single distribution.
-Configuration File Format
--------------------------
+Configuration File
+------------------
-The configuration files used by **zpkg** use the
-`ZConfig`_ configuration language.
+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.
-If **build-application** is 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.
+The following settings are available in **zpkg** configuration files:
-Setting **collect-dependencies** 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.
+**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.
-The **default-collection** value is used to specify a resource that
-should be used as the top-level collection to package if no collection
-is specified 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.
-The **distribution-class** setting is used to indicate that a
-particular class should be use to create the ``distutils``
-distribution object. **zpkg** provides on 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.
+**default-collection** (resource name)
+ Name of the resource to package by default; a resource named on the
+ command line overrides this setting.
-The **include-support-code** key is used to control 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 (less the test
-code). If false, the right versions of these packages will be assumed
-to be available for import on target systems.
+**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.
-The **release-name** may be set in the configuration file as well;
-this 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.
+**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.
-The value for **resource-map** 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.
+**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.
-For example, if the configuration file `/home/fdrake/zpkg.conf`
-contains::
+**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.
- resource-map local.map
+There are also some sections that can be added to the configuration
+file to provide more structured information:
- <resources>
- somepkg some/relative/path
- </resources>
+**<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.
- resource-map cvs://cvs.zope.org/cvs-repository:Packages2/packages.map
+ 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.
- <resources>
- another some/where/else
- </resources>
+ For example, we can exclude ``zope.interface`` and
+ ``zope.component`` using::
-**zpkg** will first load the maps in the order:
+ <exclude>
+ zope.interface
+ zope.component
+ </exclude>
-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 neither the **<exclude>** section nor the **-x** and
+ **--exclude** command-line options support wildcards. Exclusions do
+ not affect the construction of the *Support/* directory.
-Note that all **<resources>** sections will be processed before any
-external maps are loaded, regardless of ordering.
+**<resources>**
+ Provide a resource map embedded in the configuration file. For
+ example, if the configuration file `/home/fdrake/zpkg.conf`
+ contains::
-The **<support-packages>** 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.
+ resource-map local.map
-For example, using this **<support-packages>** section::
+ <resources>
+ somepkg some/relative/path
+ </resources>
- <support-packages>
- foo
- bar svn://svn.example.net/repo/foo/trunk/src/foo
- </support-packages>
+ resource-map cvs://cvs.zope.org/cvs-repository:Packages2/packages.map
-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.
+ <resources>
+ another some/where/else
+ </resources>
-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.
+ **zpkg** will first load the maps in the order:
-There is an **<exclude>** section in which you can specify the
-packages/resources that should be excluded (in other words not loaded) from
-the package. Every line should specify one package. This is equivalent of
-specifying **-x** or **--exclude** for every excluded package.
+ 1. embedded maps, in their order of appearance
+ 2. ``/home/fdrake/local.map``
+ 3. ``cvs://cvs.zope.org/cvs-repository:Packages2/packages.map``
-If a package is excluded, dependency information is not loaded for
-that package either. Dependencies for that package are only loaded if
-some other package also depends on them, unless they have also been
-excluded explicitly.
+ Note that all **<resources>** sections will be processed before any
+ external maps are loaded, regardless of ordering.
-For example, we can exclude ``zope.interface`` and ``zope.component``
-using::
+**<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.
- <exclude>
- zope.interface
- zope.component
- </exclude>
+ For example, using this **<support-packages>** section::
-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.
+ <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
-------------
More information about the zpkg
mailing list