[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