1 |
commit: 84b9b5c2aea408b9e490b352885891bb3875714d |
2 |
Author: Daniel Robbins <drobbins <AT> funtoo <DOT> org> |
3 |
AuthorDate: Sun Sep 29 21:50:18 2019 +0000 |
4 |
Commit: Zac Medico <zmedico <AT> gentoo <DOT> org> |
5 |
CommitDate: Sun Sep 29 21:50:18 2019 +0000 |
6 |
URL: https://gitweb.gentoo.org/proj/portage.git/commit/?id=84b9b5c2 |
7 |
|
8 |
man/ebuild.5: Improvements to the ebuild(5) man page |
9 |
|
10 |
The following patch contains several formatting improvements, |
11 |
as well as extended information about KEYWORDS that is easier |
12 |
to understand. The original description started describing Gentoo |
13 |
policy on KEYWORDS without actually explaining what they are and how |
14 |
they work. |
15 |
|
16 |
I have also added missing documentation for the ARCH variable as this |
17 |
was sort of shoe-horned in to the KEYWORDS documentation, and tried |
18 |
to make it clearer what is a technical requirement of Portage the |
19 |
software and what are Gentoo-specific arch team requirements. |
20 |
|
21 |
Bug: https://bugs.gentoo.org/695870 |
22 |
Signed-off-by: Zac Medico <zmedico <AT> gentoo.org> |
23 |
|
24 |
man/ebuild.5 | 160 +++++++++++++++++++++++++++++++++++++++++++---------------- |
25 |
1 file changed, 116 insertions(+), 44 deletions(-) |
26 |
|
27 |
diff --git a/man/ebuild.5 b/man/ebuild.5 |
28 |
index b002f3889..e955907f7 100644 |
29 |
--- a/man/ebuild.5 |
30 |
+++ b/man/ebuild.5 |
31 |
@@ -17,9 +17,10 @@ calculating relationships between packages. Please note that if the atom has |
32 |
not already been emerged, then the latest version available is matched. |
33 |
.TP |
34 |
.B Atom Bases |
35 |
-The base atom is just a full category/packagename. |
36 |
+The base atom is just a full category/packagename. Another name for a full |
37 |
+category/packagename is a \fI"catpkg"\fR. You will find this shorthand\-name |
38 |
+used frequently in Gentoo. Here are some base atoms, a.k.a \fI"catpkgs"\fR: |
39 |
|
40 |
-Examples: |
41 |
.nf |
42 |
.I sys\-apps/sed |
43 |
.I sys\-libs/zlib |
44 |
@@ -31,7 +32,7 @@ It is nice to be more specific and say that only certain versions of atoms are |
45 |
acceptable. Note that versions must be combined with a prefix (see below). |
46 |
Hence you may add a version number as a postfix to the base. |
47 |
|
48 |
-Examples: |
49 |
+\fBExamples\fR: |
50 |
.nf |
51 |
sys\-apps/sed\fI\-4.0.5\fR |
52 |
sys\-libs/zlib\fI\-1.1.4\-r1\fR |
53 |
@@ -51,7 +52,7 @@ Sometimes you want to be able to depend on general versions rather than |
54 |
specifying exact versions all the time. Hence we provide standard boolean |
55 |
operators: |
56 |
|
57 |
-Examples: |
58 |
+\fBExamples\fR: |
59 |
.nf |
60 |
\fI>\fRmedia\-libs/libgd\-1.6 |
61 |
\fI>=\fRmedia\-libs/libgd\-1.6 |
62 |
@@ -71,7 +72,7 @@ means match any revision of the base version specified. So in the |
63 |
example below, we would match versions '1.0.2a', '1.0.2a\-r1', '1.0.2a\-r2', |
64 |
etc... |
65 |
|
66 |
-Example: |
67 |
+\fBExample\fR: |
68 |
.nf |
69 |
\fI~\fRnet\-libs/libnet\-1.0.2a |
70 |
.fi |
71 |
@@ -79,7 +80,7 @@ Example: |
72 |
.I ! |
73 |
means block packages from being installed at the same time. |
74 |
|
75 |
-Example: |
76 |
+\fBExample\fR: |
77 |
.nf |
78 |
\fI!\fRapp\-text/dos2unix |
79 |
.fi |
80 |
@@ -90,7 +91,7 @@ and explicitly disallow them from being temporarily installed |
81 |
simultaneously during a series of upgrades. This syntax is supported |
82 |
beginning with \fBEAPI 2\fR. |
83 |
|
84 |
-Example: |
85 |
+\fBExample\fR: |
86 |
.nf |
87 |
\fI!!\fR<sys\-apps/portage\-2.1.4_rc1 |
88 |
.fi |
89 |
@@ -103,7 +104,7 @@ that comes before the '*' must be a valid version in the absence of the '*'. |
90 |
For example, '2' is a valid version and '2.' is not. Therefore, '2*' is |
91 |
allowed and '2.*' is not. |
92 |
|
93 |
-Examples: |
94 |
+\fBExamples\fR: |
95 |
.nf |
96 |
=dev\-libs/glib\-2\fI*\fR |
97 |
\fI!\fR=net\-fs/samba\-2\fI*\fR |
98 |
@@ -115,7 +116,7 @@ Beginning with \fBEAPI 1\fR, any atom can be constrained to match a specific |
99 |
\fBSLOT\fR. This is accomplished by appending a colon followed by a |
100 |
\fBSLOT\fR: |
101 |
|
102 |
-Examples: |
103 |
+\fBExamples\fR: |
104 |
.nf |
105 |
x11\-libs/qt:3 |
106 |
\fI~\fRx11\-libs/qt-3.3.8:3 |
107 |
@@ -128,7 +129,7 @@ Beginning with \fBEAPI 5\fR, a slot dependency may contain an |
108 |
optional sub\-slot part that follows the regular slot and is |
109 |
delimited by a \fI/\fR character. |
110 |
|
111 |
-Examples: |
112 |
+\fBExamples\fR: |
113 |
.nf |
114 |
dev\-libs/icu:0/0 |
115 |
dev\-libs/icu:0/49 |
116 |
@@ -147,7 +148,7 @@ for runtime dependencies, indicates that the package will not |
117 |
break if the matched package is uninstalled and replaced by |
118 |
a different matching package in a different slot. |
119 |
|
120 |
-Examples: |
121 |
+\fBExamples\fR: |
122 |
.nf |
123 |
dev\-libs/icu:* |
124 |
dev\-lang/perl:* |
125 |
@@ -161,7 +162,7 @@ break unless a matching package with slot and sub\-slot equal |
126 |
to the slot and sub\-slot of the best installed version at the |
127 |
time the package was installed is available. |
128 |
|
129 |
-Examples: |
130 |
+\fBExamples\fR: |
131 |
.nf |
132 |
dev\-libs/icu:= |
133 |
dev\-lang/perl:= |
134 |
@@ -172,7 +173,7 @@ Examples: |
135 |
Indicates that only a specific slot value is acceptable, and |
136 |
otherwise behaves identically to the plain equals slot operator. |
137 |
|
138 |
-Examples: |
139 |
+\fBExamples\fR: |
140 |
.nf |
141 |
dev\-libs/icu:0= |
142 |
dev\-lang/perl:0= |
143 |
@@ -190,7 +191,7 @@ dependencies. The sub\-slot part must not be omitted here |
144 |
is considered to have an implicit sub\-slot which is equal to |
145 |
the regular slot). |
146 |
|
147 |
-Examples: |
148 |
+\fBExamples\fR: |
149 |
.nf |
150 |
dev\-libs/icu:0/0= |
151 |
dev\-libs/icu:0/49= |
152 |
@@ -238,7 +239,7 @@ immediately following a flag with either \fI(+)\fR or \fI(\-)\fR. Use |
153 |
\fI(+)\fR to behave as if a missing flag is present and enabled, or |
154 |
\fI(\-)\fR to behave as if it is present and disabled: |
155 |
|
156 |
-Examples: |
157 |
+\fBExamples\fR: |
158 |
.nf |
159 |
media\-video/ffmpeg[threads(+)] |
160 |
media\-video/ffmpeg[-threads(\-)] |
161 |
@@ -280,7 +281,7 @@ That way the default is the superior GTK2 library. |
162 |
When a package can work with a few different packages but a virtual is not |
163 |
appropriate, this syntax can easily be used. |
164 |
|
165 |
-Example: |
166 |
+\fBExample\fR: |
167 |
.nf |
168 |
|| ( |
169 |
app\-games/unreal\-tournament |
170 |
@@ -295,7 +296,7 @@ use either. Adding a virtual is inappropriate due to the small scope of it. |
171 |
Another good example is when a package can be built with multiple video |
172 |
interfaces, but it can only ever have just one. |
173 |
|
174 |
-Example: |
175 |
+\fBExample\fR: |
176 |
.nf |
177 |
|| ( |
178 |
sdl? ( media\-libs/libsdl ) |
179 |
@@ -314,58 +315,85 @@ the user does not specify any of the previous choices. |
180 |
Note that if any of the packages listed are already merged, the package manager |
181 |
will use that to consider the dependency satisfied. |
182 |
|
183 |
-.SH "VARIABLES" |
184 |
-.TP |
185 |
-.B Usage Notes |
186 |
-\- Variables defined in \fBmake.conf\fR(5) are available for use in |
187 |
+.SS Variable Usage Notes |
188 |
+.RS |
189 |
+.IP \(bu 2 |
190 |
+Variables defined in \fBmake.conf\fR(5) are available for use in |
191 |
ebuilds (except Portage\-specific variables, which might be not supported by |
192 |
other package managers). |
193 |
-.br |
194 |
-\- When assigning values to variables in ebuilds, you \fIcannot have a |
195 |
+.IP \(bu |
196 |
+When assigning values to variables in ebuilds, you \fIcannot have a |
197 |
space\fR between the variable name and the equal sign. |
198 |
-.br |
199 |
-\- Variable values should only contain characters that are members of the |
200 |
+.IP \(bu |
201 |
+Variable values should only contain characters that are members of the |
202 |
\fBascii\fR(7) character set. This requirement is mandated by \fBGLEP 31\fR. |
203 |
+.RE |
204 |
+ |
205 |
+.SS "Variables Used In Ebuilds" |
206 |
+.TP |
207 |
+.B ARCH |
208 |
+This variable contains the official Gentoo\-specific acronym for the current |
209 |
+architecture of the running system. For an authoritative list please |
210 |
+review /var/db/repos/gentoo/profiles/arch.list. |
211 |
.TP |
212 |
.B P |
213 |
This variable contains the package name without the ebuild revision. |
214 |
This variable must NEVER be modified. |
215 |
|
216 |
-xfree\-4.2.1\-r2.ebuild \-\-> $P=='xfree\-4.2.1' |
217 |
+\fBExample\fR: |
218 |
+.nf |
219 |
+ x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIx11\-base/xorg\-server\-1.20.5\fR' |
220 |
+.fi |
221 |
.TP |
222 |
.B PN |
223 |
Contains the name of the script without the version number. |
224 |
|
225 |
-xfree\-4.2.1\-r2.ebuild \-\-> $PN=='xfree' |
226 |
+\fBExample\fR: |
227 |
+.nf |
228 |
+ x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIx11\-base/xorg\-server\fR' |
229 |
+.fi |
230 |
.TP |
231 |
.B PV |
232 |
Contains the version number without the revision. |
233 |
|
234 |
-xfree\-4.2.1\-r2.ebuild \-\-> $PV=='4.2.1' |
235 |
+\fBExample\fR: |
236 |
+.nf |
237 |
+ x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fI1.20.5\fR' |
238 |
+.fi |
239 |
.TP |
240 |
.B PR |
241 |
Contains the revision number or 'r0' if no revision number exists. |
242 |
|
243 |
-xfree\-4.2.1\-r2.ebuild \-\-> $PR=='r2' |
244 |
+\fBExample\fR: |
245 |
+.nf |
246 |
+ x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIr2\fR' |
247 |
+.fi |
248 |
.TP |
249 |
.B PVR |
250 |
Contains the version number with the revision (if non-zero). |
251 |
|
252 |
+\fBExample\fR: |
253 |
.nf |
254 |
-xfree\-4.2.1.ebuild \-\-> $PVR=='4.2.1' |
255 |
-xfree\-4.2.1\-r2.ebuild \-\-> $PVR=='4.2.1\-r2' |
256 |
+ x11\-base/xorg\-server\-1.20.5 \-\-> '\fI1.20.5\fR' |
257 |
+ x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fI1.20.5\-r2\fR' |
258 |
.fi |
259 |
.TP |
260 |
.B PF |
261 |
Contains the full package name \fBPN\fR\-\fBPVR\fR |
262 |
|
263 |
+\fBExamples\fR: |
264 |
.nf |
265 |
-xfree\-4.2.1.ebuild \-\-> $PF=='xfree\-4.2.1' |
266 |
-xfree\-4.2.1\-r2.ebuild \-\-> $PF=='xfree\-4.2.1\-r2' |
267 |
+ x11\-base/xorg\-server\-1.20.5 \-\-> '\fIxorg\-server\-1.20.5\fR' |
268 |
+ x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIxorg\-server\-1.20.5\-r2\fR' |
269 |
.fi |
270 |
.TP |
271 |
.B CATEGORY |
272 |
Contains the package category name. |
273 |
+ |
274 |
+\fBExample\fR: |
275 |
+.nf |
276 |
+ x11\-base/xorg\-server\-1.20.5\-r2 \-\-> '\fIx11\-base\fR' |
277 |
+.fi |
278 |
.TP |
279 |
.B A |
280 |
Contains all source files required for the package. This variable must |
281 |
@@ -543,17 +571,61 @@ file name, should be separated by whitespace. |
282 |
Should contain a list of URIs for the sources main sites and other further |
283 |
package dependent information. |
284 |
.TP |
285 |
-.B KEYWORDS\fR = \fI[\-~][x86,ppc,sparc,mips,alpha,arm,hppa] |
286 |
-Should contain appropriate list of arches that the ebuild is know to |
287 |
-work/not work. By default if you do not know if an ebuild runs under |
288 |
-a particular arch simply omit that KEYWORD. If the ebuild will not |
289 |
-work on that arch include it as \-ppc for example. If the ebuild is |
290 |
-being submitted for inclusion, it must have ~arch set for architectures |
291 |
-where it has been PROVEN TO WORK. (Packages KEYWORDed this way may be |
292 |
-unmasked for testing by setting ACCEPT_KEYWORDS="~arch" on the command |
293 |
-line, or in \fBmake.conf\fR(5)) For an authoritative list please review |
294 |
-/var/db/repos/gentoo/profiles/arch.list. Please keep this list in |
295 |
-alphabetical order. |
296 |
+.B KEYWORDS\fR = \fI[\-~][x86,ppc,sparc,mips,alpha,arm,hppa,...] |
297 |
+.P |
298 |
+ |
299 |
+KEYWORDS works in conjunction with ACCEPT_KEYWORDS (see \fBmake.conf\fR(5)) |
300 |
+to implement a system of creating sets of different types of packages |
301 |
+which can then be masked or unmasked en masse. In the Gentoo Linux |
302 |
+project, they are used by the Gentoo arch teams to define what ebuilds |
303 |
+are included in a particular CPU architecture's set of stable and unstable |
304 |
+unmasked packages. |
305 |
+ |
306 |
+Here's how they work. For purposes of explanation, let's assume you have |
307 |
+a stable x86\-64bit system, typically referred to as "amd64". |
308 |
+ARCH would be defined as "amd64". If you were using the stable build of |
309 |
+Gentoo Linux, then ACCEPT_KEYWORDS would be set to "amd64" via profiles. |
310 |
+Any ebuild that then has |
311 |
+"amd64" in KEYWORDS will be unmasked by default. |
312 |
+ |
313 |
+On an "unstable" |
314 |
+amd64 system, ACCEPT_KEYWORDS will be set to "amd64 ~amd64", with the |
315 |
+tilde denoting "unstable." Then, if an ebuild has \fIeither\fR |
316 |
+"amd64" or "~amd64" in KEYWORDS, it will be keyword unmasked by default on |
317 |
+that system. Similarly, if an ebuild is known to not be compatible |
318 |
+with a particular architecture, the "\-" prefix ( i.e. "\-amd64") setting |
319 |
+can be specified to mask it only on that arch. |
320 |
+.P |
321 |
+If you are developing ebuilds for Gentoo Linux, there are certain |
322 |
+policies regarding KEYWORDS that you are expected to follow in order |
323 |
+to align with Gentoo's arch team workflow. The most important |
324 |
+policies are listed below: |
325 |
+.RS |
326 |
+.IP \(bu 2 |
327 |
+If you do not know if an ebuild runs under a particular arch, then do not |
328 |
+specify it in KEYWORDS. |
329 |
+It will then be masked by default on that architecture. |
330 |
+.IP \(bu |
331 |
+If the ebuild is known not to work on an arch, disable that arch in KEYWORDS. |
332 |
+This would be done by specifying "\-ppc", for example. This will ensure that |
333 |
+it is explicitly keyword\-masked for that architecture. |
334 |
+.IP \(bu |
335 |
+When submitting an ebuild to Gentoo Linux, it is the project policy to only |
336 |
+have "~arch" set in KEYWORDS |
337 |
+for the architecture for which it has been successfully tested, and no more. |
338 |
+As the ebuild receives more testing, Gentoo arch teams will gradually expand |
339 |
+the KEYWORDS settings to "bump" the package to unstable, and possibly stable. |
340 |
+ |
341 |
+It is possible to customize the behavior of ACCEPT_KEYWORDS and KEYWORDS on |
342 |
+a per\-package basis using package.accept_keywords and package.keywords files |
343 |
+in profiles. See \fBportage\fR(5) for more information on using these files. |
344 |
+.RE |
345 |
+.P |
346 |
+Note that while other Gentoo\-based projects |
347 |
+have KEYWORDS and ACCEPT_KEYWORDS, they likely will not have exactly |
348 |
+the same policies regarding their use. Therefore, it is necessary that you |
349 |
+research their specific policies and how they differ from Gentoo. |
350 |
+.RE |
351 |
.TP |
352 |
.B SLOT |
353 |
This sets the SLOT for packages that may need to have multiple versions |