Commit | Line | Data |
---|---|---|
1479465f GJ |
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) |