1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
<?xml version="1.0"?>
<guide self="ebuild-writing/file-format/">
<chapter>
<title>Ebuild File Format</title>
<body>
<p>
An ebuild is a <c>bash</c> script which is executed within a special environment.
Files should be simple text files with a <c>.ebuild</c> extension.
</p>
</body>
<section>
<title>File Naming Rules</title>
<body>
<p>
An ebuild should be named in the form <c>name-version.ebuild</c>.
</p>
<p>
The name section should contain only lowercase non-accented letters, the digits
0-9, hyphens, underscores and plus characters. Uppercase characters are strongly
discouraged, but technically valid.
</p>
<note>
This is the same as
<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282">
IEEE Std 1003.1-2017, section 3.282 (Portable Filename Character Set)</uri>,
with the exception of the period character and with the addition of the plus
character to keep GTK+ and friends happy.
</note>
<p>
The name must not begin with a hyphen or a plus sign, and must not end
in a hyphen followed by anything that could be mistaken for a version.
</p>
<p>
The version section is more complicated. It consists of one or more numbers
separated by full stop (or period, or dot, or decimal point) characters (eg
<c>1.2.3</c>, <c>20050108</c>). The final number may have a single letter following it
(e.g. <c>1.2b</c>). This letter should not be used to indicate 'beta' status <d/>
Portage treats <c>1.2b</c> as being a later version than <c>1.2</c> or <c>1.2a</c>.
</p>
<p>
There can be a suffix to version indicating the kind of release. In the following table,
what Portage considers to be the 'lowest' version comes first.
</p>
<table>
<tr>
<th>Suffix</th>
<th>Meaning</th>
</tr>
<tr>
<ti><c>_alpha</c></ti>
<ti>Alpha release (earliest)</ti>
</tr>
<tr>
<ti><c>_beta</c></ti>
<ti>Beta release</ti>
</tr>
<tr>
<ti><c>_pre</c></ti>
<ti>Pre release</ti>
</tr>
<tr>
<ti><c>_rc</c></ti>
<ti>Release candidate</ti>
</tr>
<tr>
<ti>(no suffix)</ti>
<ti>Normal release</ti>
</tr>
<tr>
<ti><c>_p</c></ti>
<ti>Patch release</ti>
</tr>
</table>
<p>
Any of these suffixes may be followed by an unsigned integer.
</p>
<p>
These suffixes can be chained together and will be processed iteratively. To
give some examples (the following list is from lowest version to highest):
</p>
<ul>
<li>foo-1.0.0_alpha_pre</li>
<li>foo-1.0.0_alpha_rc1</li>
<li>foo-1.0.0_beta_pre</li>
<li>foo-1.0.0_beta_p1</li>
</ul>
<p>
No integer part of the version may be longer than 18 digits.
</p>
<p>
Finally, version may have a Gentoo revision number in the form <c>-r1</c>. The initial
Gentoo version should have no revision suffix, the first revision should be
<c>-r1</c>, the second <c>-r2</c> and so on. See <uri link="::general-concepts/ebuild-revisions"/>.
Revision numbers are distinguished from patch releases by revision bumps being
changes by Gentoo developers, while patch releases are new releases by upstream (with the exception
of snapshots, see below).
</p>
<p>
Overall, this gives us a filename like <c>libfoo-1.2.5b_pre5-r2.ebuild</c>.
</p>
<p>
The <uri link ="::ebuild-writing/variables/#Version and Name Formatting Issues">
EAPI 7 version commands</uri> may be used to manipulate and extract
ebuild version components.
</p>
<p>
The formal specification of version
<uri link="https://projects.gentoo.org/pms/8/pms.html#x1-250003.2">
format</uri> and the comparison
<uri link="https://projects.gentoo.org/pms/8/pms.html#x1-260003.3">
algorithm</uri> can be found in PMS.
</p>
</body>
<subsection>
<title>Snapshots and live ebuilds</title>
<body>
<p>
When packaging a snapshot of a source repository, there are two commonly used
formats. The first treats the snapshot as a patch to the previous version, and
so the ebuild version is in the format $(last-released-version)_pYYYYMMDD.
Alternatively, the snapshot may be treated as a pre-release to an upcoming
version, usually used when a release is anticipated but not out yet. The format
for this is $(upcoming-version)_preYYYYMMDD.
</p>
<p>
The policy for so-called <e>live</e> ebuilds
(see <uri link="::ebuild-writing/functions/src_unpack/#src_unpack Actions"/>)
is to use <c>9999</c> as the version (or as the last version component). For
packages with more than 4 digits e.g. YYYYMMDD format, <c>99999999</c> is an
acceptable alternative.
</p>
</body>
</subsection>
<subsection>
<title>Binary packages</title>
<body>
<p>
Gentoo usually builds its packages from source. Exceptionally, a binary package
can be provided instead (e.g., if upstream does not provide a source).
Such packages should still follow normal naming conventions and do not need any
special suffix.
</p>
<p>
If a binary package is provided in addition to its open-source based
equivalent, the name of the former should be suffixed with <c>-bin</c>
if necessary for distinction. Examples are packages that are heavy on resources
like CPU time or memory when being built from source.
</p>
</body>
</subsection>
</section>
<section>
<title>Ebuild Header</title>
<body>
<p>
All ebuilds committed to the tree should have a two line header immediately at
the start indicating copyright, followed by an empty line. This must be an
exact copy of the contents of
<c><uri link="https://gitweb.gentoo.org/repo/gentoo.git/tree/header.txt">
header.txt</uri></c> in the top directory of the Gentoo repository.
</p>
<codesample lang="ebuild">
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
</codesample>
<note>
The header previously included a third line with a CVS <c>$Id$</c>
or <c>$Header$</c> keyword. That line was abolished after conversion
to Git by <uri link="https://bugs.gentoo.org/611234">decision of the Gentoo
Council on 28 February 2017</uri> and <e>must not</e> be added any more.
</note>
</body>
</section>
<section>
<title>Indenting and Whitespace</title>
<body>
<p>
Indenting in ebuilds must be done with tabs, one tab per indent
level. Each tab represents four spaces. Tabs should only be used for
indenting, never inside strings.
</p>
<p>
Avoid trailing whitespace: <c>repoman</c> or <c>pkgcheck</c> will warn you about
this if your ebuild contains trailing or leading whitespace (whitespace instead
of tabs for indentation) when you commit.
</p>
<p>
Where possible, try to keep lines no wider than 80 positions. A
'position' is generally the same as a character <d/> tabs are four
positions wide, and multibyte characters are just one position wide.
</p>
</body>
</section>
<section>
<title>Character Set</title>
<body>
<p>
All ebuilds (and eclasses, metadata files, etc.) must use the
UTF-8 character set.
See <uri link="https://www.gentoo.org/glep/glep-0031.html">GLEP 31</uri>
for details.
</p>
</body>
</section>
</chapter>
</guide>
|
GitWeb