diff options
author | Wichert Akkerman <wakkerma@debian.org> | 2002-04-28 19:16:30 +0000 |
---|---|---|
committer | Wichert Akkerman <wakkerma@debian.org> | 2002-04-28 19:16:30 +0000 |
commit | 010459468613b5ae20a3f48476869b8b0846adcf (patch) | |
tree | 6a7ec0e871c1597d1cfb1fdc7f6225cab3ff2eb1 /doc | |
parent | 6a9ed76db3e3d1cb36d246c9b3c22d220c2168a9 (diff) | |
download | dpkg-010459468613b5ae20a3f48476869b8b0846adcf.tar.gz |
documentation update
Diffstat (limited to 'doc')
-rw-r--r-- | doc/en/reference.sgml (renamed from doc/reference.sgml) | 271 |
1 files changed, 253 insertions, 18 deletions
diff --git a/doc/reference.sgml b/doc/en/reference.sgml index e1f1bde67..fe35c7b87 100644 --- a/doc/reference.sgml +++ b/doc/en/reference.sgml @@ -4,10 +4,11 @@ <!ENTITY dselect "<command>dselect</command>"> <!ENTITY deb "<filename>.deb</filename>"> ]> -<book id="packaging-manual"> +<book id="reference"> <bookinfo> <title>dpkg reference Manual</title> <edition>draft</edition> + <authorgroup> <author> <firstname>Wichert</firstname> @@ -19,6 +20,7 @@ </affiliation> </author> </authorgroup> + <copyright> <year>2001</year> <year>2002</year> @@ -65,6 +67,43 @@ </chapter> +<chapter id="versions"> + <title>Version numbers</title> + + <para> + 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. + </para> + + <para> + Version numbers are ASCII strings made up from alphanumeric characters + (letters and digits) and the hyphen (<keycap>-</keycap>), dot + (<keycap>.</keycap>), plus (<keycap>+</keycap>), minus + (<keycap>-</keycap>) and colon (<keycap>:</keycap>) characters. + </para> + + <para> + 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. + </para> + + <para> + 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). + </para> +</chapter> + + <chapter id="diversions"> <title>Managing diversions</title> @@ -322,9 +361,9 @@ root root 0755 /bin/mount <programlisting> [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 </programlisting> </example> @@ -381,6 +420,15 @@ root root 0755 /bin/mount as the format used in e-mail headers. </para> + <para> + 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. + </para> + <section> <title>RFC822</title> <para> @@ -391,7 +439,7 @@ root root 0755 /bin/mount </para> <para> - 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: <title>changes file</title> <para> - Bla + The <filename>.changse</filename> 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 + <filename>changes</filename> 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 </para> + + <para> + 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 <filename>.dsc</filename> file. The order used is not important, + although <command>dpkg-genchanges</command> will output the fields using + the ordering used in the table. + </para> + + <table> + <title>Fields in a <filename>.changes</filename> file</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Field</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Format</entry> + <entry> + Version of the file format used. Currently 1.7. + </entry> + </row> + <row> + <entry>Date</entry> + <entry> + The date (in RFC822 format) when the change set was build. + </entry> + </row> + <row> + <entry>Source</entry> + <entry> + The name of the source package from which the changes were + build. + </entry> + </row> + <row> + <entry>Binary</entry> + <entry> + The binary packages (ie &deb; files) that are part of the + change set. + </entry> + </row> + <row> + <entry>Architecture</entry> + <entry> + A space seperate list of architectures for which files are + included in the set. + </entry> + </row> + <row> + <entry>Version</entry> + <entry> + Version number of the source from which the files were built. + </entry> + </row> + <row> + <entry>Distribution</entry> + <entry> + Distribution in which the changes should be installed, as taken from + <filename>debian/changelog</filename>. + </entry> + </row> + <row> + <entry>Urgency</entry> + <entry> + Urgency of the changes, as taken from + <filename>debian/changelog</filename>. + </entry> + </row> + <row> + <entry>Maintainer</entry> + <entry> + The maintainer of the package, as listed in + <filename>debian/control</filename>. + </entry> + </row> + <row> + <entry>Changed-By</entry> + <entry> + The person who made the last changes to the sources, as + listed in <filename>debian/changelog</filename>. + </entry> + </row> + <row> + <entry>Description</entry> + <entry> + Multi-line field describing the &deb; files in the package. + Each line describes a single package in the format + "packagename - short description". + </entry> + </row> + <row> + <entry>Closes</entry> + <entry> + Space seperate list of bugreports which are closed by this + change set. (Optional) + </entry> + </row> + <row> + <entry>Changes</entry> + <entry> + Multi-line field with the changes made since the previous + version, as taken from <filename>debian/changelog</filename>. + Can possibly mention changes for multiple versions. + </entry> + </row> + <row> + <entry>Files</entry> + <entry> + Multi-line field with the list of files in the change set. + Each line describes a single file in the format "MD5 filesize + filename". + </entry> + </row> + </tbody> + </tgroup> + </table> </section> <section> @@ -451,8 +626,8 @@ X-Fortune: </thead> <tbody> <row><entry>Format</entry> - <entry>Version of the <filename>.dsc</filename> file format used - </entry></row> + <entry>Version of the file format used. Currently 1.0. + </entry></row> <row><entry>Source</entry> <entry>Name of the source package</entry></row> <row><entry>Version</entry> @@ -461,7 +636,7 @@ X-Fortune: <entry>comma seperated list of binary packages build from this source</entry></row> <row><entry>Origin</entry> - <entry>Name of the organization that procudes this package + <entry>Name of the organization that procuded this package </entry></row> <row><entry>Maintainer</entry> <entry>Maintainer of this package</entry></row> @@ -482,14 +657,6 @@ X-Fortune: </table> <para> - The current version of the <filename>.dsc</filename> 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 <command>dpkg-source</command> will be - fully backwards and upwards compatible within a major version. - </para> - - <para> The Files field contains one line for each file that is contains source for this package (only 2 files are supported: a <filename>.tar.gz</filename> file with the (original) source, and @@ -730,12 +897,80 @@ root adm 0750 /var/log/apache <title>alternatives</title> <para> - 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 <filename>/var/lib/dpkg/alternatives/</filename>. </para> + + <para> + For each alternative there is a single file in + <filename>/var/lib/dpkg/alternatives/</filename> named after the + the alternative it describes. The file is a normal text file: + </para> + + <itemizedlist> + <listitem> + <para> + The first line lists the state of the alternative, either + `manual' or `auto'. + </para> + </listitem> + + <listitem> + <para> + The second line is the filename that the alternative will + provide. + </para> + </listitem> + + <listitem> + <para> + 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. + </para> + </listitem> + + <listitem> + <para> + An empty line + </para> + </listitem> + + <listitem> + <para> + A list of one or more alternatives. Each alternative is made up + as follows: + </para> + + <itemizedlist> + <listitem> + <para> + The filename of the file providing the alternative. + </para> + </listitem> + + <listitem> + <para> + The priority + </para> + </listitem> + + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> </section> </chapter> </book> -<!-- vim: sw=2 +<!-- vi: sw=2 tw=75 --> |