[zpkg] SVN: zpkgtools/trunk/doc/ lots of updates based on
proofreading and adding missing information
Fred L. Drake, Jr.
fdrake at gmail.com
Tue Sep 13 23:50:03 EDT 2005
Log message for revision 38461:
lots of updates based on proofreading and adding missing information
Changed:
U zpkgtools/trunk/doc/collections.txt
U zpkgtools/trunk/doc/metadata.txt
U zpkgtools/trunk/doc/resources.txt
U zpkgtools/trunk/doc/zpkg.txt
-=-
Modified: zpkgtools/trunk/doc/collections.txt
===================================================================
--- zpkgtools/trunk/doc/collections.txt 2005-09-14 02:36:38 UTC (rev 38460)
+++ zpkgtools/trunk/doc/collections.txt 2005-09-14 03:50:02 UTC (rev 38461)
@@ -12,8 +12,8 @@
dependency information.
Collection distributions are laid out as a directory tree with a
-specific form. If the primary resource being packaged is ``ZopeX3``,
-and the release tag is ``ZopeX3-1_0``, we get a tree that looks like
+specific form. If the primary resource being packaged is ``Zope``,
+and the release tag is ``Zope-3.1.0``, we get a tree that looks like
this (assuming it has the ``zope`` package as a dependency)::
ZopeX3-1.0/
@@ -35,7 +35,7 @@
version.txt
Support/
- setuptools/
+ ZConfig/
__init__.py
...
zpkgtools/
@@ -53,7 +53,7 @@
The support packages aren't shown in their entirety, both for brevity
and because they really aren't the meaningful part of the payload.
The dependency list is assumed to be shorter than actually expected
-for ZopeX3 as well.
+for Zope 3 as well.
Explanation
@@ -75,33 +75,12 @@
component is equivalent to a non-collection package of just the one
component.
-Collections are defined by a set of metadata files similar to
-packages. These include:
-
-`DEPENDENCIES.cfg`
- 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, a comment, or blank.
-
-`PACKAGE.cfg`
- An optional file which describes how the collection distribution
- should be assembled.
-
-`PUBLICATION.cfg`
- Publication metadata, including many Dublin Core fields and similar
- information. This is required, but is not expected to change often
- for a distribution.
-
-`SETUP.cfg`
- Information about what's included in the distrubution, primarily for
- use by a `setup.py` script.
-
-For components that aren't Python packages, at least one of
+Collections are defined by the same set of metadata files as any other
+packages. Additional information on these files can be found in
+`Metadata Descriptions for Distributions <metadata.html>`_. For
+components that aren't Python packages, at least one of
`DEPENDENCIES.cfg`, `PACKAGE.cfg`, or `SETUP.cfg` is required.
-
-Additional information on these files can be found in `Metadata
-Descriptions for Distributions <metadata.html>`_.
-
+
For each dependency that can be fulfilled (a location is specified in
the `resource maps`_ loaded by |zpkg|_), an additional directory is
added to the `Packages/` directory. The new directory will have the
@@ -136,8 +115,9 @@
- We're currently only supporting a limited amount of "package
information" for collections, but this is largely a software issue,
- not a design problem. The information file will be called
- `SETUP.cfg`.
+ not a design problem. The information file is called `SETUP.cfg`,
+ and what's accepted is a subset of what's allowed for a Python
+ package.
.. include:: links.rst
Modified: zpkgtools/trunk/doc/metadata.txt
===================================================================
--- zpkgtools/trunk/doc/metadata.txt 2005-09-14 02:36:38 UTC (rev 38460)
+++ zpkgtools/trunk/doc/metadata.txt 2005-09-14 03:50:02 UTC (rev 38461)
@@ -18,7 +18,7 @@
feature:XML parser
- Blank lines and lines starting with ``#`` as the first non-white
+ Blank lines and lines starting with **#** as the first non-white
character are ignored. All other lines are considered a single
dependency; leading and trailing whitespace will be ignored.
Dependencies are case-sensitive.
@@ -57,9 +57,9 @@
--------------------------------
The `PACKAGE.cfg` file can contain three distinct sections; the
-``<load>`` section identifies files that need to be loaded from
-other sources, the ``<distribution>`` section is used to include
-files in the distribution root, and the ``<collection>`` section is
+**<load>** section identifies files that need to be loaded from
+other sources, the **<distribution>** section is used to include
+files in the distribution root, and the **<collection>** section is
used to include files in the component itself (even if the component
isn't a collection; this name is used since it usually will be a
collection).
@@ -70,21 +70,27 @@
1. A copy of the component is made that can be written to. This is
the *workspace*.
-2. External references are loaded into the workspace. It is
- possible for this to overwrite portions of the component itself,
- so specify the loads carefully. This is based on the ``<load>``
- section of `PACKAGE.cfg`.
+2. External references are loaded into the workspace. It is possible
+ for this to overwrite portions of the component itself, so specify
+ the loads carefully. This is based on the **<load>** section of
+ `PACKAGE.cfg`. Note that using **<load>** sections to retrieve
+ critical parts of a Python package's functionality makes the
+ package more difficult to work with directly from a checkout from a
+ revision control repository. Current best practice is to use it
+ only for information that should be loaded for a distribution, and
+ even that should be avoided when possible since it can be used to
+ bypass the value of the revision control system.
3. Files from the workspace are copied into their final locations in
the component-specific portion of the distribution tree.
- If `PACKAGE.cfg` contains a ``<collection>`` section, it is used
+ If `PACKAGE.cfg` contains a **<collection>** section, it is used
to specify which files should be copied into the
component-specific portion of the distribution tree. Only files
- listed will be copied. If the ``<collection>`` section specifies
+ listed will be copied. If the **<collection>** section specifies
exclusions, all files will be copied *except* for those excluded.
- If the ``<collection>`` section is not present or is empty, all
+ If the **<collection>** section is not present or is empty, all
files in the workspace are copied; directories are copied
recursively. Files named `.cvsignore` and directories with names
of `{arch}`, `CVS`, `_darcs`, `RCS`, `SCCS`, or `.svn` are
@@ -107,9 +113,9 @@
specifying exclusions instead of inclusions. It is not possible to
specify both using the current |zpkg|_ implementation. An
exclusion is similar to an inclusion, but the destination is always
- ``-`` (a single hyphen):
+ **-** (a single hyphen):
- *source* ``-``
+ *source* **-**
will cause files and directories matching *source* to be excluded
from the distribution. *source* can contain POSIX globbing
@@ -117,7 +123,7 @@
4. If the component being processed is the primary resource being
packaged, files from the workspace can be copied into the
- distribution root. This is done using the ``<distribution>``
+ distribution root. This is done using the **<distribution>**
section of `PACKAGE.cfg`. This is most useful for including a
`README.txt` in the distribution root so people unpacking the
distribution can read about the package they've just unpacked.
@@ -127,7 +133,7 @@
*destination* *source*
- Unlike inclusions in the ``<collection>`` section, the
+ Unlike inclusions in the **<collection>** section, the
*destination* is interpreted relative to the distribution root
rather than the component-specific portion of the distribution
tree.
Modified: zpkgtools/trunk/doc/resources.txt
===================================================================
--- zpkgtools/trunk/doc/resources.txt 2005-09-14 02:36:38 UTC (rev 38460)
+++ zpkgtools/trunk/doc/resources.txt 2005-09-14 03:50:02 UTC (rev 38461)
@@ -40,15 +40,15 @@
- tag
The host part can include optional username, password, and connection
-type parts::
+type parts:
- [ username [ ":" password ] "@" ] hostname [ ":" connection-type ]
+ [ *username* [ ":" *password* ] "@" ] *hostname* [ ":" *connection-type* ]
This is very similar to the format used for FTP or HTTP with Basic
authentication, where connection-type replaces the port number.
-XXX We should actually still support a port number, at least for
-``pserver`` connections. The default port for ``pserver`` is 2041.
+.. XXX We should actually still support a port number, at least for
+ ``pserver`` connections. The default port for ``pserver`` is 2041.
The path may be omitted (left empty) to refer to the entire
repository, including the top-level `CVSROOT/` directory.
@@ -66,14 +66,32 @@
cvs://user@pw:cvs.example.org:pserver/cvsroot/module/doc/:r1-1-maint-branch
+Tags and Subversion URLs
+------------------------
+
+Subversion doesn't distinguish tags specially, since the conceptual
+equivalent is actually the revision number. To support the (common)
+convention of having a */tags/* tree within the Subversion repository
+that can be used to provide human-friendly names for tags, |zpkg|_
+supports the use of the text */tags/\*/* as a marker for the tag
+position in Subversion URLs. If the HEAD revision is to be used,
+*/tags/\*/* is replaced by */trunk/* instead. If a tag was specified
+using the **-r** or **--revision-tag** command line option, that value
+is substituted for the asterisk in the URL to generate the actual URL
+to use.
+
+
Supporting Other Revision Control Systems
-----------------------------------------
-Currently, CVS is supported generally, and Subversion is supported in
-a somewhat limited fashion.
+Currently, CVS is supported generally, and Subversion is supported for
+schemes other than ``http:`` and ``https:``.
Support for additional systems hinges on creating new URL schemes for
each system.
Most of the time, it makes more sense to use file: URLs to reference
-files in a checkout on the local system.
+files in a checkout on the local system. By using this and storing
+the configuration and map files use by |zpkg|_ as part of the resource
+being packaged, everything needed by |zpkg|_ can be kept under
+revision control in a consistent state.
Modified: zpkgtools/trunk/doc/zpkg.txt
===================================================================
--- zpkgtools/trunk/doc/zpkg.txt 2005-09-14 02:36:38 UTC (rev 38460)
+++ zpkgtools/trunk/doc/zpkg.txt 2005-09-14 03:50:02 UTC (rev 38461)
@@ -7,13 +7,11 @@
Configuration of **zpkg** is generally 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.
+its packaging.
The **zpkg** command provides some command line options to control
-configuration, and a very simple configuration file to allow
-configurations to be saved.
+configuration, and a simple configuration file to allow configurations
+to be saved.
The following command line options are provided:
@@ -36,8 +34,11 @@
--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.
+ ``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.
@@ -53,10 +54,13 @@
is used for the package name.
-r TAG, --revision-tag=TAG
- Generate the distribution using the CVS 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).
+ 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
@@ -65,7 +69,8 @@
-S
Don't include the required support packages in the distribution.
This can be used to generate smaller distributions when the
- ``zpkgsetup`` package is known to be available on target systems.
+ ``zpkgsetup`` and ``ZConfig`` packages are known to be available on
+ target systems.
--support RESOURCE
Include an additional resource in the Support/ directory of the
@@ -106,9 +111,9 @@
**-m** option.
The command line can include the name of the resource to be packaged
-simply by naming it. It this is not specified on the command line,
-but must be specified in the configuration file using the
-``default-collection`` setting. Only one resource can be specified
+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.
@@ -118,40 +123,41 @@
The configuration files used by **zpkg** use the
`ZConfig`_ configuration language.
-Blank lines and comments (lines that start with ``#`` as the first
+Blank lines and comments (lines that start with **#** as the first
non-blank character) are ignored.
Four keys are currently defined for the configuration file:
-``build-application``, ``collect-dependencies``,
-``include-support-code``, and ``resource-map``. There is also one
-section type that can be used as well, ``<resources>``.
+**build-application**, **collect-dependencies**,
+**include-support-code**, and **resource-map**. There are also two
+section types that can be used as well, **<resources>** and
+**<exclude>**.
-If ``build-application`` is set to ``true``, then an application
+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.
-Setting ``collect-dependencies`` to ``true`` causes dependencies to be
+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.
-The ``default-collection`` value is used to specify a resource that
+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.
-The ``include-support-code`` key is used to control whether **zpkg**
+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
+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.
-The value for ``resource-map`` is a path or URL (including
+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;
+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.
@@ -176,10 +182,10 @@
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
+Note that all **<resources>** sections will be processed before any
external maps are loaded, regardless of ordering.
-Optionally, there is a ``<exclude>`` section in which you can specify the
+Optionally, 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.
@@ -197,7 +203,7 @@
zope.component
</exclude>
-Note that neither the ``<exclude>`` section nor the **-x** and
+Note that neither the **<exclude>** section nor the **-x** and
**--exclude** command-line options support wildcards.
@@ -217,7 +223,7 @@
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.
+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.
@@ -228,7 +234,8 @@
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.
+allows all descendent packages of ``foo`` to be located. Note that
+``*`` alone is not accepted as a wildcard package specification.
Zope Corporation Tagging Convention
More information about the zpkg
mailing list