Write a "Package Archive Layout" page.

1 files changed, 150 insertions, 0 deletions

diff --git a/dev/archive/layout.mdwn b/dev/archive/layout.mdwn
new file mode 100644
index 0000000..7b25e26
--- /dev/null
+++ b/dev/archive/layout.mdwn
@@ -0,0 +1,150 @@
+[[!meta title="Package Archive Layout"]]
+
+The package archive will be laid out like a Debian pool archive but use opkg's
+simpler package source list (a.k.a. "feed") structure.
+
+
+Definitions
+===========
+
+Package Archive
+---------------
+
+The **package archive** is a hierarchy of directories, package indicies, and
+binary packages.  It is accessible on mirror hosts over network protocols like
+HTTP and FTP.  On each mirror host, it is stored under `pub/proteanos`, relative
+to the mirror site's document root.
+
+Channel
+-------
+
+A **channel** is a set of distributions in the package archive aimed at a
+particular set of users.  There are two channels: `dev` for developers and `rel`
+for end users and their installed systems.
+
+Packages may be directly uploaded to distributions in the `dev` channel.
+Distributions in the `rel` channel are simply static snapshots of distributions
+in the `dev` channel.
+
+Distribution
+------------
+
+A **distribution** is a set of components in the package archive with a certain
+release policy and life cycle.  There is one rolling release: `trunk`.  All
+other distributions are fixed release series distributions, e.g. `rs1`.
+
+Normally, packages should be uploaded to the `trunk` distribution.  Packages
+should only be uploaded to release series distributions to backport critical
+defect fixes into stable releases.
+
+Suite
+-----
+
+A **suite** is the combination of a channel and distribution.  Example suites
+are `dev/trunk` and `rel/rs1`.
+
+Component
+---------
+
+A **component** is a section of the package archive that is subject to certain
+inclusion criteria.  There is only one component: `main`.
+
+Platform
+--------
+
+A **platform** is a set of architectures in the package archive with packages
+configured for a particular use case.
+
+Architecture
+------------
+
+An **architecture** is a set of packages in the package archive built for a
+particular combination of processing units, kernel, and system libraries.
+
+The `src` architecture contains source packages.
+
+The `all` architecture contains architecture-independent binary packages.
+
+Feed
+----
+
+A **feed** is a set of packages of a particular channel, distribution,
+component, platform, and architecture in the package archive.  It contains a
+package index that describes all contained packages.
+
+Package
+-------
+
+A **package** is a set of data and control files that can be installed on a
+user's system.
+
+A **source package** is a set of source package data files and control files.
+It can be unpacked and built to generate binary packages.
+
+A **binary package** is a set of compiled data files and control files.  It can
+be installed by an end user and used by other binary and source packages.
+
+Package Index
+-------------
+
+A **package index** is a detailed list of all packages in a feed in the package
+archive.  It is either a UTF-8-encoded plain text file named `Packages` or a
+gzip-compressed UTF-8-encoded plain text file named `Packages.gz`.
+
+Pool
+----
+
+The pool is the common storage area for all packages.
+
+
+Archive Layout
+==============
+
+The layout of the package archive is given by the following tree:
+
+    <proto>://<mirror-domain>/pub/proteanos/
+     +- dists/
+     |   +- <channel>/
+     |       +- <distribution>/
+     |           +- <component>/
+     |               +- <platform>/
+     |                   +- <architecture>/
+     |                       +- Packages
+     |                       +- Packages.gz
+     +- pool/
+         +- <component>/
+             +- <letter>/
+                 +- <srcpkg>/
+                     +- <binpkg>_<binver>_<arch>_<plat>.opk
+
+Examples
+--------
+
+The compressed packages index of the `core-linux-eglibc` architecture and `dev`
+platform would be located at the following path at a mirror site:
+
+    /pub/proteanos/dists/dev/trunk/main/dev/core-linux-eglibc/Packages.gz
+
+The compressed packages index of the `src` architecture and `all` platform would
+be located at the following path at a mirror site:
+
+    /pub/proteanos/dists/dev/trunk/main/all/src/Packages.gz
+
+The `libexpat.1` binary package for the `core-linux-eglibc` architecture would
+be located at the following path at a mirror site:
+
+    /pub/proteanos/pool/main/e/expat/libexpat.1_2.1.0-2_core-linux-eglibc_all.opk
+
+
+References
+==========
+
+Examples of Debian pool archives are the official [Debian archive][deb-arc] and
+[P. J.'s "Bootstrappable Debian" archive][deb-boot-arc].  An example of a set of
+opkg package source lists (a.k.a. "feeds") is the [Ångström
+repository][ang-repo].
+
+
+[deb-arc]: http://ftp.us.debian.org/debian/
+[deb-boot-arc]: http://bootstrap.pehjota.net/archive/
+[ang-repo]: http://www.angstrom-distribution.org/feeds/