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 email@example.com. > > > > Goswin von Brederlow writes ("Re: Bug#481129: Bug#671503: general: APT repository format is not documented"): > > > Michal Suchanek <firstname.lastname@example.org> 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/.
Description: PGP signature