Overview
========

This proposal extends the URI Syntax proposal:
  http://nagoya.apache.org/wiki/apachewiki.cgi?ASFRepository/URISyntax

It is recommended, but not required, that it be used in conjunction
with the Common Build Version Specifier proposal:

http://nagoya.apache.org/wiki/apachewiki.cgi?ASFRepository/CommonBuildVersio
nSpecifier

The key aims of this proposal are to:

. formalise artifact-specifier for source and binary distributions;
. support platform-independent and platform-specific distributions;
. provide a set of best practices for such artifacts; and
. enable tools to construct a URI to unambigously locate
  a particular distribution artifact using a set of known
  criteria


URI Components
==============

An absolute repository URI is written as follows:

  repository-uri = access-specifier "/" product-specifier "/"
                   version-specifier "/" artifact-specifier

For distribution artifacts, artifact-specifier is:

  artifact-specifier = distribution-artifact
  distribution-artifact = binary-artifact | source-artifact

Binary artifacts
----------------

  binary-artifact = platform-independent-binary |
                    platform-specific-binary
  platform-independent-binary = bin-prefix "/"
                                versioned-artifact-name
                                bin-suffix
  platform-specific-binary = bin-prefix "/" os-name "/"
                             versioned-platform-artifact-name
                             bin-suffix
  bin-prefix = "binaries"
  os-name = pchar+
  bin-suffix = "-bin" "." arc-ext
  arc-ext = "tar.gz" | "zip" | "exe" | pchar+

  (pchar is per http://www.ietf.org/rfc/rfc2396.txt)

E.g:
  "binaries/linux/httpd-2.0.40-i686-pc-linux-gnu-rh73-bin.tar.gz"
  "binaries/win32/apache-2.0.48-win32-x86-bin.exe"
  "binaries/commons-cli-1.1-bin.tar.gz"

Source artifacts
----------------

  source-artifact = platform-independent-source |
                    platform-specific-source
  platform-independent-source = src-prefix "/"
                                versioned-artifact-name
                                src-suffix
  platform-specific-source = src-prefix "/" os-name "/"
                             versioned-platform-artifact-name
                             src-suffix
  src-prefix = "source"
  src-suffix = "-src" "." arc-ext

E.g:
  "source/commons-cli-1.1-src.zip"
  "source/solaris/httpd-2.0.43-sparc-sun-solaris-2.8-src.tar.gz"

Platform independent artifacts
------------------------------

Platform independent artifacts include the project version:

  versioned-artifact-name = artifact-name "-" short-version [debug]
  artifact-name = pchar+
  short-version = version-name  ["-" timestamp]

  (version-name and timestamp are per

http://nagoya.apache.org/wiki/apachewiki.cgi?ASFRepository/CommonBuildVersio
nSpecifier)

E.g:
  ant-1.5.4-src.tar.gz
  ant-1.5.4-20031113.1043-bin.zip
  ant-1.5.4-dbg-bin.tar.gz

Platform specific artifacts
---------------------------

Platform-specific distribution artifacts include the project version
and platform:

  versioned-platform-artifact-name = artifact-name "-" short-version
                                     platform [debug]
  artifact-name = pchar+
  short-version = version-name  ["-" timestamp]
  plaform = pchar+
  os-name = pchar+

Debug information
-----------------

Artifacts can indicate that they include debugging information
via the "-dbg" suffix:

  debug = "-dbg"

E.g:
  "commons-cli-1.1-dbg-bin.zip"
  "httpd-2.0.43-sparc-sun-solaris2.8-dbg-bin.tar.gz"

Rationale
=========

Artifacts in subdirectories
---------------------------

Each category of artifact in this proposal is required
to be located in its own directory, e.g:
  "binaries/commons-cli-1.0.tar.gz"
rather than in the root project version directory.

The alternative approach of placing each artifact in the
root makes repository navigation harder, particularly
for projects that:
. deploy large numbers of artifacts
. deploy artifacts for multiple platforms
. deploy artifacts other than those defined by this proposal.

Inclusion of version and platform in artifact names
----------------------------------------------------

Distribution artifacts require that the version be included in
their names. Platform specific artifacts are required to
also specify the platform:

  versioned-artifact-name = artifact-name "-" short-version [debug]
  versioned-platform-artifact-name = artifact-name "-" short-version
                                     platform [debug]
  short-version = version-name  ["-" timestamp]

This ensures that it is immediately obvious to users what version
and platform of an artifact they are using, subsequent to its download.

The optional timestamp indicates interim builds, as per:

http://nagoya.apache.org/wiki/apachewiki.cgi?ASFRepository/CommonBuildVersio
nSpecifier


Tool support
============

Tools can unambigously locate an artifact within a project version
given the following criteria:

. artifact type
  Mandatory.

. artifact name
  Mandatory.

. OS name.
  Mandatory for platform specific distributions, optional otherwise.

. Platform
  Mandatory for platform specific distributions, optional otherwise.

. debug information
  Optional.

. artifact version
  Mandatory. May include interim build timestamp.

. archive type
  Mandatory.

Example 1
---------

Given:
  type = "binary"
  name = "commons-cli"
  version = "1.1"
  debug = "false"
  arc = "zip

The URI fragment would be:
  "binaries/commons-cli-1.1-bin.zip"

Example 2
---------

Given:
  type = "binary"
  name = "commons-cli"
  version = "1.1-20031113.1043"
  debug = "true"
  arc = "tar.gz"

The URI fragment would be:
  "binaries/commons-cli-1.1-20031113.1043-dbg-bin.tar.gz"

Example 3
---------

Given:
  type = "source"
  name = "commons-cli"
  version = "1.1"
  arc-type = "tar.gz"

The URI fragment would be:
  "source/commons-cli-1.1-src.tar.gz"

Example 4
---------

Given:
  type = "binary"
  name = "httpd"
  version = "2.0.48"
  os-name = "solaris"
  platform = "sparc-sun-solaris2.8"
  debug = "true"
  arc-type = "tar.gz"

The URI fragment would be:
  "binaries/solaris/httpd-2.0.48-sparc-sun-solaris2.8-dbg-bin.tar.gz"

URI Examples
============

Platform independent source
---------------------------

  http://repo.apache.org/apache/ant/1.5.4/source/ant-1.5.4-src.zip
  http://repo.apache.org/apache/ant/1.5.4/source/ant-1.5.4-src.tar.gz


Platform independent binaries
------------------------------

  http://repo.apache.org/apache/ant/1.5.4/binaries/ant-1.5.4-bin.zip
  http://repo.apache.org/apache/ant/1.5.4/binaries/ant-1.5.4-bin.tar.gz
  http://repo.apache.org/apache/ant/1.5.4/binaries/ant-1.5.4-dbg-bin.tar.gz

Platform specific binaries
--------------------------


http://repo.apache.org/apache/httpd/2.0.48/binaries/win32/apache-2.0.48-win3
2-x86-dbg-bin.exe

http://repo.apache.org/apache/httpd/2.0.48/binaries/solaris/httpd-2.0.48-spa
rc-sun-solaris2.8-bin.tar.gz


Reply via email to