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
