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
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
|
<?xml version='1.0'?>
<!-- gentoo-howto.xml,v 1.20 2001/08/17 21:52:07 drobbins Exp -->
<guide link="/doc/gentoo-howto.html">
<title>Gentoo Linux Developers HOWTO</title>
<author title="Author"><mail link="woodchip@gentoo.org">Donny Davies</mail></author>
<author title="Author"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
<author title="Author"><mail link="pete@gentoo.org">Peter Gavin</mail></author>
<abstract>This document describes the Gentoo Linux Portage system, how
to create new packages for Gentoo, and is also meant to be somewhat of
a standard for the Gentoo Developers. It is a work in progress, and is
constantly being updated and changed. It is by no means
complete.</abstract>
<version>1.1</version>
<date>21 Sep 2001</date>
<!--
Contents
I. Introduction
II. The Portage Tree
A. What (Not) to Put in the Portage Tree
B. Categories
C. The files Directory
III. .ebuild Files
A. Naming .ebuild Files
B. Contents of an .ebuild File
C. Rules for Writing an .ebuild File
IV. Filesystem Locations
A. Introduction to the FHS
B. How to Fit Your Packages into the Filesystem
V. The Portage Scripts and Utilities
A. Public Scripts
B. Private Scripts
VI. Package Dependencies
-->
<chapter>
<title>The Portage tree</title>
<section>
<title>Introduction</title>
<body><p>The Portage tree is typically found at <path>/usr/portage</path>
and is organized in a heirarchical structure consisting of category directories,
followed by specific package directories. Here's an example; you can find
the <path>util-linux-2.11g.ebuild</path> file in the <path>/usr/portage/sys-apps/util-linux</path>
directory. There may be several other versions of <c>util-linux</c> ebuilds alongside
<path>util-linux-2.11g.ebuild</path>. This is because <e>all ebuilds for a particular
package (irregardless of version)</e>, share the same <path>mycat/mypkg</path> directory in
<path>/usr/portage</path>.
</p></body>
</section>
<section>
<title> What (not) to put in the Portage tree</title>
<body><p>In general, the Portage tree should only be used for storing
<path>.ebuild</path> files, as well as any relatively small companion files,
such as patches or sample configuration files. These types of files should be
placed in the <path>/usr/portage/mycat/mypkg/files</path> directory to keep the
main <path>mycat/mypkg</path> directory uncluttered. Also, in general, it's
not a good idea for developers to add binary (non-ASCII) files to CVS.
However, if this is necessary (for example, if you need to add a small PNG
graphic for whatever reason, be sure to add it to CVS by using the <c>-kb</c>
option, like so: </p>
<pre>
# <i>cvs add -kb myphoto.png</i>
</pre>
<p>The <c>-kb</c> option tells CVS that <path>myphoto.png</path> is a binary
file and should be treated specially. For example, merging the differences
between two different versions of this file should not be allowed to happen,
for obvious reasons. Also, speaking of merging changes, any patches you add to
Portage should generally <e>not</e> be compressed. This will allow CVS to
merge changes and inform developers of conflicts correctly. </p>
</body>
</section>
<!--
<section>
<title>Categories</title>
<body><p>The categories are defined as follows:</p>
<table><tr><th>Category</th><th>Description</th></tr>
<tr><ti><path>app-admin</path></ti><ti>non-critical system administration utilities</ti></tr>
<tr><ti><path>app-arch</path></ti><ti>non-critical archival/compression utilities </ti></tr>
<tr><ti><path>app-cdr</path></ti><ti> CD recording utilities </ti></tr>
<tr><ti><path>app-crypt</path></ti><ti> Cryptography related apps </ti></tr>
<tr><ti><path>app-doc</path></ti><ti>application documentation </ti></tr>
<tr><ti><path>app-editors</path></ti><ti>non-critical text editors </ti></tr>
<tr><ti><path>app-emulation</path></ti><ti>packages for emulating other systems/OSes </ti></tr>
<tr><ti><path>app-games</path></ti><ti>Games!!! 'Nough said </ti></tr>
<tr><ti><path>app-misc</path></ti><ti>applications that don't fit anywhere else </ti></tr>
<tr><ti><path>app-office</path></ti><ti>office-type (word processing, spreadsheet, etc.) packages </ti></tr>
<tr><ti><path>app-shells</path></ti><ti>non-critical shells and command interpreters </ti></tr>
<tr><ti><path>app-text</path></ti><ti>text processing, spell checkers, and document formatting packages </ti></tr>
<tr><ti><path>dev-db</path></ti><ti>database libraries </ti></tr>
<tr><ti><path>dev-java</path></ti><ti>java classes/packages/etc. </ti></tr>
<tr><ti><path>dev-lang</path></ti><ti>compilers and interpreters for different languages </ti></tr>
<tr><ti><path>dev-libs</path></ti><ti>miscellaneous developer's libraries </ti></tr>
<tr><ti><path>dev-perl</path></ti><ti>perl modules </ti></tr>
<tr><ti><path>dev-python</path></ti><ti>python modules </ti></tr>
<tr><ti><path>dev-ruby</path></ti><ti>ruby modules </ti></tr>
<tr><ti><path>dev-tcltk</path></ti><ti>Tcl-Tk modules </ti></tr>
<tr><ti><path>dev-util</path></ti><ti>various developers utilities </ti></tr>
<tr><ti><path>gnome-apps</path></ti><ti>applications for GNOME </ti></tr>
<tr><ti><path>gnome-base</path></ti><ti>base GNOME packages </ti></tr>
<tr><ti><path>gnome-libs</path></ti><ti>non-essential GNOME libraries </ti></tr>
<tr><ti><path>gnome-office</path></ti><ti>office packages for gnome </ti></tr>
<tr><ti><path>kde-base</path></ti><ti>main KDE distribution </ti></tr>
<tr><ti><path>kde-i18n</path></ti><ti>KDE internationalization packages </ti></tr>
<tr><ti><path>media-gfx</path></ti><ti>graphics-related programs </ti></tr>
<tr><ti><path>media-libs</path></ti><ti> libraries for manipulating different media, including accessing multimedia peripherals of your computer (sound card, video card, etc.) </ti></tr>
<tr><ti><path>media-sound</path></ti><ti>programs related to sound, including cd-audio and sound encoding </ti></tr>
<tr><ti><path>media-video</path></ti><ti>programs related to video, including video codecs and players </ti></tr>
<tr><ti><path>net-analyzer</path></ti><ti>network usage statistics monitors/analyzers </ti></tr>
<tr><ti><path>net-dialup</path></ti><ti>network dialup clients and servers such as pppd </ti></tr>
<tr><ti><path>net-fs</path></ti><ti>network filesystems </ti></tr>
<tr><ti><path>net-ftp</path></ti><ti>ftp servers and clients </ti></tr>
<tr><ti><path>net-im</path></ti><ti>Instant Messaging servers and clients </ti></tr>
<tr><ti><path>net-irc</path></ti><ti>irc servers and clients </ti></tr>
<tr><ti><path>net-libs</path></ti><ti>networking-related libraries </ti></tr>
<tr><ti><path>net-mail</path></ti><ti>MTAs and MUAs </ti></tr>
<tr><ti><path>net-misc</path></ti><ti>miscellaneous servers, clients, firewalls, etc. </ti></tr>
<tr><ti><path>net-nds</path></ti><ti>NIS/NIS+ and other network directory services </ti></tr>
<tr><ti><path>net-news</path></ti><ti>Usenet servers and clients </ti></tr>
<tr><ti><path>net-print</path></ti><ti>print servers and clients </ti></tr>
<tr><ti><path>net-www</path></ti><ti>http/www servers and clients </ti></tr>
<tr><ti><path>sys-apps</path></ti><ti>system-critical applications and utilities </ti></tr>
<tr><ti><path>sys-devel</path></ti><ti>base development packages, such as gcc and make </ti></tr>
<tr><ti><path>sys-kernel</path></ti><ti>Linux kernels and kernel source packages </ti></tr>
<tr><ti><path>sys-libs</path></ti><ti>system-critical libraries such as glibc </ti></tr>
<tr><ti><path>x11-base</path></ti><ti>base X packages, such as XFree86 and drivers for various video cards </ti></tr>
<tr><ti><path>x11-libs</path></ti><ti>widget sets and other X-specific libraries</ti></tr>
<tr><ti><path>x11-terms</path></ti><ti>X-based terminal emulators </ti></tr>
<tr><ti><path>x11-wm</path></ti><ti>X window managers </ti></tr>
</table>
<note>If a new category is created (please get permission first!),
then the category needs to be added to
<path>/usr/lib/python2.0/portage.py</path>.
</note>
</body>
</section>
-->
<section>
<title>The files Directory</title>
<body>
<p>As noted earlier, under each package subdirectory is a <path>files</path>
directory. Any patches, configuration files, or other ancillary files your
package might require should be added to this directory. You may want to
consider naming patches you create yourself just to get your package to build
with a version-specific name, such as <path>mypkg-1.0-gentoo.diff</path>. Also
note that the <path>gentoo</path> extension informs people that this patch was
created by us, the Gentoo Linux developers, rather than having been grabbed
from a mailing list or somewhere else. Again, you should not compress these
diffs because cvs does not play well with binary files. </p>
<p>Consider adding a suffix such as <path>mypkg-1.0</path> to the tail of every
file you put into the <path>files</path> directory, so that the files used for
each individual version of your ebuild scripts are distinguishable from one
another, and so that the changes between different revisions are visible. This
is generally a really good idea. :) You may want to use a different suffix if
coarser or finer granularity is required.</p>
<p>If you have many files that should go into the files directory, consider
creating subdirectories such as <path>files/mypkg-1.0</path> and putting the
relevant files in the appropriate subdirectory. If you use this method, you do
not need to add suffix the names of the files in this directory, which is often
more convenient.</p>
</body>
</section>
</chapter>
<chapter>
<title>ebuild scripts</title>
<section>
<title>Introduction</title>
<body>
<p>ebuild scripts are the basis for the entire portage system. They contain all
the information required to download, unpack, compile and install a set of
sources, as well as how to perform any optional pre/post install/removal or
configuration functions. While most of Portage is written in Python, the ebuild
scripts themselves are written in bash, since using bash allows us to call commands
as we would from the command-line. One of the important design principles behind
ebuild scripts is to have the commands therein be analogs of those one would type
on the command-line if installing the package manually. For this purpose, having
bash syntax is a good thing.</p>
<p>
Ebuild scripts are interpreted by the <c>ebuild</c> and <c>emerge</c> commands.
Think of the <c>ebuild</c> command as a low-level building tool. It can build
and install a single ebuild, but no more. It will check to see if dependencies
are satisfied, but it will not attempt to auto-resolve them. On the other hand
<c>emerge</c> is a high level engine for <c>ebuild</c>, and has the ability to
auto-merge dependencies if needed, perform "pretend" merges so that user can see
what ebuilds <e>would</e> be merged, and more. Generally, <c>emerge</c> blows
<c>ebuild</c> out of the water except in one area. With <c>ebuild</c>, you can
incrementally step through the various parts of a package installation (fetching,
unpacking, compiling, installing and merging) one at a time. For developers,
this is an invaluable debugging tool, because it allows you to isolate ebuild
problems to a specific portion of the build process.
</p>
</body>
</section>
<section>
<title>Naming ebuild Files</title>
<body>
<p>Ebuild file names consist of four logical sections:</p>
<p>The first section is the package name, which should only contain lowercase
letters, the digits 0-9, and any number of single hyphen ('-') characters.
Some examples are <c>util-linux</c>, <c>sysklogd</c> and <c>glibc</c>. </p>
<p>The second section is the version of the package, which should normally be
same as the version on the main source tarball. The version is normally made up
of two or three numbers separated by periods, such as <c>1.2</c> or
<c>4.5.2</c> (although very long period-separated number sequences <e>are</e>
supported), and may have a single letter immediately following the last digit,
e.g., <c>1.4b</c> or <c>2.6h</c>. The package version is joined to the package
name with a hyphen; for example: <c>foo-1.0</c>, <c>bar-2.4.6</c>, etc.</p>
<impo>If you're thinking of using a trailing letter in your version string,
note that the trailing letter should <e>not</e> be used to signify alpha or beta
status for the package, since alphas and betas are <e>prereleases</e> and
letter revisions are <e>newer versions</e>. This is an important distinction
because Portage uses an ebuild's version number to determine if it is newer
or older than other packages with the same category and name. It's very
important that version numbers faithfully represent the version of the
package so that Portage properly performs its dependency checking duties.</impo>
<p>The third (optional) section contains a special suffix; either
<c>_alpha</c>, <c>_beta</c>, <c>_pre</c> or <c>_rc</c>. Any of these suffixes
may be immediately followed my a number, e.g., <c>linux-2.4.0_pre10</c>;
Assuming identical version parts, an <c>_alpha</c> package is older than
<c>_beta</c>, <c>_beta</c> older than <c>_pre</c>, and <c>_pre</c> older than
<c>_rc</c>.
</p>
<note>An <c>_rc</c> package is older than a package without an underscore
prefix (i.e. <c>linux-2.4.0</c>), and <c>linux-2.4.0</c> is older than a
package with a single letter prefix, i.e. <c>linux-2.4.0b</c>. As you would
expect, the <c>linux-2.4.0b</c> package is considered older than
<c>linux-2.4.0c</c>. Again this versioning information is important, as
Portage uses it internally to determine whether one package or ebuild is newer
than another with the same category and name.</note>
<p>The fourth (optional) section of the package name is the Gentoo Linux-specific <e>revision</e> number,
which is specified by <c>-r#</c>, where <c>#</c> is an integer,
e.g. <c>package-4.5.3-r3</c>. This revision number is independent of
the version of the source tarball and is used to inform people that
a new and improved Gentoo Linux rev of a particular package is available.
</p>
<p>
If you make non-trivial improvements to an existing ebuild file, you should
copy the ebuild file to a new file with the revision number incremented by 1.
Initial releases normally have no revision number, e.g.
<path>package-4.5.3</path> and are considered by Portage to have a a revision
number of zero. This means that counting goes as follows: <c>1.0</c> (initial
version), <c>1.0-r1</c>, <c>1.0-r2</c>, etc.
</p>
<p>And I suppose that we actually have a <e>fifth</e> section of the ebuild name -- the
<c>.ebuild</c> extension itself.
</p>
</body>
</section>
<section>
<title>Contents of an ebuild File</title>
<body><p>1. Variable Settings:</p>
<p>The first part of every ebuild file is made up of a number of
variable settings. The variables you can set are:</p>
<table>
<tr><ti><c>P</c></ti><ti>the name name and version of the package; you should not need to set this, as it is determined from the name of the ebuild file</ti></tr>
<tr><ti><c>A</c></ti><ti>the name (without the path) of the main archive file for your package</ti></tr>
<tr><ti><c>S</c></ti><ti>the source directory for your package; normally ${WORKDIR}/${P}</ti></tr>
<tr><ti><c>DESCRIPTION</c></ti><ti>a short, one line description of your package</ti></tr>
<tr><ti><c>SRC_URI</c></ti><ti>the URIs for every source file in your package, separated by whitespace; normally the first one is something like "ftp://ftp.company.com/pub/somepackage/${A}"</ti></tr>
<tr><ti><c>HOMEPAGE</c></ti><ti>your package's homepage</ti></tr>
<tr><ti><c>DEPEND</c></ti><ti>build dependencies; see the section <uri link="#dependencies">Package Dependencies</uri></ti></tr>
<tr><ti><c>RDEPEND</c></ti><ti>runtime dependencies; see the section <uri link="#dependencies">Package Dependencies</uri></ti></tr>
</table>
<p>2. ebuild Functions</p>
<p>There are a number of different functions that you can define in ebuild files that control the building and installation process of your package.</p>
<table>
<tr><ti><c>src_unpack</c></ti><ti>Use this function to unpack your sources and apply patches, and run autoconf/automake/etc. if necessary. By default, unpacks the packages in <c>${A}</c> and applies <c>${PF}-gentoo.diff</c>. The default starting directory is <c>${WORKDIR}</c>.</ti></tr>
<tr><ti><c>src_compile</c></ti><ti>Use this function to configure and build the package. Default starting directory is <c>${S}</c>.</ti></tr>
<tr><ti><c>src_install</c></ti><ti>Use this function install the package to an image in <c>${D}</c>. If your package uses automake, you can do this simply with <c>make DESTDIR=${D} install</c>. <emph>Make sure your package installs all its files using <c>${D}</c> as the root!</emph></ti></tr>
<tr><ti><c>pkg_preinst</c></ti><ti>The commands in this function are run just prior to merging a package image into the filesystem.</ti></tr>
<tr><ti><c>pkg_postinst</c></ti><ti>The commands in this function are run just following merging a package image into the filesystem.</ti></tr>
<tr><ti><c>pkg_prerm</c></ti><ti>The commands in this function are run just prior to unmerging a package image from the filesystem.</ti></tr>
<tr><ti><c>pkg_postrm</c></ti><ti>The commands in this function are run just following unmerging a package image from the filesystem.</ti></tr>
</table>
</body>
</section>
<section>
<title>Rules for writing an ebuild File</title>
<body><p>Since ebuild files are really just shell scripts, you should use your editor's
shell-script mode for editing them. You should use proper indentation, using only tab characters --
no spaces. Make sure you set up your editor to put tabstops at 4 spaces. Always make sure you use braces around your environment variables; e.g. <c>${P}</c> instead of just <c>$P</c>.</p>
<p>TODO: add stuff about emacs & vi.</p></body>
</section>
<section>
<title><c>USE</c> Variables</title>
<body>
<p>The purpose of USE variables is to allow you to configure Portage to gobally
and automatically enable or disable certain <e>optional build-time</e>
features. Here's an example. Let's say you're a GNOME fan, and you'd like any
ebuild that has the option of compiling-in optional GNOME support to do
so. In this case, you'd add <c>gnome</c> to the <c>USE</c> variable in
<path>/etc/make.conf</path>, and then Portage will automatically add optional
GNOME functionality to packages if it is available. Likewise, if you don't
want optional GNOME features to be added to your ebuilds if they are available,
simply edit <path>/etc/make.conf</path> and make sure that <c>gnome</c> is
<e>not</e> set in the <c>USE</c> variable. Gentoo Linux has an almost
overwhelming number of USE options, allowing you to have your system configured
exactly the way you want it.
<note> If you unset a USE variable (for example, removing <c>gnome</c> from
<c>USE</c>), this will only instruct Portage to disable <e>optional</e>
build-time support for GNOME. However, if you <c>emerge</c> an ebuild that
<e>requires</e> GNOME, the package will obviously have GNOME support enabled, as you
would expect. This also means that
GNOME will be automatically installed (as a dependency) if it hasn't been already. That's why
it's always a good idea to do an <c>emerge --pretend</c> before doing the
"real" <c>emerge</c>; that way, you'll always know that you're going to get!
</note>
In your own ebuilds, you can check whether a USE variable is set by using the
<c>use <variable></c> command. The <c>use</c> command prints out the name
of every variable that is present in both <c>USE</c> and its command line. You
would normally use this command as follows:</p>
<p><c>if [ "`use X`" ]; then commands; fi</c></p>
<p>USE variables can also be used to set dependencies. For example, you may
only want to require a package if a certain USE variable is set. This is done
by using the syntax <c>variable? ( mycat/mypackage-1.0-r1 )</c> in the DEPEND
variable for your ebuild. In this example, <c>mycat/mypackage-1.0-r1</c> will
only be required if <c>variable</c> is present in <c>USE</c></p>
<p>Here's an important tip about how to use <c>USE</c>. Most of the time,
a package will have a <c>./configure</c> script used to perform configuration
steps. Generally, if your ebuild uses <c>./configure</c>, any optional build-time
functionality will be enabled or disabled by passing the appropriate arguments to
the <c>./configure</c> command. Here's the best way to handle this. First,
find out whether the particular <c>./configure</c> option that you want to add
<c>USE</c> support for is is <e>enabled</e> or <e>disabled</e> by default. If
it's <e>enabled</e> by default, then do things as follows:</p>
<pre>
DEPEND="gnome? ( >=gnome-base/gnome-1.4 )"
src_compile() {
local myvar
myvar=""
if [ -z "`use gnome`" ]
then
myvar="--disable-gnome"
fi
try ./configure ${myvar} --prefix=/usr --host=${CHOST}
try emake
}
</pre>
<p>
Above, we only check to see if the <c>gnome</c> USE variable is disabled (<c>-z</c>
is <c>bash</c>'s way of saying "if empty string"). There's no need to explicitly
enable GNOME, since for this package, GNOME is enabled by default. However, if a
particular feature is <e>disabled</e> by default, you can use this approach:</p>
<pre>
DEPEND="gnome? ( >=gnome-base/gnome-1.4 )"
src_compile() {
local myvar
myvar=""
if [ -n "`use gnome`" ]
then
myvar="--enable-gnome"
fi
try ./configure ${myvar} --prefix=/usr --host=${CHOST}
try emake
}
</pre>
<p>This time, we only explicitly enable GNOME if the <c>GNOME</c> USE variable is set.
Note that in bash, <c>[ -n "`use gnome`" ]</c> is equivalent to <c>[ "`use gnome`" ]</c>,
and will be true only if the <c>gnome</c> USE variable is set.</p>
<p>The following USE variables are currently used in Gentoo Linux:</p>
<table>
<tr><th>Variable</th><th>Description</th></tr>
<tr><ti>X</ti><ti>enable use of X. Often used to enable "token X app" included in a mostly console-based ebuild.</ti></tr>
<tr><ti>alsa</ti><ti>enable built-in support for the Advanced Linux Sound Architecture.</ti></tr>
<tr><ti>berkdb</ti><ti>enable built-in support for the Berkeley DB library (any version, as needed)</ti></tr>
<tr><ti>bonobo</ti><ti>enable Bonobo</ti><ti><c>gnome</c> packages and others</ti></tr>
<tr><ti>esd</ti><ti>enable ESound</ti><ti><c>gnome</c> packages and others</ti></tr>
<tr><ti>gdbm</ti><ti>use GNU dbm</ti><ti></ti></tr>
<tr><ti>glibc22</ti><ti>use GNU libc 2.2</ti><ti></ti></tr>
<tr><ti>gnome</ti><ti>use GNOME; also enables use of GNOME related packages such as gdk-pixbuf</ti><ti></ti></tr>
<tr><ti>gpm</ti><ti>use gpm</ti><ti></ti></tr>
<tr><ti>kde</ti><ti>enable features of the K Desktop Environment</ti><ti></ti></tr>
<tr><ti>ldap</ti><ti>use ldap</ti><ti></ti></tr>
<tr><ti>lm_sensors</ti><ti>enable lm_sensors</ti><ti><c>sys-kernel</c> packages</ti></tr>
<tr><ti>lvm</ti><ti>enable the Linux Volume Manager</ti><ti><c>sys-kernel</c> packages</ti></tr>
<tr><ti>motif</ti><ti>enable Motif</ti><ti></ti></tr>
<tr><ti>mysql</ti><ti>enable MySQL</ti><ti></ti></tr>
<tr><ti>odbc</ti><ti>enable odbc</ti><ti></ti></tr>
<tr><ti>ogg</ti><ti>enable the Ogg multimedia libraries</ti><ti></ti></tr>
<tr><ti>opengl</ti><ti>use OpenGL 3D graphics</ti><ti></ti></tr>
<tr><ti>pcmcia-cs</ti><ti>enable PCMCIA</ti><ti><c>sys-kernel</c> packages</ti></tr>
<tr><ti>postgres</ti><ti>use PostgreSQL</ti><ti></ti></tr>
<tr><ti>qt</ti><ti>use the Qt widget set</ti><ti></ti></tr>
<tr><ti>readline</ti><ti>use readline</ti><ti></ti></tr>
<tr><ti>slang</ti><ti>use slang</ti><ti></ti></tr>
<tr><ti>ssl</ti><ti>use SSL</ti><ti></ti></tr>
<tr><ti>tcltk</ti><ti>use Tcl/TK</ti><ti></ti></tr>
<tr><ti>tcpd</ti><ti>use tcpd/tcp_wrappers</ti><ti></ti></tr>
<tr><ti>xfs</ti><ti>enable the SGI XFS journaling filesystem</ti><ti><c>sys-kernel</c> packages</ti></tr>
</table>
</body>
</section>
</chapter>
<chapter>
<title>Filesystem Locations</title>
<section>
<title>Introduction to the FHS</title>
<body>
<p>The filesystem layout standards used in Gentoo Linux closely follow the FHS,
short for <e>Filesystem Hierarchy Standard</e>. A simplified
description of the standard is given here; for a complete
specification go to <uri>http://www.pathname.com/fhs/</uri>.</p>
<note> The <path>/opt</path> hierarchy is addressed in section 3.12 of the FHS.
Section 4.4 deals with the <path>/usr/X11R6</path> directory. KDE and GNOME are
not specifically addressed, and are in fact not even mentioned in the current
version of the FHS.
</note>
</body>
</section>
<section>
<title>How to fit your packages into the filesystem</title>
<body><p>Usually, if the package uses autoconf and automake, the
default installation destinations are mostly correct, with a few exceptions:</p>
<ul>
<li>If you're installing a program into <path>/bin</path>, <path>/sbin</path>,
<path>/usr/bin</path> or <path>/usr/sbin</path>, then the program's
corresponding man page should be installed into the <path>/usr/share/man</path>
tree. This can often be accomplished by specifying a <c>./configure
--mandir=/usr/share/man</c> in the ebuild.</li>
<li>GNU info files should always be installed to <path>/usr/share/info</path>,
<e>even if the info files are about X11, GNOME or KDE-specific programs or
tools</e>. Make a note: <path>/usr/share/info</path> is the <e>only</e>
official location for GNU info files. Since most <c>./configure</c> scripts
default to installing GNU info files in <c>/usr/info</c>, it's often necessary
to call <c>./configure</c> with the <c>--infodir=/usr/share/info</c> argument.</li>
<li>Documentation files are installed in <path>/usr/share/doc</path>, into a
subdirectory reflecting the name, version and revision of the particular
program. This applies to all programs: GNOME, KDE, X11 and console alike.
However, some programs may install additional documentation and support files
into a <path>/usr/share</path> hierarchy for their own purposes.
</li>
<li>X11-specific programs and libraries should always be installed into <path>/usr</path>, not
directly into <path>/usr/X11R6</path>. We reserve the <path>/usr/X11R6</path> hierarchy for
the X Window System, Version 11 Release 6 <e>itself</e>. This is perhaps a more to-the-letter
interpretation of the FHS than some other distributions have made.</li>
<li>GNOME and KDE programs, similarly, should always be installed into
<path>/usr</path>.</li>
</ul>
<impo> Some distributions choose to install GNOME and KDE into <path>/opt</path>. There
exists no standard for these desktop environments in terms of where to actually install
their files. In the interests of simplicity and consistency, we elect to install all
KDE and GNOME packages into the <path>/usr</path> hierarchy.</impo>
<p>In general, you should have ebuilds install their files into the <path>/usr</path>
tree. <e>Some</e> programs can be compiled and linked with or without GNOME, KDE and X11 libraries,
which can cause confusion. Our solution is to install everything into <path>/usr</path>
which avoids ambiguity and needless complexity for ebuild authors. The location in which to
install a program's files should <e>not</e> depend on the presence or abscence of specific
<c>USE</c> variables. Therefore, the ebuilds in the portage tree <e>almost always</e>
install into the <path>/usr</path> hierarchy exclusively.</p>
<note>The <path>/opt</path> directory is reserved in Gentoo Linux for binary-only packages.
Examples include mozilla-bin, acroread, netscape and realplayer. Packages that get
installed here will usually require a <path>/etc/env.d/foo</path> stub file. This is
so that paths and additional variables can be included into the environment.</note>
</body>
</section>
</chapter>
<chapter>
<title>The Portage scripts and utilities</title>
<section>
<title>Public scripts</title>
<body><p>These are scripts used by the system-administrator to install and remove packages, and maintain the package database.</p>
<p><c>ebuild</c></p>
<p><c>ebuild</c> is the main engine of the Portage system; it performs all major tasks such as unpacking, compiling, installing, merging, and unmerging packages. It is called using the command: <c>ebuild path/to/package.ebuild command</c>. The commands available are:</p>
<table>
<tr><th>Command</th><th>Description</th><th>Related <c>ebuild</c> Function</th></tr>
<tr><ti><c>depend</c></ti><ti>displays the dependencies required to build the package</ti><ti>n/a</ti></tr>
<tr><ti><c>check</c></ti><ti>checks that the package dependencies are fulfilled</ti><ti>n/a</ti></tr>
<tr><ti><c>rcheck</c></ti><ti>checks that the package runtime dependencies are fulfilled</ti><ti>n/a</ti></tr>
<tr><ti><c>merge</c></ti><ti>unpacks, compiles, installs, and merges the package into your filesystem</ti><ti>n/a</ti></tr>
<tr><ti>*<c>qmerge</c></ti><ti>merges the package into your filesystem, assuming that the the unpack, compile, and install stages have already been executed</ti><ti>n/a</ti></tr>
<tr><ti>*<c>unpack</c></ti><ti>unpacks the source tarballs into the work directory</ti><ti><c>src_unpack</c></ti></tr>
<tr><ti>*<c>compile</c></ti><ti>compiles the package</ti><ti><c>src_compile</c></ti></tr>
<tr><ti><c>rpm</c></ti><ti>creates an RPM from the package</ti><ti>n/a</ti></tr>
<tr><ti><c>package</c></ti><ti>creates a Gentoo <c>tbz2</c> package</ti><ti>n/a</ti></tr>
<tr><ti>*<c>prerm</c></ti><ti>executes the pre-removal stage of the package</ti><ti><c>pkg_prerm</c></ti></tr>
<tr><ti>*<c>postrm</c></ti><ti>executes the post-removal stage of the package</ti><ti><c>pkg_postrm</c></ti></tr>
<tr><ti>*<c>preinst</c></ti><ti>executes the pre-installation stage of the package</ti><ti><c>pkg_preinst</c></ti></tr>
<tr><ti>*<c>postinst</c></ti><ti>executes the post-installation stage of the package</ti><ti><c>pkg_postinst</c></ti></tr>
<tr><ti><c>config</c></ti><ti>sets up a default configuration once the package is merged</ti><ti><c>src_config</c></ti></tr>
<tr><ti>*<c>touch</c></ti><ti>updates the mtimes for each source archive in the package</ti><ti>n/a</ti></tr>
<tr><ti>*<c>clean</c></ti><ti>cleans the work directory for the package</ti><ti>n/a</ti></tr>
<tr><ti>*<c>fetch</c></ti><ti>fetches the package source tarballs</ti><ti>n/a</ti></tr>
<tr><ti>*<c>digest</c></ti><ti>creates a digest file for the package</ti><ti>n/a</ti></tr>
<tr><ti>*<c>install</c></ti><ti>installs the package into the image directory</ti><ti><c>src_install</c></ti></tr>
<tr><ti><c>unmerge</c></ti><ti>unmerges the package from your filesystem</ti><ti>n/a</ti></tr>
</table>
<p>Note: commands with an asterisk (*) are normally only used by the developer.</p>
<p><c>emerge</c></p>
<p><c>emerge</c> recursively merges a package and all of its dependencies into your filesystem.</p>
<p><c>pkgmerge</c></p>
<p><c>pkgmerge</c> merges a Gentoo <c>tbz2</c> package.</p>
<p><c>env-update</c></p>
<p><c>env-update</c> updates the configuration files (including, but not limited to <path>/etc/ld.so.conf</path> and <path>/etc/profile.env</path>) to include changes made by installed packages.</p>
</body>
</section>
<section>
<title>Private Scripts and Commands</title>
<body><p>These are scripts you can use in your ebuild files to perform common tasks.</p>
<table>
<tr><ti>dobin</ti><ti>installs the specified binaries into <path>DESTTREE/bin</path></ti></tr>
<tr><ti>into</ti><ti>sets the target prefix (<path>DESTTREE</path>) for <c>dobin</c>, <c>dolib</c>, <c>doman</c>, etc.</ti></tr>
<tr><ti>dodoc</ti><ti>installs the specified files into the packages documentation directory (<path>/usr/share/doc/${PF}</path>)</ti></tr>
<tr><ti>doexe</ti><ti></ti></tr>
<tr><ti>dohard</ti><ti></ti></tr>
<tr><ti>doinfo</ti><ti></ti></tr>
<tr><ti>doins</ti><ti></ti></tr>
<tr><ti>dolib</ti><ti></ti></tr>
<tr><ti>dolib.a</ti><ti></ti></tr>
<tr><ti>dolib.so</ti><ti></ti></tr>
<tr><ti>doman</ti><ti></ti></tr>
<tr><ti>domo</ti><ti></ti></tr>
<tr><ti>donewins</ti><ti></ti></tr>
<tr><ti>dopython</ti><ti></ti></tr>
<tr><ti>dosbin</ti><ti></ti></tr>
<tr><ti>dosed</ti><ti></ti></tr>
<tr><ti>dosym</ti><ti></ti></tr>
<tr><ti>find-packages</ti><ti></ti></tr>
<tr><ti>find-requires</ti><ti></ti></tr>
<tr><ti>fowners</ti><ti></ti></tr>
<tr><ti>fperms</ti><ti></ti></tr>
<tr><ti>import-configsettings</ti><ti></ti></tr>
<tr><ti>import-settings</ti><ti></ti></tr>
<tr><ti>megadigest</ti><ti></ti></tr>
<tr><ti>megadownload</ti><ti></ti></tr>
<tr><ti>megatouch</ti><ti></ti></tr>
<tr><ti>newbin</ti><ti></ti></tr>
<tr><ti>newdoc</ti><ti></ti></tr>
<tr><ti>newexe</ti><ti></ti></tr>
<tr><ti>newins</ti><ti></ti></tr>
<tr><ti>newlib.a</ti><ti></ti></tr>
<tr><ti>newlib.so</ti><ti></ti></tr>
<tr><ti>newman</ti><ti></ti></tr>
<tr><ti>newsbin</ti><ti></ti></tr>
<tr><ti>pkgmerge</ti><ti></ti></tr>
<tr><ti>pkgname</ti><ti></ti></tr>
<tr><ti>pmake</ti><ti></ti></tr>
<tr><ti>prepall</ti><ti></ti></tr>
<tr><ti>prepalldocs</ti><ti></ti></tr>
<tr><ti>prepallinfo</ti><ti></ti></tr>
<tr><ti>prepallman</ti><ti></ti></tr>
<tr><ti>try</ti><ti></ti></tr>
</table>
</body>
</section>
</chapter>
<chapter>
<title>Package Dependencies</title>
<section>
<title>Why dependencies are important</title>
<body><p>(TODO)<!-- todo -->
</p></body>
</section>
<section>
<title>How to Specify Dependencies in Your ebuild Files</title>
<body><p>(TODO)<!-- todo -->
</p></body>
</section>
</chapter>
</guide>
|
GitWeb