summaryrefslogtreecommitdiffstats
path: root/dev/archive/layout.mdwn
blob: 082d755fc8e4c28c48ca41088eee3ff6f566e1da (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
[[!meta title="Package Archive Layout"]]

This page should be converted into a proper [specification][].

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.

For a tool that implements this package archive layout, see
[[pro-archman|dev/pro-archman]], the ProteanOS Archive Manager.

[specification]: http://git.proteanos.com/doc/specs.git/


Definitions
===========

Package Archive
---------------

The **package archive** is a hierarchy of directories, package indices, 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 feeds 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`.

Platform
--------

A **platform** is a set of package configurations representing a particular use
case.

Architecture
------------

An **architecture** is a particular combination of processing units, kernel, and
system libraries for which packages are built.

The `src` architecture contains source packages.

The `all` architecture contains architecture-independent binary packages.

Section
-------

A **section** is a set of packages organized by purpose.  Example sections are
`base`, `dev`, and `dbg`.

Feed
----

A **feed** is a set of packages of a particular channel, distribution,
platform, architecture, and section 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.

Hash
----

The **hash** of a source package name, as used in the pool structure, is the
first character in the name or the first four characters in the name if the name
begins with the string "`lib`".

A directory in the pool whose name is a source package name hash may be called a
**bucket**.


Archive Layout
==============

The layout of the package archive is given by the following tree:

    <proto>://<mirror-domain>/pub/proteanos/
     +- feeds/
     |   +- <channel>/
     |       +- <distribution>/
     |           +- <platform>/
     |               +- <architecture>/
     |                   +- <section>/
     |                       +- Packages
     |                       +- Packages.gz
     +- pool/
         +- <component>/
             +- <hash>/
                 +- <srcpkg>/
                     +- <binpkg>_<binver>_<arch>_<plat>.opk

Examples
--------

The compressed packages index of the `core-linux-eglibc` architecture, `dev`
platform, and `base` section would be located at the following path at a mirror
site:

    /pub/proteanos/feeds/dev/trunk/dev/core-linux-eglibc/base/Packages.gz

The compressed packages index of source packages would be located at the
following path at a mirror site:

    /pub/proteanos/feeds/dev/trunk/all/src/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/e/expat/libexpat.1_2.1.0-2_core-linux-eglibc_all.opk


Packages Index Syntax
=====================

The packages index file syntax is that used by APT, opkg, etc.  It consists of
paragraphs of fields, with paragraphs separated by empty lines.  Each field
consists of the field name, a colon (`:`), and the field value.  Some fields may
have values spanning multiple lines; each line after the first in a value must
begin with at least one space.

The fields in a paragraph are the control fields generated for binary packages
by ob-gencontrol, plus `Filename`, `Size`, and `MD5sum`.

Example
-------

An example paragraph of a packages index follows:

    Package: libexpat.1
    Source: expat
    Version: 2.1.0-2
    Architecture: core-linux-eglibc
    Platform: all
    Maintainer: "P. J. McDermott" <pjm@nac.net>
    Installed-Size: 530
    Description: XML parser library
     Expat is an XML parser library written in C. It is a stream-oriented parser in
     which an application registers handlers for things the parser might find in the
     XML document (like start tags).
    Homepage: http://expat.sourceforge.net/
    Filename: ../../../../../../pool/e/expat/libexpat.1_2.1.0-2_core-linux-eglibc_all.opk
    Size: 176465
    MD5sum: 7d7984ab0c910ba525410562cfdb5315


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/