[[!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/