==================
Resource Locations
==================

.. This is a reStructuredText document.
.. include:: links.rst

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
are *not* handled well via HTTP or FTP in the current implementation,
but that's considered a quality-of-implementation issue that can be
dealt with if needed.)

A URL scheme has been defined specifically for use with this tool.
The ``cvs:`` scheme identifies a resource stored in a CVS repository
(either local or remote).

Subversion is supported using the ``svn:``, ``svn+ssh:`` (as well as
Subversion's general ``svn+special:`` schemes), and
``file:`` schemes.  |zpkg|_ is able to determine whether a ``file:``
URL refers to a Subversion repository or refers to a normal
filesystem path and will handle either appropriately.


Absolute Locations and the ``cvs:`` Scheme
------------------------------------------

The ``cvs:`` scheme can be used to identify any absolute path on any
branch or tag within a CVS repository.  It contains the following
components, separated by colons:

- scheme identifier (always ``cvs``)
- host part
- host-relative cvs root
- path
- tag

The host part can include optional username, password, and connection
type parts:

  [ *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.

The path may be omitted (left empty) to refer to the entire
repository, including the top-level `CVSROOT/` directory.

The tag part, including the colon used to separate it from the rest,
can be omitted.  The tag can specify a symbolic tag, a branch tag, or
a revision number.

Some examples::

  cvs:///usr/local/cvsroot:module

  cvs://cvs.example.org:ext/cvs-repository:myproject/README.txt:1.2

  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 for
most schemes; for ``http:`` and ``https:``, add an ``svn:`` prefix so
|zpkg|_ knows the URL is accessible via Subversion::

    svn:http://codespeak.net/svn/user/fdrake/testpkg

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.  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.
