| .\" 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 "2011-08-14" "Debian Project" "Debian" |
| .SH NAME |
| deb\-version \- Debian package version number format |
| . |
| .SH SYNOPSIS |
| .RI "[" epoch "\fB:\fP]" upstream-version "[\fB\-\fP" 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 \(co 1996,1997,1998 Ian Jackson and Christian Schwarz |
| .br |
| Copyright \(co 2007 Frank Lichtenheld |
| .sp |
| This is free software; see the GNU General Public Licence version 2 or later |
| for copying conditions. There is NO WARRANTY. |
