On Fri, May 18, 2012 at 01:38:40PM +0200, Julian Andres Klode wrote:
> On Fri, May 18, 2012 at 12:02:47PM +0100, Ian Jackson wrote:
> > CC'ing the apt list deity@lists.debian.org.
> >
> > Goswin von Brederlow writes ("Re: Bug#481129: Bug#671503: general: APT repository format is not documented"):
> > > Michal Suchanek <michal.suchanek@ruk.cuni.cz> writes:
> > > > [ discussions regarding documenting the apt repository format ]
> > >
> > > I would suggest you look at existing repositories, whatever scraps of
> > > information is in the manuals and maybe a bit at the source and start to
> > > write a documentation. Once you have that offer it for review and other
> > > people can pitch in their bits of knowledge. Getting the current format
> > > documented right shouldn't be that hard if someone just starts.
> >
> > Right.
> >
> > > And once such a document exists it is much easier to get people do
> > > document changes or hit them over the head if they don't.
> >
> > Can the apt maintainers confirm that once such a document exists, they
> > will insist that future contributions to apt which change the
> > repository format update the document ?
> >
> > What form do the apt maintainers think the document should take ?
> > Should it eventually be in the apt source package or somewhere else ?
>
> I do not think that APT is responsible for the repository format. The
> repository format is defined by ftpmaster, not by APT. APT has to my
> knowledge not defined anything new, but only implemented changes to
> the repository format after they were introduced by ftpmaster (see
> InRelease files).
>
> We currently have three independent implementations of the repository
> format in the archive: APT, cupt, smartpm. Furthermore, tools like
> debian-cd probably also have some knowledge about the repository
> format.
>
> The repository format should thus be part of Policy, not part of
> APT. APT is one of the users of that format, not the one defining
> it (it might just get stricter in behavior from time to time, just
> like compilers). Changes to the format should require approval of
> ftpmaster, as they have to implement them on the server-side.
>
A working draft could be something like the following. It mostly
describes the current format for Release, Packages, and Sources
files. It's thus missing Contents and Translations, pdiffs, and
stuff, but it's a beginning.
It specifies different requirements for servers and clients,
in order to have clients be backwards compatible with more
repositories, and forcing servers to be stricter. Don't know
how good that is, though.
============================
= Debian Repository Format =
============================
This documents a subset of the Debian repository format. This is a work
in progress.
"Release" files
===============
The file "dists/$DIST/Release" shall contain meta-information about the
distribution and checksums for the indices. The file "dists/$DIST/Release.gpg"
shall be an GPG signature of the "Release" file, compatible with the format
used by the GPG options "-a -b -s". The file "dists/$DIST/InRelease" shall be
the "Release" file with a GPG clearsign signature compatible with the format
used by the GPG options "-a -s --clearsign".
The following fields might be available:
- Origin
- Label
- Suite
- Codename
- Date
- Valid-Until
- Architectures
- Components
- Description
- MD5sum, SHA1, SHA256
- NotAutomatic and ButAutomaticUpgrades
Servers shall provide the Release file, and its signed counterparts with at
least the following keys:
- SHA256
- Origin
- Suite and/or Codename
- Architectures
Clients shall accept missing Release files, and Release files without the
fields required for servers. They might reject Release files that do not
contain at least one of the fields defined herein.
Architectures
-------------
Whitespace separated unique single words identifying Debian machine architectures
as described in Architecture specification strings, Section 11.1.
Origin
------
Shall indicate the origin of the repository.
Label
-----
Optional field including some kind of label.
Suite
-----
The Suite field shall describe the suite. In Debian, this shall be one of
oldstable, stable, testing, unstable, or experimental; with optional suffixes
separated by "-" (such as "stable-updates").
Codename
--------
The Suite field shall describe the codename of the release. This is mostly
a free-form string used to give a name to a release.
Date, Valid-Until
-----------------
The Date field shall specify the time at which the Release file was created. The
Valid-Until field shall specify at which time the Release file should be
considered expired by the client. Client behaviour on expired Release files
is unspecified.
Components
-----------
A whitespace separated list of areas.
Example:
Components: main contrib non-free
MD5sum, SHA1, SHA256
--------------------
Those fields shall be multi-line fields containing multiple lines of whitespace
separated data. Each line shall contain
(1) The checksum of the file in the format corresponding to the field
(2) The size of the file (integer >= 0)
(3) The filename relative to the directory of the Release file
Each datum may be seperated by one or more whitespace characters.
Server requirements:
The field shall contain data about all uncompressed files, and should also
contain information about all compressed files. The checksum and sizes shall
match the actual existing files.
Client behaviour:
Any file should be checked at least once, either in compressed or
uncompressed form, depending on which data is available. If a file
has no associated data, the client shall inform the user about this
under possibly dangerous situations (such as installing a package
from that repository). If a file does not match the data specified
in the release file, the client shall not use any information from
that file, inform the user, and might use old information (such as
the previous locally kept information) instead.
NotAutomatic and ButAutomaticUpgrades
-------------------------------------
The NotAutomatic and ButAutomaticUpgrades fields are boolean fields
instructing the package manager. They may contain the values "yes"
and "no".
If "NotAutomatic: yes" is specified, the client should prevent installation
of packages from this repository unless explicitely requested (APT will assign
priority 1 to that repository).
If "ButAutomaticUpgrades: yes" is specified in addition to "NotAutomatic: yes",
the client should cause upgrades to packages from that repository to be
installed automatically (APT will assign priority 100 to that repository).
If both are either missing or set to "No", the repository should behave like
any other repository (APT will assign either priority 500 or 990 by default,
depending on whether the release is it's target release).
Other combinations are undefined.
"Packages" Indices
==================
The files dists/$DIST/$COMP/binary-$ARCH/Packages are called Binary Packages
Indices. They consist of multiple paragraphs, where each paragraph has the
format defined in Policy 5.3 (Binary package control files -- DEBIAN/control),
and the additional fields defined in this section.
Filename
--------
The Filename field shall list the path of the package archive relative to the
base directory of the repository.
Example:
Filename: pool/main/a/apt/apt_0.9.3_amd64.deb
Required: yes
Size
----
The size field shall give the size of the package file, in bytes.
Example:
Size: 1158196
Required: yes
MD5sum, SHA1, SHA256, SHA512
----------------------------
Checksums for the package. They shall be represented in hexadecimal
notation. The SHA512 field is not in active use prior to this
specification, the MD5sum and SHA1 fields should be considered
deprecated, but should still be provided.
Examples:
MD5sum: 2519c8c1afd27e70cf4ac10a5fa46e32
SHA1: 646eda5b6d51190181c15f5537428161f6f04c1d
SHA256: 3183eff291d1e9d905e78a6b467bbfb90b20fc2808d50b5e91bf55158b4c18be
Server requirements: SHA256 shall be available
Client requirements: Shall accept files without any such fields, should warn
if those fields are missing and a package is used.
Description-md5
----------------
An md5sum of the english description. This will be used to lookup the
translations in the translation indices. If this field is not defined,
the md5sum shall be calculated from the Description field.
Server requirements:
Either Description or Description-md5 shall be specified.
Client requirements:
If neither Description, nor Description-MD5 is defined, the result shall
be the same as if an empty description was specified for all languages.
If Description-md5 is defined, the long description shall be looked up
via translation indices if requested.
Example:
Description-md5: 9fb97a88cb7383934ef963352b53b4a7
Description
-----------
The Description field shall contain the complete package description, if
Description-md5 is not defined; or only the short description of the package,
if Description-md5 is defined.
"Sources" Indices
=================
The files dists/$DIST/$COMP/source/Sources are called Sources indices. They
consist of multiple paragraphs, where each paragraph has the format defined
in Policy 5.5 (5.4 Debian source control files -- .dsc), with the following
changes and additional fields. The changes are:
- The "Source" field is renamed to "Package"
- A new mandatory field "Package-List"
- A new mandatory field "Directory"
- A new optional field "Priority"
- A new optional field "Section"
Package-List
------------
The Package-List field shall contain multiple lines of package information,
where each line begins with a whitespace and has the following format:
$PKGNAME $TYPE $SECTION $PRIORITY
$PKGNAME is the name of the package, $TYPE is "deb" or "udeb", $SECTION
is the section of the package, and $PRIORITY is the priority of the package.
Example:
Package-List:
apt deb admin important
apt-doc deb doc optional
apt-transport-https deb admin optional
apt-utils deb admin important
libapt-inst1.5 deb admin important
libapt-pkg-dev deb libdevel optional
libapt-pkg-doc deb doc optional
libapt-pkg4.12 deb admin important
Directory
---------
The directory field shall list the location of the source package in the
repository, relative to the base directory of the repository.
Example:
Directory: pool/main/a/apt
Priority
--------
Shall contain the value "source".
Example:
Priority: source
Section
-------
Shall contain the section specified for the source package??
Example:
Section: admin
>
--
Julian Andres Klode - Debian Developer, Ubuntu Member
See http://wiki.debian.org/JulianAndresKlode and http://jak-linux.org/.
Attachment:
pgp7ZOx4j6TR4.pgp
Description: PGP signature