chiark - git - mdw - dpkg/blob - man/deb-version.man

   1 .\" dpkg manual page - deb-version(5)
   2 .\"
   3 .\" Copyright © 1996-1998 Ian Jackson and Christian Schwarz
   4 .\"   for parts of the text reused from the Debian Policy
   5 .\" Copyright © 2007 Frank Lichtenheld <djpig@debian.org>
   6 .\" Copyright © 2011, 2013, 2015 Guillem Jover <guillem@debian.org>
   7 .\"
   8 .\" This is free software; you can redistribute it and/or modify
   9 .\" it under the terms of the GNU General Public License as published by
  10 .\" the Free Software Foundation; either version 2 of the License, or
  11 .\" (at your option) any later version.
  12 .\"
  13 .\" This is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public License
  19 .\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
  20 .
  21 .TH deb\-version 5 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
  22 .nh
  23 .SH NAME
  24 deb\-version \- Debian package version number format
  25 .
  26 .SH SYNOPSIS
  27 .RI "[" epoch "\fB:\fP]" upstream-version "[\fB\-\fP" debian-revision "]"
  28 .SH DESCRIPTION
  29 Version numbers as used for Debian binary and source packages
  30 consist of three components. These are:
  31 .TP
  32 .I epoch
  33 This is a single (generally small) unsigned integer.  It
  34 may be omitted, in which case zero is assumed.  If it is
  35 omitted then the \fIupstream-version\fP may not
  36 contain any colons.
  37 .IP
  38 It is provided to allow mistakes in the version numbers
  39 of older versions of a package, and also a package's
  40 previous version numbering schemes, to be left behind.
  41 .TP
  42 .I upstream-version
  43 This is the main part of the version number.  It is
  44 usually the version number of the original (“upstream”)
  45 package from which the \fI.deb\fP file has been made,
  46 if this is applicable.  Usually this will be in the same
  47 format as that specified by the upstream author(s);
  48 however, it may need to be reformatted to fit into the
  49 package management system's format and comparison
  50 scheme.
  51 .IP
  52 The comparison behavior of the package management system
  53 with respect to the \fIupstream-version\fP is
  54 described below. The \fIupstream-version\fP
  55 portion of the version number is mandatory.
  56 .IP
  57 The \fIupstream-version\fP may contain only
  58 alphanumerics (“A-Za-z0-9”) and the characters
  59 .BR . " " + " " \- " " : " " ~
  60 (full stop, plus, hyphen, colon, tilde) and should
  61 start with a digit.  If there is no
  62 \fIdebian-revision\fP then hyphens are not allowed;
  63 if there is no \fIepoch\fP then colons are not
  64 allowed.
  65 .TP
  66 .I debian-revision
  67 This part of the version number specifies the version of
  68 the Debian package based on the upstream version.  It
  69 may contain only alphanumerics and the characters
  70 .BR + " " . " " ~
  71 (plus, full stop, tilde) and is
  72 compared in the same way as the
  73 \fIupstream-version\fP is.
  74 .IP
  75 It is optional; if it isn't present then the
  76 \fIupstream-version\fP may not contain a hyphen.
  77 This format represents the case where a piece of
  78 software was written specifically to be turned into a
  79 Debian package, and so there is only one “debianization”
  80 of it and therefore no revision indication is required.
  81 .IP
  82 It is conventional to restart the
  83 \fIdebian-revision\fP at ‘1’ each time the
  84 \fIupstream-version\fP is increased.
  85 .IP
  86 Dpkg will break the version
  87 number apart at the last hyphen in the string (if there
  88 is one) to determine the \fIupstream-version\fP and
  89 \fIdebian-revision\fP. The absence of a
  90 \fIdebian-revision\fP compares earlier than the
  91 presence of one (but note that the \fIdebian-revision\fP
  92 is the least significant part of the version number).
  93 .SS Sorting algorithm
  94 The \fIupstream-version\fP and \fIdebian-revision\fP
  95 parts are compared by the package management system using the
  96 same algorithm:
  97 .PP
  98 The strings are compared from left to right.
  99 .PP
 100 First the initial part of each string consisting entirely of
 101 non-digit characters is determined.  These two parts (one of
 102 which may be empty) are compared lexically.  If a difference
 103 is found it is returned.  The lexical comparison is a
 104 comparison of ASCII values modified so that all the letters
 105 sort earlier than all the non-letters and so that a tilde
 106 sorts before anything, even the end of a part.  For example,
 107 the following parts are in sorted order: ‘~~’, ‘~~a’, ‘~’,
 108 the empty part, ‘a’.
 109 .PP
 110 Then the initial part of the remainder of each string which
 111 consists entirely of digit characters is determined.  The
 112 numerical values of these two parts are compared, and any
 113 difference found is returned as the result of the comparison.
 114 For these purposes an empty string (which can only occur at
 115 the end of one or both version strings being compared) counts
 116 as zero.
 117 .PP
 118 These two steps (comparing and removing initial non-digit
 119 strings and initial digit strings) are repeated until a
 120 difference is found or both strings are exhausted.
 121 .PP
 122 Note that the purpose of epochs is to allow us to leave behind
 123 mistakes in version numbering, and to cope with situations
 124 where the version numbering scheme changes.  It is
 125 \fBnot\fP intended to cope with version numbers containing
 126 strings of letters which the package management system cannot
 127 interpret (such as ‘ALPHA’ or ‘pre\-’), or with
 128 silly orderings.
 129 .SH NOTES
 130 The tilde character and its special sorting properties were introduced
 131 in dpkg 1.10 and some parts of the dpkg build scripts only gained
 132 support for it later in the 1.10.x series.
 133 .SH SEE ALSO
 134 .BR deb\-control (5),
 135 .BR deb (5),
 136 .BR dpkg (1)