From 010459468613b5ae20a3f48476869b8b0846adcf Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Sun, 28 Apr 2002 19:16:30 +0000 Subject: [PATCH] documentation update --- doc/{ => en}/reference.sgml | 271 +++++++++++++++++++++++++++++++++--- 1 file changed, 253 insertions(+), 18 deletions(-) rename doc/{ => en}/reference.sgml (74%) diff --git a/doc/reference.sgml b/doc/en/reference.sgml similarity index 74% rename from doc/reference.sgml rename to doc/en/reference.sgml index e1f1bde6..fe35c7b8 100644 --- a/doc/reference.sgml +++ b/doc/en/reference.sgml @@ -4,10 +4,11 @@ dselect"> .deb"> ]> - + dpkg reference Manual draft + Wichert @@ -19,6 +20,7 @@ + 2001 2002 @@ -65,6 +67,43 @@ + + Version numbers + + + It is essential for a packaging system to have a documented method to + compare version numbers. Unfortunately there are different ways of + dealing with them, each with their own good and bad sides. This chapter + describes how &dpkg; compares version numbers. + + + + Version numbers are ASCII strings made up from alphanumeric characters + (letters and digits) and the hyphen (-), dot + (.), plus (+), minus + (-) and colon (:) characters. + + + + A version number consists of two parts: the upstream version, and + optionally the package revision, which are seperated by a hyphen. + If there is no seperate package revision then the upstream version is + not allowed to contain a hyphen. + + + + Comparing version numbers is done by breaking them into pieces and + comparing those from left to right. Pieces are seperated by a + transition from numbers to letters and by non-alphanumeric + characters. Starting from &dpkg; 1.10 numbers of unlimited length may + be used. Olders versions converted numbers to integers before comparing + them and as a result can not handle numbers that do not fit into the C + type int (2^31-1 on 32bit architectures and 2^63-1 on 64bit + architectures). + + + + Managing diversions @@ -322,9 +361,9 @@ root root 0755 /bin/mount [fog;~/sources/play/pkg-manual]-1# dpkg-statoverride --add root root 0755 /bin/mount An override for "/bin/mount" already exists, aborting -[fog;~/sources/play/pkg-manual]-2# dpkg-statoverride --force --add root root 0755 /bin/mount +[fog;~]-2# dpkg-statoverride --force --add root root 0755 /bin/mount An override for "/bin/mount" already exists, but --force specified so lets ignore it. -[fog;~/sources/play/pkg-manual]-3# dpkg-statoverride --list /bin/mount +[fog;~]-3# dpkg-statoverride --list /bin/mount root root 0755 /bin/mount @@ -381,6 +420,15 @@ root root 0755 /bin/mount as the format used in e-mail headers. + + Each format has a version number which indicates the revision of the + format being used. This version is always of the form "X.Y". The + first number (X) is the major version. Within a major version the only + allowed changes in format are the addition of new fields. This guarantees + that tools will always be fully backwards and upwards compatible within + a major version. + +
RFC822 @@ -391,7 +439,7 @@ root root 0755 /bin/mount - Each fiels s a single line consisting of a field-name and a + Each fiels is a single line consisting of a field-name and a field-body, seperated by a colon (:). The field-name is made up from printable ASCII characters minus the colon. The field-body may be composed of all ASCII characters except CR or LF (they @@ -420,8 +468,135 @@ X-Fortune: changes file - Bla + The .changse file is used to describe a set of + files that is going to be installed in an archive. All files have to + belong to the same source package. The data in a + changes include the changes made since the + previous revision, version and architecture information and the list + of files that form the change set along with a checksum + + + Just like other dpkg datafiles this file is formated using RFC822 + syntax. In addition the file can signed as an OpenPGP ASCII armored + message (see RFC2440). The table below lists the allowed fields + in a .dsc file. The order used is not important, + although dpkg-genchanges will output the fields using + the ordering used in the table. + + + + Fields in a <filename>.changes</filename> file + + + + Field + Description + + + + + + Format + + Version of the file format used. Currently 1.7. + + + + Date + + The date (in RFC822 format) when the change set was build. + + + + Source + + The name of the source package from which the changes were + build. + + + + Binary + + The binary packages (ie &deb; files) that are part of the + change set. + + + + Architecture + + A space seperate list of architectures for which files are + included in the set. + + + + Version + + Version number of the source from which the files were built. + + + + Distribution + + Distribution in which the changes should be installed, as taken from + debian/changelog. + + + + Urgency + + Urgency of the changes, as taken from + debian/changelog. + + + + Maintainer + + The maintainer of the package, as listed in + debian/control. + + + + Changed-By + + The person who made the last changes to the sources, as + listed in debian/changelog. + + + + Description + + Multi-line field describing the &deb; files in the package. + Each line describes a single package in the format + "packagename - short description". + + + + Closes + + Space seperate list of bugreports which are closed by this + change set. (Optional) + + + + Changes + + Multi-line field with the changes made since the previous + version, as taken from debian/changelog. + Can possibly mention changes for multiple versions. + + + + Files + + Multi-line field with the list of files in the change set. + Each line describes a single file in the format "MD5 filesize + filename". + + + + +
@@ -451,8 +626,8 @@ X-Fortune: Format - Version of the .dsc file format used - + Version of the file format used. Currently 1.0. + Source Name of the source package Version @@ -461,7 +636,7 @@ X-Fortune: comma seperated list of binary packages build from this source Origin - Name of the organization that procudes this package + Name of the organization that procuded this package Maintainer Maintainer of this package @@ -481,14 +656,6 @@ X-Fortune: - - The current version of the .dsc is 1.0 . The first - digit in the version number is the major version. Within a major version - the only allowed changes in format are additiong of new fields. This - guarantees that tools like dpkg-source will be - fully backwards and upwards compatible within a major version. - - The Files field contains one line for each file that is contains source for this package (only 2 files are supported: a @@ -730,12 +897,80 @@ root adm 0750 /var/log/apache alternatives - Bla + The configuration for alternatives is spread over two places: the + symlink to the selected alternative is stored in /etc/alternatives + and the list of available alternatives is kept in a series of files + in /var/lib/dpkg/alternatives/. + + + For each alternative there is a single file in + /var/lib/dpkg/alternatives/ named after the + the alternative it describes. The file is a normal text file: + + + + + + The first line lists the state of the alternative, either + `manual' or `auto'. + + + + + + The second line is the filename that the alternative will + provide. + + + + + + A list of zero or more slave links. For each slave there are + two lines: the first contains the name of the slave and the + second contains the filename. + + + + + + An empty line + + + + + + A list of one or more alternatives. Each alternative is made up + as follows: + + + + + + The filename of the file providing the alternative. + + + + + + The priority + + + + + + For each slave link a single line with the file providing + the link. An empty line can be used to indicate an + alternative does not provide a slave. + + + + +
- -- 2.39.5