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