summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorP. J. McDermott <pehjota>2012-10-16 22:38:07 (EDT)
committer P. J. McDermott <pjm@nac.net>2012-10-16 22:38:07 (EDT)
commit72cd7ffa29b045d734ae24d99b926fda16c91bd4 (patch)
treecbcbe1ea3a27215b6302643c78863ed9470cf7bf
parent54bcb080adef64f7aef00c02871511376a32bf6a (diff)
Write a "Package Archive Layout" page.
-rw-r--r--dev/archive/layout.mdwn150
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/