/[gentoo]/xml/htdocs/doc/en/handbook/hb-working-portage.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-working-portage.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.61 - (show annotations) (download) (as text)
Sun Nov 12 21:28:30 2006 UTC (7 years, 11 months ago) by nightmorph
Branch: MAIN
Changes since 1.60: +7 -5 lines
File MIME type: application/xml
reworded hb-working-portage's --update/--deep paragraph to be even more clear than crystal clear, bug 154899. thanks to jkt for discussing on irc

1 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6
7 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.60 2006/10/28 09:17:55 neysx Exp $ -->
8
9 <sections>
10
11 <abstract>
12 This chapter explains the "simple" steps a user definitely needs to know to
13 maintain the software on his system.
14 </abstract>
15
16 <version>1.55</version>
17 <date>2006-11-12</date>
18
19 <section>
20 <title>Welcome to Portage</title>
21 <body>
22
23 <p>
24 Portage is probably Gentoo's most notable innovation in software management.
25 With its high flexibility and enormous amount of features it is frequently seen
26 as the best software management tool available for Linux.
27 </p>
28
29 <p>
30 Portage is completely written in <uri link="http://www.python.org">Python</uri>
31 and <uri link="http://www.gnu.org/software/bash">Bash</uri> and therefore fully
32 visible to the users as both are scripting languages.
33 </p>
34
35 <p>
36 Most users will work with Portage through the <c>emerge</c> tool. This chapter
37 is not meant to duplicate the information available from the emerge man page.
38 For a complete rundown of emerge's options, please consult the man page:
39 </p>
40
41 <pre caption="Reading the emerge man page">
42 $ <i>man emerge</i>
43 </pre>
44
45 </body>
46 </section>
47 <section>
48 <title>The Portage Tree</title>
49 <subsection>
50 <title>Ebuilds</title>
51 <body>
52
53 <p>
54 When we talk about packages, we often mean software titles that are available to
55 the Gentoo users through the Portage tree. The Portage tree is a collection of
56 <e>ebuilds</e>, files that contain all information Portage needs to maintain
57 software (install, search, query, ...). These ebuilds reside in
58 <path>/usr/portage</path> by default.
59 </p>
60
61 <p>
62 Whenever you ask Portage to perform some action regarding software titles, it
63 will use the ebuilds on your system as a base. It is therefore important that
64 you regularly update the ebuilds on your system so Portage knows about new
65 software, security updates, etc.
66 </p>
67
68 </body>
69 </subsection>
70 <subsection>
71 <title>Updating the Portage Tree</title>
72 <body>
73
74 <p>
75 The Portage tree is usually updated with <uri
76 link="http://rsync.samba.org/">rsync</uri>, a fast incremental file transfer
77 utility. Updating is fairly simple as the <c>emerge</c> command provides a
78 front-end for rsync:
79 </p>
80
81 <pre caption="Updating the Portage tree">
82 # <i>emerge --sync</i>
83 </pre>
84
85 <p>
86 If you are unable to rsync due to firewall restrictions you can still update
87 your Portage tree by using our daily generated Portage tree snapshots. The
88 <c>emerge-webrsync</c> tool automatically fetches and installs the latest
89 snapshot on your system:
90 </p>
91
92 <pre caption="Running emerge-webrsync">
93 # <i>emerge-webrsync</i>
94 </pre>
95
96 </body>
97 </subsection>
98 </section>
99 <section>
100 <title>Maintaining Software</title>
101 <subsection>
102 <title>Searching for Software</title>
103 <body>
104
105 <p>
106 To search through the Portage tree after software titles, you can use
107 <c>emerge</c> built-in search capabilities. By default, <c>emerge --search</c>
108 returns the names of packages whose title matches (either fully or partially)
109 the given search term.
110 </p>
111
112 <p>
113 For instance, to search for all packages who have "pdf" in their name:
114 </p>
115
116 <pre caption="Searching for pdf-named packages">
117 $ <i>emerge --search pdf</i>
118 </pre>
119
120 <p>
121 If you want to search through the descriptions as well you can use the
122 <c>--searchdesc</c> (or <c>-S</c>) switch:
123 </p>
124
125 <pre caption="Searching for pdf-related packages">
126 $ <i>emerge --searchdesc pdf</i>
127 </pre>
128
129 <p>
130 When you take a look at the output, you'll notice that it gives you a lot of
131 information. The fields are clearly labelled so we won't go further into their
132 meanings:
133 </p>
134
135 <pre caption="Example 'emerge --search' output">
136 * net-print/cups-pdf
137 Latest version available: 1.5.2
138 Latest version installed: [ Not Installed ]
139 Size of downloaded files: 15 kB
140 Homepage: http://cip.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/
141 Description: Provides a virtual printer for CUPS to produce PDF files.
142 License: GPL-2
143 </pre>
144
145 </body>
146 </subsection>
147 <subsection>
148 <title>Installing Software</title>
149 <body>
150
151 <p>
152 Once you've found a software title to your liking, you can easily install it
153 with <c>emerge</c>: just add the package name. For instance, to install
154 <c>gnumeric</c>:
155 </p>
156
157 <pre caption="Installing gnumeric">
158 # <i>emerge gnumeric</i>
159 </pre>
160
161 <p>
162 Since many applications depend on each other, any attempt to install a certain
163 software package might result in the installation of several dependencies as
164 well. Don't worry, Portage handles dependencies well. If you want to find out
165 what Portage <e>would</e> install when you ask it to install a certain package,
166 add the <c>--pretend</c> switch. For instance:
167 </p>
168
169 <pre caption="Pretend to install gnumeric">
170 # <i>emerge --pretend gnumeric</i>
171 </pre>
172
173 <p>
174 When you ask Portage to install a package, it will download the necessary source
175 code from the internet (if necessary) and store it by default in
176 <path>/usr/portage/distfiles</path>. After this it will unpack, compile and
177 install the package. If you want Portage to only download the sources without
178 installing them, add the <c>--fetchonly</c> option to the <c>emerge</c> command:
179 </p>
180
181 <pre caption="Download the sourcecode for gnumeric">
182 # <i>emerge --fetchonly gnumeric</i>
183 </pre>
184
185 </body>
186 </subsection>
187 <subsection>
188 <title>Finding Installed Package Documentation</title>
189 <body>
190
191 <p>
192 Many packages come with their own documentation. Sometimes, the <c>doc</c> USE
193 flag determines whether the package documentation should be installed or not.
194 You can check the existence of a <c>doc</c> USE flag with the <c>emerge -vp
195 &lt;package name&gt;</c> command.
196 </p>
197
198 <pre caption="Checking the existence of a doc USE flag">
199 <comment>(alsa-lib is just an example, of course.)</comment>
200 # <i>emerge -vp alsa-lib</i>
201 [ebuild N ] media-libs/alsa-lib-1.0.9_rc3 +doc -jack 674 kB
202 </pre>
203
204 <p>
205 You can enable or disable the <c>doc</c> USE flag either globally in the
206 <path>/etc/make.conf</path> file or per package in the
207 <path>/etc/portage/package.use</path> file. You can also create a directory
208 called <path>/etc/portage/package.use</path> and list it in a file inside this
209 directory. The <uri
210 link="?part=2&amp;chap=2">USE Flags</uri> chapter covers this aspect in detail.
211 </p>
212
213 <p>
214 Once the package installed, its documentation is generally found in a
215 subdirectory named after the package under the <path>/usr/share/doc</path>
216 directory. You can also list all installed files with the <c>equery</c> tool
217 which is part of the <c>app-portage/gentoolkit</c> <uri
218 link="/doc/en/gentoolkit.xml">package</uri>.
219 </p>
220
221 <pre caption="Locating package documentation">
222 # <i>ls -l /usr/share/doc/alsa-lib-1.0.9_rc3</i>
223 total 28
224 -rw-r--r-- 1 root root 669 May 17 21:54 ChangeLog.gz
225 -rw-r--r-- 1 root root 9373 May 17 21:54 COPYING.gz
226 drwxr-xr-x 2 root root 8560 May 17 21:54 html
227 -rw-r--r-- 1 root root 196 May 17 21:54 TODO.gz
228
229 <comment>(Alternatively, use equery to locate interesting files:)</comment>
230 # <i>equery files alsa-lib | less</i>
231 media-libs/alsa-lib-1.0.9_rc3
232 * Contents of media-libs/alsa-lib-1.0.9_rc3:
233 /usr
234 /usr/bin
235 /usr/bin/alsalisp
236 <comment>(Output truncated)</comment>
237 </pre>
238
239 </body>
240 </subsection>
241 <subsection>
242 <title>Removing Software</title>
243 <body>
244
245 <p>
246 When you want to remove a software package from your system, use <c>emerge
247 --unmerge</c>. This will tell Portage to remove all files installed by that
248 package from your system <e>except</e> the configuration files of that
249 application if you have altered those after the installation. Leaving the
250 configuration files allows you to continue working with the package if you ever
251 decide to install it again.
252 </p>
253
254 <p>
255 However, a <brite>big warning</brite> applies: Portage will <e>not</e> check if
256 the package you want to remove is required by another package. It will however
257 warn you when you want to remove an important package that breaks your system
258 if you unmerge it.
259 </p>
260
261 <pre caption="Removing gnumeric from the system">
262 # <i>emerge --unmerge gnumeric</i>
263 </pre>
264
265 <p>
266 When you remove a package from your system, the dependencies of that package
267 that were installed automatically when you installed the software are left. To
268 have Portage locate all dependencies that can now be removed, use
269 <c>emerge</c>'s <c>--depclean</c> functionality. We will talk about this later
270 on.
271 </p>
272
273 </body>
274 </subsection>
275 <subsection>
276 <title>Updating your System</title>
277 <body>
278
279 <p>
280 To keep your system in perfect shape (and not to mention install the latest
281 security updates) you need to update your system regularly. Since Portage only
282 checks the ebuilds in your Portage tree you first have to update your Portage
283 tree. When your Portage tree is updated, you can update your system with
284 <c>emerge --update world</c>. In the next example, we'll also use the
285 <c>--ask</c> switch which will tell Portage to display the list of packages it
286 wants to upgrade and ask you if you want to continue:
287 </p>
288
289 <pre caption="Updating your system">
290 # <i>emerge --update --ask world</i>
291 </pre>
292
293 <p>
294 Portage will then search for newer version of the applications you have
295 installed. However, it will only verify the versions for the applications you
296 have <e>explicitly</e> installed (the applications listed in
297 <path>/var/lib/portage/world</path>) - it does not thoroughly check their
298 dependencies. If you want to update <e>every single package</e> on your system,
299 add the <c>--deep</c> argument:
300 </p>
301
302 <pre caption="Updating your entire system">
303 # <i>emerge --update --deep world</i>
304 </pre>
305
306 <p>
307 Since security updates also happen in packages you have not explicitly installed
308 on your system (but that are pulled in as dependencies of other programs), it
309 is recommended to run this command once in a while.
310 </p>
311
312 <p>
313 If you have altered any of your <uri link="?part=2&amp;chap=2">USE flags</uri>
314 lately you might want to add <c>--newuse</c> as well. Portage will then verify
315 if the change requires the installation of new packages or recompilation of
316 existing ones:
317 </p>
318
319 <pre caption="Performing a full update">
320 # <i>emerge --update --deep --newuse world</i>
321 </pre>
322
323 </body>
324 </subsection>
325 <subsection>
326 <title>Metapackages</title>
327 <body>
328
329 <p>
330 Some packages in the Portage tree don't have any real content but are used to
331 install a collection of packages. For instance, the <c>kde</c> package will
332 install a complete KDE environment on your system by pulling in various
333 KDE-related packages as dependencies.
334 </p>
335
336 <p>
337 If you ever want to remove such a package from your system, running <c>emerge
338 --unmerge</c> on the package won't have much effect as the dependencies remain
339 on the system.
340 </p>
341
342 <p>
343 Portage has the functionality to remove orphaned dependencies as well, but since
344 the availability of software is dynamically dependent you first need to update
345 your entire system fully, including the new changes you applied when changing
346 USE flags. After this you can run <c>emerge --depclean</c> to remove the
347 orphaned dependencies. When this is done, you need to rebuild the applications
348 that were dynamically linked to the now-removed software titles but don't
349 require them anymore.
350 </p>
351
352 <p>
353 All this is handled with the following three commands:
354 </p>
355
356 <pre caption="Removing orphaned dependencies">
357 # <i>emerge --update --deep --newuse world</i>
358 # <i>emerge --depclean</i>
359 # <i>revdep-rebuild</i>
360 </pre>
361
362 <p>
363 <c>revdep-rebuild</c> is provided by the <c>gentoolkit</c> package; don't forget
364 to emerge it first:
365 </p>
366
367 <pre caption="Installing the gentoolkit package">
368 # <i>emerge gentoolkit</i>
369 </pre>
370
371 </body>
372 </subsection>
373 </section>
374 <section>
375 <title>When Portage is Complaining...</title>
376 <subsection>
377 <title>About SLOTs, Virtuals, Branches, Architectures and Profiles</title>
378 <body>
379
380 <p>
381 As we stated before, Portage is extremely powerful and supports many features
382 that other software management tools lack. To understand this, we explain a few
383 aspects of Portage without going into too much detail.
384 </p>
385
386 <p>
387 With Portage different versions of a single package can coexist on a system.
388 While other distributions tend to name their package to those versions (like
389 <c>freetype</c> and <c>freetype2</c>) Portage uses a technology called
390 <e>SLOT</e>s. An ebuild declares a certain SLOT for its version. Ebuilds with
391 different SLOTs can coexist on the same system. For instance, the
392 <c>freetype</c> package has ebuilds with <c>SLOT="1"</c> and <c>SLOT="2"</c>.
393 </p>
394
395 <p>
396 There are also packages that provide the same functionality but are implemented
397 differently. For instance, <c>metalogd</c>, <c>sysklogd</c> and <c>syslog-ng</c>
398 are all system loggers. Applications that rely on the availability of "a system
399 logger" cannot depend on, for instance, <c>metalogd</c>, as the other system
400 loggers are as good a choice as any. Portage allows for <e>virtuals</e>: each
401 system logger provides <c>virtual/syslog</c> so that applications can depend on
402 <c>virtual/syslog</c>.
403 </p>
404
405 <p>
406 Software in the Portage tree can reside in different branches. By default your
407 system only accepts packages that Gentoo deems stable. Most new software titles,
408 when committed, are added to the testing branch, meaning more testing needs to
409 be done before it is marked as stable. Although you will see the ebuilds for
410 those software in the Portage tree, Portage will not update them before they are
411 placed in the stable branch.
412 </p>
413
414 <p>
415 Some software is only available for a few architectures. Or the software doesn't
416 work on the other architectures, or it needs more testing, or the developer that
417 committed the software to the Portage tree is unable to verify if the package
418 works on different architectures.
419 </p>
420
421 <p>
422 Each Gentoo installation adheres to a certain <c>profile</c> which contains,
423 amongst other information, the list of packages that are required for a system
424 to function normally.
425 </p>
426
427 </body>
428 </subsection>
429 <subsection id="blocked">
430 <title>Blocked Packages</title>
431 <body>
432
433 <pre caption="Portage warning about blocked packages (with --pretend)">
434 [blocks B ] mail-mta/ssmtp (is blocking mail-mta/postfix-2.2.2-r1)
435 </pre>
436
437 <pre caption="Portage warning about blocked packages (without --pretend)">
438 !!! Error: the mail-mta/postfix package conflicts with another package.
439 !!! both can't be installed on the same system together.
440 !!! Please use 'emerge --pretend' to determine blockers.
441 </pre>
442
443 <p>
444 Ebuilds contain specific fields that inform Portage about its dependencies.
445 There are two possible dependencies: build dependencies, declared in
446 <c>DEPEND</c> and run-time dependencies, declared in <c>RDEPEND</c>. When one of
447 these dependencies explicitly marks a package or virtual as being <e>not</e>
448 compatible, it triggers a blockage.
449 </p>
450
451 <p>
452 To fix a blockage, you can choose to not install the package or unmerge the
453 conflicting package first. In the given example, you can opt not to install
454 <c>postfix</c> or to remove <c>ssmtp</c> first.
455 </p>
456
457 <p>
458 It is also possible that two packages that are yet to be installed are blocking
459 each other. In this rare case, you should find out why you need to install both.
460 In most cases you can do with one of the packages alone. If not, please file a
461 bug on <uri link="http://bugs.gentoo.org">Gentoo's bugtracking system</uri>.
462 </p>
463
464 </body>
465 </subsection>
466 <subsection id="masked">
467 <title>Masked Packages</title>
468 <body>
469
470 <pre caption="Portage warning about masked packages">
471 !!! all ebuilds that could satisfy "bootsplash" have been masked.
472 </pre>
473
474 <pre caption="Portage warning about masked packages - reason">
475 !!! possible candidates are:
476
477 - gnome-base/gnome-2.8.0_pre1 (masked by: <i>~x86 keyword</i>)
478 - lm-sensors/lm-sensors-2.8.7 (masked by: <i>-sparc keyword</i>)
479 - sys-libs/glibc-2.3.4.20040808 (masked by: <i>-* keyword</i>)
480 - dev-util/cvsd-1.0.2 (masked by: <i>missing keyword</i>)
481 - media-video/ati-gatos-4.3.0 (masked by: <i>package.mask</i>)
482 - sys-libs/glibc-2.3.2-r11 (masked by: <i>profile</i>)
483 </pre>
484
485 <p>
486 When you want to install a package that isn't available for your system, you
487 will receive this masking error. You should try installing a different
488 application that is available for your system or wait until the package is put
489 available. There is always a reason why a package is masked:
490 </p>
491
492 <ul>
493 <li>
494 <b>~arch keyword</b> means that the application is not tested sufficiently
495 to be put in the stable branch. Wait a few days or weeks and try again.
496 </li>
497 <li>
498 <b>-arch keyword</b> or <b>-* keyword</b> means that the application does
499 not work on your architecture. If you believe the package does work file
500 a bug at our <uri link="http://bugs.gentoo.org">bugzilla</uri> website.
501 </li>
502 <li>
503 <b>missing keyword</b> means that the application has not been tested on
504 your architecture yet. Ask the architecture porting team to test the package
505 or test it for them and report your findings on our <uri
506 link="http://bugs.gentoo.org">bugzilla</uri> website.
507 </li>
508 <li>
509 <b>package.mask</b> means that the package has been found corrupt, unstable
510 or worse and has been deliberately marked as do-not-use.
511 </li>
512 <li>
513 <b>profile</b> means that the package has been found not suitable for your
514 profile. The application might break your system if you installed it or is
515 just not compatible with the profile you use.
516 </li>
517 </ul>
518
519 </body>
520 </subsection>
521 <subsection id="missingdependencies">
522 <title>Missing Dependencies</title>
523 <body>
524
525 <pre caption="Portage warning about missing dependency">
526 emerge: there are no ebuilds to satisfy "&gt;=sys-devel/gcc-3.4.2-r4".
527
528 !!! Problem with ebuild sys-devel/gcc-3.4.2-r2
529 !!! Possibly a DEPEND/*DEPEND problem.
530 </pre>
531
532 <p>
533 The application you are trying to install depends on another package that is not
534 available for your system. Please check <uri
535 link="http://bugs.gentoo.org">bugzilla</uri> if the issue is known and if not,
536 please report it. Unless you are mixing branches this should not occur and is
537 therefore a bug.
538 </p>
539
540 </body>
541 </subsection>
542 <subsection id="ambiguousebuild">
543 <title>Ambiguous Ebuild Name</title>
544 <body>
545
546 <pre caption="Portage warning about ambiguous ebuild names">
547 !!! The short ebuild name "aterm" is ambiguous. Please specify
548 !!! one of the following fully-qualified ebuild names instead:
549
550 dev-libs/aterm
551 x11-terms/aterm
552 </pre>
553
554 <p>
555 The application you want to install has a name that corresponds with more than
556 one package. You need to supply the category name as well. Portage will inform
557 you of possible matches to choose from.
558 </p>
559
560 </body>
561 </subsection>
562 <subsection id="circulardependencies">
563 <title>Circular Dependencies</title>
564 <body>
565
566 <pre caption="Portage warning about circular dependencies">
567 !!! Error: circular dependencies:
568
569 ebuild / net-print/cups-1.1.15-r2 depends on ebuild / app-text/ghostscript-7.05.3-r1
570 ebuild / app-text/ghostscript-7.05.3-r1 depends on ebuild / net-print/cups-1.1.15-r2
571 </pre>
572
573 <p>
574 Two (or more) packages you want to install depend on each other and can
575 therefore not be installed. This is most likely a bug in the Portage tree.
576 Please resync after a while and try again. You can also check <uri
577 link="http://bugs.gentoo.org">bugzilla</uri> if the issue is known and if not,
578 report it.
579 </p>
580
581 </body>
582 </subsection>
583 <subsection id="fetchfailed">
584 <title>Fetch failed</title>
585 <body>
586
587 <pre caption="Portage warning about fetch failed">
588 !!! Fetch failed for sys-libs/ncurses-5.4-r5, continuing...
589 <comment>(...)</comment>
590 !!! Some fetch errors were encountered. Please see above for details.
591 </pre>
592
593 <p>
594 Portage was unable to download the sources for the given application and will
595 try to continue installing the other applications (if applicable). This failure
596 can be due to a mirror that has not synchronised correctly or because the ebuild
597 points to an incorrect location. The server where the sources reside can also be
598 down for some reason.
599 </p>
600
601 <p>
602 Retry after one hour to see if the issue still persists.
603 </p>
604
605 </body>
606 </subsection>
607 <subsection id="profileprotect">
608 <title>System Profile Protection</title>
609 <body>
610
611 <pre caption="Portage warning about profile-protected package">
612 !!! Trying to unmerge package(s) in system profile. 'sys-apps/portage'
613 !!! This could be damaging to your system.
614 </pre>
615
616 <p>
617 You have asked to remove a package that is part of your system's core packages.
618 It is listed in your profile as required and should therefore not be removed
619 from the system.
620 </p>
621
622 </body>
623 </subsection>
624 <subsection id="digesterror">
625 <title>Digest Verification Failures</title>
626 <body>
627
628 <p>
629 Sometimes, when you attempt to emerge a package, it will fail with the message:
630 </p>
631
632 <pre caption="Digest verification failure">
633 &gt;&gt;&gt; checking ebuild checksums
634 !!! Digest verification failed:
635 </pre>
636
637 <p>
638 This is a sign that something is wrong with the Portage tree -- often, it is
639 because a developer may have made a mistake when committing a package to the
640 tree.
641 </p>
642
643 <p>
644 When the digest verification fails, do <e>not</e> try to re-digest the package
645 yourself. Running <c>ebuild foo digest</c> will not fix the problem; it will
646 almost certainly make it worse!
647 </p>
648
649 <p>
650 Instead, wait an hour or two for the tree to settle down. It's likely that the
651 error was noticed right away, but it can take a little time for the fix to
652 trickle down the Portage tree. While you're waiting, check <uri
653 link="http://bugs.gentoo.org">Bugzilla</uri> and see if anyone has reported
654 the problem yet. If not, go ahead and file a bug for the broken package.
655 </p>
656
657 <p>
658 Once you see that the bug has been fixed, you may want to re-sync to pick up
659 the fixed digest.
660 </p>
661
662 <impo>
663 This does <e>not</e> mean that you can re-sync your tree multiple times! As
664 stated in the rsync policy (when you run <c>emerge --sync</c>), users who sync
665 too often will be banned! In fact, it's better to just wait until your next
666 scheduled sync, so that you don't overload the rsync servers.
667 </impo>
668
669 </body>
670 </subsection>
671 </section>
672 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20