= Common Distribution Artifact Specifier =
Version 0.1
Overview
This proposal extends the URI Syntax proposal: /URISyntax
It is recommended, but not required, that it be used in conjunction with the Common Build Version Specifier proposal: /CommonBuildVersionSpecifier
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
- versioned-platform-artifact-name bin-suffix
(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
- versioned-platform-artifact-name src-suffix
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-versiondebug
- artifact-name = pchar+ short-version = version-name ["-" timestamp]
(version-name and timestamp are per /CommonBuildVersionSpecifier) }}}
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-versiondebug
- versioned-platform-artifact-name = artifact-name "-" short-version
- platform["debug"]
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 /CommonBuildVersionSpecifier
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 http://repo.apache.org/apache/httpd/2.0.48/source/httpd-2.0.48-src.tar.gz }}}
Platform specific source
http://repo.apache.org/apache/httpd/2.0.48/source/win32/httpd-2.0.48-win32-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-win32-x86-dbg-bin.exe