|
|
@@ -0,0 +1,128 @@
|
|
|
+.\" Includes text from the Debian Policy probably by Ian Jackson and others
|
|
|
+.\" The copyright given below is that of the whole policy, but probably
|
|
|
+.\" incomplete.
|
|
|
+.\" Conversion to roff by Frank Lichtenheld
|
|
|
+.TH deb\-version 5 "2007-10-06" "Debian Project" "Debian"
|
|
|
+.SH NAME
|
|
|
+deb\-version \- Debian package version number format
|
|
|
+.
|
|
|
+.SH SYNOPSIS
|
|
|
+.RI "[ " epoch ":] " upstream_version " [\-" debian_revision " ]"
|
|
|
+.SH DESCRIPTION
|
|
|
+Version numbers as used for Debian binary and source packages
|
|
|
+consist of three components. These are:
|
|
|
+.TP
|
|
|
+.I epoch
|
|
|
+This is a single (generally small) unsigned integer. It
|
|
|
+may be omitted, in which case zero is assumed. If it is
|
|
|
+omitted then the \fIupstream_version\fP may not
|
|
|
+contain any colons.
|
|
|
+.IP
|
|
|
+It is provided to allow mistakes in the version numbers
|
|
|
+of older versions of a package, and also a package's
|
|
|
+previous version numbering schemes, to be left behind.
|
|
|
+.TP
|
|
|
+.I upstream_version
|
|
|
+This is the main part of the version number. It is
|
|
|
+usually the version number of the original ("upstream")
|
|
|
+package from which the \fI.deb\fP file has been made,
|
|
|
+if this is applicable. Usually this will be in the same
|
|
|
+format as that specified by the upstream author(s);
|
|
|
+however, it may need to be reformatted to fit into the
|
|
|
+package management system's format and comparison
|
|
|
+scheme.
|
|
|
+.IP
|
|
|
+The comparison behavior of the package management system
|
|
|
+with respect to the \fIupstream_version\fP is
|
|
|
+described below. The \fIupstream_version\fP
|
|
|
+portion of the version number is mandatory.
|
|
|
+.IP
|
|
|
+The \fIupstream_version\fP may contain only
|
|
|
+alphanumerics ("A-Za-z0-9") and the characters
|
|
|
+.BR . " " + " " \- " " : " " ~
|
|
|
+(full stop, plus, hyphen, colon, tilde) and should
|
|
|
+start with a digit. If there is no
|
|
|
+\fIdebian_revision\fP then hyphens are not allowed;
|
|
|
+if there is no \fIepoch\fP then colons are not
|
|
|
+allowed.
|
|
|
+.TP
|
|
|
+.I debian_revision
|
|
|
+This part of the version number specifies the version of
|
|
|
+the Debian package based on the upstream version. It
|
|
|
+may contain only alphanumerics and the characters
|
|
|
+.BR + " " . " " ~
|
|
|
+(plus, full stop, tilde) and is
|
|
|
+compared in the same way as the
|
|
|
+\fIupstream_version\fP is.
|
|
|
+.IP
|
|
|
+It is optional; if it isn't present then the
|
|
|
+\fIupstream_version\fP may not contain a hyphen.
|
|
|
+This format represents the case where a piece of
|
|
|
+software was written specifically to be turned into a
|
|
|
+Debian package, and so there is only one "debianisation"
|
|
|
+of it and therefore no revision indication is required.
|
|
|
+.IP
|
|
|
+It is conventional to restart the
|
|
|
+\fIdebian_revision\fP at '1' each time time the
|
|
|
+\fIupstream_version\fP is increased.
|
|
|
+.IP
|
|
|
+Dpkg will break the version
|
|
|
+number apart at the last hyphen in the string (if there
|
|
|
+is one) to determine the \fIupstream_version\fP and
|
|
|
+\fIdebian_revision\fP. The absence of a
|
|
|
+\fIdebian_revision\fP compares earlier than the
|
|
|
+presence of one (but note that the \fIdebian_revision\fP
|
|
|
+is the least significant part of the version number).
|
|
|
+.SS Sorting Algorithm
|
|
|
+The \fIupstream_version\fP and \fIdebian_revision\fP
|
|
|
+parts are compared by the package management system using the
|
|
|
+same algorithm:
|
|
|
+.PP
|
|
|
+The strings are compared from left to right.
|
|
|
+.PP
|
|
|
+First the initial part of each string consisting entirely of
|
|
|
+non-digit characters is determined. These two parts (one of
|
|
|
+which may be empty) are compared lexically. If a difference
|
|
|
+is found it is returned. The lexical comparison is a
|
|
|
+comparison of ASCII values modified so that all the letters
|
|
|
+sort earlier than all the non-letters and so that a tilde
|
|
|
+sorts before anything, even the end of a part. For example,
|
|
|
+the following parts are in sorted order: '~~', '~~a', '~',
|
|
|
+the empty part, 'a'.
|
|
|
+.PP
|
|
|
+Then the initial part of the remainder of each string which
|
|
|
+consists entirely of digit characters is determined. The
|
|
|
+numerical values of these two parts are compared, and any
|
|
|
+difference found is returned as the result of the comparison.
|
|
|
+For these purposes an empty string (which can only occur at
|
|
|
+the end of one or both version strings being compared) counts
|
|
|
+as zero.
|
|
|
+.PP
|
|
|
+These two steps (comparing and removing initial non-digit
|
|
|
+strings and initial digit strings) are repeated until a
|
|
|
+difference is found or both strings are exhausted.
|
|
|
+.PP
|
|
|
+Note that the purpose of epochs is to allow us to leave behind
|
|
|
+mistakes in version numbering, and to cope with situations
|
|
|
+where the version numbering scheme changes. It is
|
|
|
+\fBnot\fP intended to cope with version numbers containing
|
|
|
+strings of letters which the package management system cannot
|
|
|
+interpret (such as 'ALPHA' or 'pre\-'), or with
|
|
|
+silly orderings.
|
|
|
+.SH CAVEATS
|
|
|
+The tilde character and its special sorting properties were introduced
|
|
|
+in dpkg, version 1.10 and some parts of dpkg-dev only gained
|
|
|
+support for it later in the 1.10.x series.
|
|
|
+.SH SEE ALSO
|
|
|
+.BR deb-control (5),
|
|
|
+.BR deb (5),
|
|
|
+.BR dpkg (1)
|
|
|
+.SH AUTHORS
|
|
|
+Copyright © 1996,1997,1998 Ian Jackson and Christian Schwarz.
|
|
|
+.br
|
|
|
+Copyright © 2007 Frank Lichtenheld
|
|
|
+.sp
|
|
|
+This manual is free software; you may redistribute it and/or modify it
|
|
|
+under the terms of the GNU General Public License as published by the
|
|
|
+Free Software Foundation; either version 2, or (at your option) any later
|
|
|
+version.
|
Frank Lichtenheld