man/deb-version.pod

   1 # dpkg manual page - deb-version(7)
   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 =encoding utf8
  22
  23 =head1 NAME
  24
  25 deb-version - Debian package version number format
  26
  27 =head1 SYNOPSIS
  28
  29 [I<epoch>B<:>]I<upstream-version>[B<->I<debian-revision>]
  30
  31 =head1 DESCRIPTION
  32
  33 Version numbers as used for Debian binary and source packages
  34 consist of three components.
  35 These are:
  36
  37 =over
  38
  39 =item I<epoch>
  40
  41 This is a single (generally small) unsigned integer.
  42 It may be omitted, in which case zero is assumed.
  43 If it is
  44 omitted then the I<upstream-version> may not
  45 contain any colons.
  46
  47 It is provided to allow mistakes in the version numbers
  48 of older versions of a package, and also a package's
  49 previous version numbering schemes, to be left behind.
  50
  51 =item I<upstream-version>
  52
  53 This is the main part of the version number.
  54 It is
  55 usually the version number of the original (“upstream”)
  56 package from which the I<.deb> file has been made,
  57 if this is applicable.
  58 Usually this will be in the same
  59 format as that specified by the upstream author(s);
  60 however, it may need to be reformatted to fit into the
  61 package management system's format and comparison
  62 scheme.
  63
  64 The comparison behavior of the package management system
  65 with respect to the I<upstream-version> is
  66 described below.
  67 The I<upstream-version>
  68 portion of the version number is mandatory.
  69
  70 The I<upstream-version> may contain only
  71 alphanumerics (“A-Za-z0-9”) and the characters
  72 B<.> B<+> B<-> B<:> B<~>
  73 (full stop, plus, hyphen, colon, tilde) and should
  74 start with a digit.
  75 If there is no
  76 I<debian-revision> then hyphens are not allowed;
  77 if there is no I<epoch> then colons are not
  78 allowed.
  79
  80 =item I<debian-revision>
  81
  82 This part of the version number specifies the version of
  83 the Debian package based on the upstream version.
  84 It
  85 may contain only alphanumerics and the characters
  86 B<+> B<.> B<~>
  87 (plus, full stop, tilde) and is
  88 compared in the same way as the
  89 I<upstream-version> is.
  90
  91 It is optional; if it isn't present then the
  92 I<upstream-version> may not contain a hyphen.
  93 This format represents the case where a piece of
  94 software was written specifically to be turned into a
  95 Debian package, and so there is only one “debianization”
  96 of it and therefore no revision indication is required.
  97
  98 It is conventional to restart the
  99 I<debian-revision> at ‘1’ each time the
 100 I<upstream-version> is increased.
 101
 102 Dpkg will break the version
 103 number apart at the last hyphen in the string (if there
 104 is one) to determine the I<upstream-version> and
 105 I<debian-revision>.
 106 The absence of a
 107 I<debian-revision> compares earlier than the
 108 presence of one (but note that the I<debian-revision>
 109 is the least significant part of the version number).
 110
 111 =back
 112
 113 =head2 Sorting algorithm
 114
 115 The I<upstream-version> and I<debian-revision>
 116 parts are compared by the package management system using the
 117 same algorithm:
 118
 119 The strings are compared from left to right.
 120
 121 First the initial part of each string consisting entirely of
 122 non-digit characters is determined.
 123 These two parts (one of which may be empty) are compared lexically.
 124 If a difference is found it is returned.
 125 The lexical comparison is a
 126 comparison of ASCII values modified so that all the letters
 127 sort earlier than all the non-letters and so that a tilde
 128 sorts before anything, even the end of a part.
 129 For example,
 130 the following parts are in sorted order: ‘~~’, ‘~~a’, ‘~’,
 131 the empty part, ‘a’.
 132
 133 Then the initial part of the remainder of each string which
 134 consists entirely of digit characters is determined.
 135 The
 136 numerical values of these two parts are compared, and any
 137 difference found is returned as the result of the comparison.
 138 For these purposes an empty string (which can only occur at
 139 the end of one or both version strings being compared) counts
 140 as zero.
 141
 142 These two steps (comparing and removing initial non-digit
 143 strings and initial digit strings) are repeated until a
 144 difference is found or both strings are exhausted.
 145
 146 Note that the purpose of epochs is to allow us to leave behind
 147 mistakes in version numbering, and to cope with situations
 148 where the version numbering scheme changes.
 149 It is
 150 B<not> intended to cope with version numbers containing
 151 strings of letters which the package management system cannot
 152 interpret (such as ‘ALPHA’ or ‘pre-’), or with
 153 silly orderings.
 154
 155 =head1 NOTES
 156
 157 The tilde character and its special sorting properties were introduced
 158 in dpkg 1.10 and some parts of the dpkg build scripts only gained
 159 support for it later in the 1.10.x series.
 160
 161 =head1 SEE ALSO
 162
 163 L<deb-control(5)>,
 164 L<deb(5)>,
 165 L<dpkg(1)>