= 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
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 Self: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-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 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 http://repo.apache.org/apache/httpd/2.0.48/binaries/solaris/httpd-2.0.48-sparc-sun-solaris2.8-bin.tar.gz