/[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.35 - (show annotations) (download) (as text)
Sun Aug 29 10:56:31 2004 UTC (10 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.34: +141 -13 lines
File MIME type: application/xml
#60806 - Add information on the various reasons why a package can be masked

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/1.0 -->
6
7 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.34 2004/08/28 11:30:43 swift Exp $ -->
8
9 <sections>
10 <section>
11 <title>Obtaining Package Information</title>
12 <subsection>
13 <title>The Lord of All Tools: emerge</title>
14 <body>
15
16 <p>
17 The main Portage tool that most users will use is <c>emerge</c>. We have already
18 used it during the Gentoo installation and in the previous chapter, but we just
19 briefly explained how to use it. This chapter will elaborate on <c>emerge</c>
20 and teach you how to use <c>emerge</c> to fix all your software-related needs.
21 </p>
22
23 <p>
24 <c>emerge</c> is the command used to install, remove, query and maintain
25 software packages. It is a front-end for <c>ebuild</c>; people interested in
26 becoming Gentoo professionals will learn how to use <c>ebuild</c> later on. For
27 now, we will focus on <c>emerge</c> as it has functionality that <c>ebuild</c>
28 lacks (such as resolving dependencies, searching the Portage tree, etc.).
29 </p>
30
31 <p>
32 Since <c>emerge</c> is the most important tool for Gentoo users, it has an
33 extensive manpage you can read by issuing <c>man emerge</c>. You can also view
34 the in-command help by running <c>emerge --help</c>.
35 </p>
36
37 <pre caption="Retrieving help for emerge">
38 # <i>man emerge</i>
39 # <i>emerge --help</i>
40 </pre>
41
42 </body>
43 </subsection>
44 <subsection>
45 <title>The Portage Tree</title>
46 <body>
47
48 <p>
49 Before we continue describing <c>emerge</c>, let us first take a look at the
50 Portage Tree. Go to <path>/usr/portage</path> and do a listing of the available
51 directories. We use <c>ls --classify</c> to list the contents of a
52 directory as it will show directories with a trailing "/".
53 </p>
54
55 <pre caption="Viewing the Portage Tree">
56 # <i>cd /usr/portage; ls --classify</i>
57 app-admin/ dev-ml/ gnome-libs/ net-print/
58 app-arch/ dev-perl/ gnome-office/ net-wireless/
59 app-benchmarks/ dev-php/ header.txt net-www/
60 app-cdr/ dev-python/ incoming/ net-zope/
61 app-crypt/ dev-ruby/ jython/ packages/
62 app-dicts/ dev-tcltk/ kde-apps/ profiles/
63 app-doc/ dev-tex/ kde-base/ releases/
64 app-editors/ dev-util/ kde-i18n/ scripts/
65 app-emacs/ distfiles/ kde-libs/ sec-policy/
66 app-emulation/ eclass/ licenses/ skel.ChangeLog
67 app-games/ experimental/ media-fonts/ skel.ebuild
68 app-gnustep/ files/ media-gfx/ skel.metadata.xml
69 app-i18n/ fresco-base/ media-libs/ snapshots/
70 app-misc/ games-action/ media-plugins/ sys-apps/
71 app-office/ games-arcade/ media-radio/ sys-build/
72 app-pda/ games-board/ media-sound/ sys-cluster/
73 app-portage/ games-emulation/ media-tv/ sys-devel/
74 app-sci/ games-engines/ media-video/ sys-fs/
75 app-shells/ games-fps/ metadata/ sys-kernel/
76 app-text/ games-kids/ net-analyzer/ sys-kmods/
77 app-vim/ games-misc/ net-apache/ sys-libs/
78 app-xemacs/ games-mud/ net-dialup/ unix2tcp/
79 berlin-base/ games-puzzle/ net-dns/ x11-base/
80 dev-ada/ games-roguelike/ net-firewall/ x11-libs/
81 dev-cpp/ games-rpg/ net-fs/ x11-misc/
82 dev-db/ games-server/ net-ftp/ x11-plugins/
83 dev-dotnet/ games-simulation/ net-im/ x11-terms/
84 dev-embedded/ games-sports/ net-irc/ x11-themes/
85 dev-games/ games-strategy/ net-libs/ x11-wm/
86 dev-haskell/ games-util/ net-mail/ xfce-base/
87 dev-java/ glep/ net-misc/ xfce-extra/
88 dev-lang/ gnome-apps/ net-nds/
89 dev-libs/ gnome-base/ net-news/
90 dev-lisp/ gnome-extra/ net-p2p/
91 </pre>
92
93 <p>
94 As you can see, the Portage tree has several subdirectories. Most of them are
95 the <e>categories</e> in which the Gentoo packages reside. Take a look at, for
96 instance, <path>app-office</path>:
97 </p>
98
99 <pre caption="Viewing a category">
100 # <i>cd app-office; ls --classify</i>
101 abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x
102 dia/ gnucash/ koffice/ oooqs/ qhacc/
103 dia2code/ gnumeric/ lxbank/ openoffice/ sc/
104 facturalux/ ical/ lyx/ openoffice-bin/ scribus/
105 gaby/ kbudget/ mdbtools/ openoffice-ximian/ siag/
106 gnofin/ khacc/ mrproject/ phprojekt/ texmacs/
107 </pre>
108
109 <p>
110 Inside a category you will find the packages belonging to that category, with a
111 separate directory for each package. Let us take a look at the <c>openoffice</c>
112 package:
113 </p>
114
115 <pre caption="Viewing a package">
116 # <i>cd openoffice; ls --classify</i>
117 ChangeLog files/ openoffice-1.0.3-r1.ebuild openoffice-1.1.0-r2.ebuild
118 Manifest metadata.xml openoffice-1.1.0-r1.ebuild openoffice-1.1.0.ebuild
119 </pre>
120
121 <p>
122 In the example directory, four ebuilds are stored. An <e>ebuild</e> is a script
123 which contains all the necessary information about a specific version of a
124 package. The naming for the ebuilds is almost identical; they only differ in
125 the version name.
126 You are free to view the contents of such an ebuild: they are plain scripts. We
127 will not discuss it right now as it isn't important to know if you plan on just
128 using Gentoo.
129 </p>
130
131 <p>
132 The other files are the <path>ChangeLog</path> (which contains a listing of all
133 the changes done to the ebuilds), <path>Manifest</path> (which contains the
134 checksums and filesizes of all the files in the directory) and
135 <path>metadata.xml</path> (which contains more information about the package,
136 such as the responsible development group -- called <e>herd</e> -- and a more
137 extensive description).
138 </p>
139
140 <p>
141 Inside the <path>files</path> directory, you will find extra files, needed by
142 Portage: digests (names, sizes and checksums of the files needed by a single
143 version of the package), patches, example configuration files, etc.
144 </p>
145
146 <pre caption="Viewing the extra files">
147 # <i>cd files; ls --classify</i>
148 1.0.3/ digest-openoffice-1.0.3-r1 digest-openoffice-1.1.0-r1
149 1.1.0/ digest-openoffice-1.1.0 digest-openoffice-1.1.0-r2
150 # <i>cd 1.1.0; ls --classify</i>
151 fixed-gcc.patch ooffice-wrapper-1.3
152 newstlportfix.patch openoffice-1.1.0-linux-2.6-fix.patch
153 no-mozab.patch openoffice-1.1.0-sparc64-fix.patch
154 nptl.patch
155 </pre>
156
157 <p>
158 If you go back to the root of the Portage tree (<path>/usr/portage</path>) you
159 will notice that there are other, non-category directories, too. We will discuss
160 those later in this chapter.
161 </p>
162
163 </body>
164 </subsection>
165 <subsection>
166 <title>Search for a Package</title>
167 <body>
168
169 <p>
170 If you are new to Linux or Gentoo, you might not know what tool you need for
171 what job. To facilitate searching, <c>emerge</c> provides you with a way to
172 search through the available packages on your system. There are two ways you can
173 search through packages: by <e>name</e>, or by <e>name</e> and
174 <e>description</e>.
175 </p>
176
177 <p>
178 To search through the Portage tree by name, use <c>emerge search</c>. For
179 instance, to find out more about <c>mozilla</c>:
180 </p>
181
182 <pre caption="Showing information about mozilla">
183 # <i>emerge search mozilla</i>
184 Searching...
185 [ Results for search key : mozilla ]
186 [ Applications found : 5 ]
187 <comment>(Some output removed to improve readability)</comment>
188 * net-www/mozilla
189 Latest version available: 1.5-r1
190 Latest version installed: 1.4-r3
191 Size of downloaded files: 29,153 kB
192 Homepage: http://www.mozilla.org
193 Description: The Mozilla Web Browser
194
195 * net-www/mozilla-firebird
196 Latest version available: 0.7
197 Latest version installed: [ Not Installed ]
198 Size of downloaded files: 37,850 kB
199 Homepage: http://www.mozilla.org/projects/firebird/
200 Description: The Mozilla Firebird Web Browser
201 <comment>(...)</comment>
202 </pre>
203
204 <p>
205 If you want to include a search through the descriptions too, use the
206 <c>--searchdesc</c> argument:
207 </p>
208
209 <pre caption="Search through the descriptions too">
210 # <i>emerge --searchdesc mozilla</i>
211 Searching...
212 [ Results for search key : mozilla ]
213 [ Applications found : 10 ]
214 <comment>(Some output removed to improve readability)</comment>
215 * dev-libs/nss-3.8
216 Latest version available: 3.8
217 Latest version installed: 3.8
218 Size of downloaded files: 2,782 kB
219 Homepage: http://www.mozilla.org/projects/security/pki/nss/
220 Description: Mozilla's Netscape Security Services Library that implements PKI support
221 </pre>
222
223 <p>
224 As you can see, the output of <c>emerge</c> informs you about the category and
225 name of the package, the available version, the currently installed version,
226 the size of the downloaded files, the homepage and the small description.
227 </p>
228
229 <p>
230 You see something new? Yes, <e>downloaded files</e>. When you tell Portage to
231 install a package, it of course needs to have the necessary sources (or
232 precompiled packages) available. It therefore checks the contents of
233 <path>/usr/portage/distfiles</path> to see if the necessary files are already
234 available. If not, it downloads the necessary files and places them in that
235 directory.
236 </p>
237
238 </body>
239 </subsection>
240 <subsection>
241 <title>Viewing the ChangeLog</title>
242 <body>
243
244 <p>
245 While browsing through the Portage Tree, you saw that there was a ChangeLog for
246 each package. You can view the ChangeLog entries between the available version
247 and the installed version with <c>emerge</c> too. Use the
248 <c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we
249 will view the ChangeLog entries for <c>gnumeric</c>:
250 </p>
251
252 <pre caption="Viewing the ChangeLog entries for gnumeric">
253 # <i>emerge --pretend --changelog gnumeric</i>
254 <comment>(Some output removed to improve readability)</comment>
255 *gnumeric-1.2.2
256
257 27 Nov 2003; foser &lt;foser@gentoo.org&gt; gnumeric-1.2.2.ebuild :
258 New release, requested in #34492
259 updated deps
260
261 12 Nov 2003; Jason Wever &lt;weeve@gentoo.org&gt; gnumeric-1.2.0.ebuild:
262 Marked stable on sparc, fixes bug #32405.
263
264 14 Oct 2003; Jason Wever &lt;weeve@gentoo.org&gt; gnumeric-1.0.8.ebuild:
265 Added ~sparc keyword. Fixes bug #31150.
266 </pre>
267
268 </body>
269 </subsection>
270 </section>
271 <section>
272 <title>Updating Portage</title>
273 <subsection>
274 <title>Introduction</title>
275 <body>
276
277 <p>
278 Searching through Portage is nice, but if you don't update your Portage Tree
279 regularly, you will be stuck with the packages and versions available on your
280 system. This means that your system will get outdated pretty soon and that
281 you will be missing bugfixes and remedies for possible security problems.
282 </p>
283
284 <p>
285 There are several ways to update your Portage Tree. The most popular method is
286 by using one of our <uri link="/main/en/mirrors.xml">rsync mirrors</uri>.
287 Another one is by using a Portage snapshot (in case a firewall or unavailability
288 of a network prohibits the use of the rsync server).
289 </p>
290
291 </body>
292 </subsection>
293 <subsection>
294 <title>Selecting a Mirror for rsync</title>
295 <body>
296
297 <p>
298 It is adviseable to first select a fast <uri
299 link="/main/en/mirrors.xml">mirror</uri> close to you. You can do this manually
300 (by setting the <c>SYNC</c> variable in <path>/etc/make.conf</path>) or use
301 <c>mirrorselect</c> to do this for you automatically. As the <c>SYNC</c>
302 variable will be discussed later on, we will focus on using <c>mirrorselect</c>.
303 First install <c>mirrorselect</c> by emerging it:
304 </p>
305
306 <pre caption="Installing mirrorselect">
307 # <i>emerge --usepkg mirrorselect</i>
308 </pre>
309
310 <p>
311 Now run <c>mirrorselect</c> to automatically select mirrors for you (it will
312 also setup Portage to use a mirror for the source code):
313 </p>
314
315 <pre caption="Running mirrorselect">
316 # <i>mirrorselect -a -s3</i>
317 </pre>
318
319 </body>
320 </subsection>
321 <subsection>
322 <title>Updating Portage</title>
323 <body>
324
325 <p>
326 To update Portage using rsync, simply run <c>emerge sync</c>:
327 </p>
328
329 <pre caption="Updating Portage using emerge sync">
330 # <i>emerge sync</i>
331 </pre>
332
333 <p>
334 If this fails (due to network problems, or a firewall), you can try using
335 <c>emerge-webrsync</c> which will download a Portage Tree snapshot using
336 <c>wget</c>. This also means that you can use proxies if you want. We discussed
337 how to setup your system to use proxies during the Gentoo installation.
338 </p>
339
340 <pre caption="Updating Portage using emerge-webrsync">
341 # <i>emerge-webrsync</i>
342 </pre>
343
344 </body>
345 </subsection>
346 </section>
347 <section>
348 <title>Maintaining Software</title>
349 <subsection>
350 <title>Building or Prebuilt?</title>
351 <body>
352
353 <p>
354 Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to
355 install such an ebuild, you can choose between <e>building</e> the package and
356 using a <e>prebuilt</e> package. But what are the advantages/disadvantages of
357 both approaches, and can they be used next to each other?
358 </p>
359
360 <p>
361 As you probably have guessed, building packages takes a lot of time (especially
362 if you have little resources or want to build big packages, such as <uri
363 link="http://www.kde.org">KDE</uri>, <uri
364 link="http://www.openoffice.org">OpenOffice.org</uri>, etc.). By building the
365 package, you can use the <c>USE</c> setting to tweak the package to your system.
366 Of course, you can also define high optimization options (in the <c>CFLAGS</c>
367 and <c>CXXFLAGS</c> variables) to compile the package with.
368 </p>
369
370 <p>
371 Using prebuilt packages improves the installation time (as no more compilation
372 is needed), but you will lose the advantages of the <c>USE</c> setting and the
373 <c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables.
374 </p>
375
376 <p>
377 As previously stated, prebuilt packages are stored in the
378 <path>/usr/portage/packages/All</path> directory, while the source code of the
379 packages is placed in <path>/usr/portage/distfiles</path>. If you have finished
380 installing a package you can remove the package or source code from the
381 respective directory. However, you might want to keep the package/source code of
382 the latest version, just in case you want to reinstall the package (so you don't
383 have to redownload it).
384 </p>
385
386 </body>
387 </subsection>
388 <subsection>
389 <title>Installing Software from Sources</title>
390 <body>
391
392 <p>
393 Okay, enough talking, let's cut to the chase. To install a package, you will use
394 the <c>emerge</c> command. If you don't want to use any prebuilt packages, you
395 can just use <c>emerge &lt;package-name&gt;</c> or <c>emerge
396 &lt;category&gt;/&lt;package-name&gt;</c>. As an example we'll install
397 <c>gnumeric</c>:
398 </p>
399
400 <pre caption="Building gnumeric">
401 # <i>emerge gnumeric</i>
402 </pre>
403
404 <p>
405 This will download the source code for you and unpacks, compiles and installs
406 the package on your system. It will also do the same for all the dependencies.
407 If you want to see what dependencies will be installed with it, use the
408 <c>--pretend</c> option (<c>-p</c> in short):
409 </p>
410
411 <pre caption="Pretending to build gnumeric">
412 # <i>emerge --pretend gnumeric</i>
413 </pre>
414
415 <p>
416 If you want to download the source code of the package and its dependencies,
417 but don't want to build the package, use the <c>--fetchonly</c> option
418 (<c>-f</c> in short):
419 </p>
420
421 <pre caption="Fetching sources for gnumeric">
422 # <i>emerge --fetchonly gnumeric</i>
423 </pre>
424
425 <p>
426 If you want to see where <c>emerge</c> downloads the sources from, combine the
427 <c>--fetchonly</c> and <c>--pretend</c> options:
428 </p>
429
430 <pre caption="Showing URLs of the sources for gnumeric">
431 # <i>emerge --fetchonly --pretend gnumeric</i>
432 </pre>
433
434 <p>
435 You can also opt to install a specific version of a package.
436 For instance, if you want to install a gnumeric version older than 1.2 -- for
437 any reason whatsoever :) you would type:
438 </p>
439
440 <pre caption="Installing a specific gnumeric version">
441 # <i>emerge "&lt;gnumeric-1.2"</i>
442 </pre>
443
444 <p>
445 Other possibilities are of course "&gt;" (later version) and "=" (the exact
446 version).
447 </p>
448
449 </body>
450 </subsection>
451 <subsection>
452 <title>Installing Prebuilt Packages</title>
453 <body>
454
455 <p>
456 When you want to install a prebuilt package, you should use the <c>--usepkg</c>
457 option (<c>-k</c> in short). This will use the binary package available in
458 <path>/usr/portage/packages/All</path> <e>if</e> the package and the version of
459 the application you want to install match.
460 </p>
461
462 <pre caption="Installing a prebuilt package for gnumeric">
463 # <i>emerge --usepkg gnumeric</i>
464 </pre>
465
466 <p>
467 If you want to use the binary package, even if the versions don't match, use
468 <c>--usepkgonly</c> (<c>-K</c> in short).
469 </p>
470
471 <pre caption="Installing the prebuilt package for gnumeric">
472 # <i>emerge --usepkgonly gnumeric</i>
473 </pre>
474
475 <p>
476 If you don't have the prebuilt package on your system yet, you can have
477 <c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c>
478 variable declared in <path>/etc/make.conf</path>.
479 </p>
480
481 <note>
482 Gentoo does not have any server or mirror containing such prebuilt packages.
483 Portage has been extended with this feature to fullfil the community request.
484 </note>
485
486 <p>
487 To download the binary package in case this package doesn't exist on
488 your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
489 </p>
490
491 <pre caption="Downloading and installing a prebuilt package for gnumeric">
492 # <i>emerge --getbinpkg gnumeric</i>
493 </pre>
494
495 <p>
496 This will download the package and the package-related information for you and
497 install it on your system, together with the dependencies. If you want to see
498 what dependencies will be installed with it, use the <c>--pretend</c> option
499 (<c>-p</c> in short):
500 </p>
501
502 <pre caption="Pretending to download the prebuilt packages for gnumeric">
503 # <i>emerge --getbinpkg --pretend gnumeric</i>
504 </pre>
505
506 <p>
507 You can also opt to download the prebuilt package (and the package-related
508 information) <e>without</e> checking the information on your local system and
509 <e>without</e> using the prebuilt package already on your system (if
510 applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short):
511 </p>
512
513 <pre caption="Installing a prebuilt package without using local information">
514 # <i>emerge --getbinpkgonly gnumeric</i>
515 </pre>
516
517 <p>
518 You can also opt to install a specific version of a package.
519 For instance, if you want to install a gnumeric version older than 1.2 -- for
520 any reason whatsoever :) you would type:
521 </p>
522
523 <pre caption="Installing a specific gnumeric version">
524 # <i>emerge --usepkg "&lt;gnumeric-1.2"</i>
525 </pre>
526
527 <p>
528 Other possibilities are of course "&gt;" (later version) and "=" (the exact
529 version).
530 </p>
531
532
533 </body>
534 </subsection>
535 <subsection>
536 <title>Working with Dependencies</title>
537 <body>
538
539 <p>
540 Portage has an extensive support for dependency handling. Although you usually
541 don't need to even think about this (as dependencies are automatically handled
542 by Portage) some users might want to know how you can work with <c>emerge</c>
543 and dependencies.
544 </p>
545
546 <p>
547 For instance, if you want Portage to pretend that none of the dependencies of a
548 package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This
549 is useful with <c>--pretend</c> to display a complete tree of dependencies for
550 any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile
551 all listed packages.
552 </p>
553
554 <pre caption="Show all dependencies of gnumeric">
555 # <i>emerge --emptytree --pretend gnumeric</i>
556 </pre>
557
558 <p>
559 Another argument is <c>--nodeps</c>, which will ask Portage to try install the
560 given package without taking care of the dependencies. It is trivial that this
561 can lead to failures.
562 </p>
563
564 <pre caption="Installing gnumeric without taking care of the dependencies">
565 # <i>emerge --nodeps gnumeric</i>
566 </pre>
567
568 <p>
569 The opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage
570 install all dependencies of a given package, but not the package itself:
571 </p>
572
573 <pre caption="Installing the dependencies of gnumeric">
574 # <i>emerge --onlydeps gnumeric</i>
575 </pre>
576
577 <p>
578 When you uninstall software Portage will not automatically unmerge the
579 dependencies that aren't needed anymore. If you want to "clean" your system from
580 those orphaned dependencies, you can use <c>emerge depclean</c>. This will
581 search for all installed software that you haven't installed explicitly and that
582 isn't a dependency of software that you have installed explicitly.
583 </p>
584
585 <warn>
586 Using depclean can seriously impair your system. Use with caution and
587 double-check the list of dependencies that Portage wants to remove before you go
588 ahead!
589 </warn>
590
591 <pre caption="Listing and removing the orphaned dependencies">
592 # <i>emerge -p depclean</i>
593 <comment>(After seriously verifying the list, remove the orphaned dependencies)</comment>
594 # <i>emerge depclean</i>
595 </pre>
596
597 </body>
598 </subsection>
599 <subsection>
600 <title>Updating your System</title>
601 <body>
602
603 <p>
604 Portage knows two special tags to denote a set of software packages:
605 <e>system</e> and <e>world</e>. You have already seen the former while
606 installing Gentoo if you didn't use a <e>stage3</e> installation. To refresh
607 things: <e>system</e> is the collection of <e>core</e> packages, necessary to
608 have a working Gentoo system.
609 </p>
610
611 <p>
612 The <e>world</e> tag consists of all software you have installed yourself on
613 your system plus the <e>system</e> information. In other words, every time you
614 emerge a package using <c>emerge &lt;package-name&gt;</c>, the
615 <c>&lt;package-name&gt;</c> is registered in the <e>world</e> file
616 (<path>/var/cache/edb/world</path>). Dependencies are <e>not</e> part of the
617 <e>world</e> file, but we will get to that later.
618 </p>
619
620 <p>
621 If you want to update the system packages, use the <c>--update</c> option
622 (<c>-u</c> in short):
623 </p>
624
625 <pre caption="Updating the system packages">
626 # <i>emerge --update system</i>
627 </pre>
628
629 <p>
630 An identical approach can be used for the world packages:
631 </p>
632
633 <pre caption="Updating your entire system">
634 # <i>emerge --update world</i>
635 </pre>
636
637 <p>
638 Again, if you want to see what <c>emerge</c> wants to update, use the
639 <c>--pretend</c> option together with the <c>--update</c> option:
640 </p>
641
642 <pre caption="Pretending to update your entire system">
643 # <i>emerge --pretend --update world</i>
644 <comment>(Some output removed to improve readability)</comment>
645 [ebuild U ] net-misc/wget-1.9-r1 [1.9]
646 [ebuild UD] media-video/dvdauthor-0.5.0 [0.5.3]
647 [ebuild U ] net-analyzer/ethereal-0.9.16 [0.9.14]
648 </pre>
649
650 <p>
651 Right next to the word "ebuild" you will notice a letter (or combination of
652 letters) which gives you more information about the package:
653 </p>
654
655 <ul>
656 <li>
657 <e>B</e> (blocks) The package listed to the left is blocking the emerge of
658 the package listed to the right
659 </li>
660 <li>
661 <e>N</e> (new) The package is new to your system and will be emerged for the
662 first time
663 </li>
664 <li>
665 <e>R</e> (replace) The package isn't new, but will be reemerged
666 </li>
667 <li>
668 <e>F</e> (fetch) The package requires that you download the source code
669 manually (for instance due to licencing issues)
670 </li>
671 <li>
672 <e>U</e> (update) The package already exists on your system but will be
673 upgraded
674 </li>
675 <li>
676 <e>UD</e> (downgrade) The package already exists on your system but will be
677 downgraded
678 </li>
679 </ul>
680
681 <p>
682 We have mentioned that the <e>world</e> file doesn't contain dependencies. When
683 you run <c>emerge --update world</c> only the packages mentioned in the
684 <e>world</e> file and it's immediate dependencies are checked and, if necessary,
685 upgraded. If you want <c>emerge</c> to check <e>all</e> the dependencies
686 (including the dependencies of the dependencies), add the <c>--deep</c> flag:
687 </p>
688
689 <pre caption="Upgrading your entire system, including all dependencies">
690 # <i>emerge --update --deep world</i>
691 </pre>
692
693 <p>
694 Of course, we are talking here about <e>system</e> and <e>world</e>, but you can
695 perform the same actions for individual software packages.
696 </p>
697
698 </body>
699 </subsection>
700 <subsection>
701 <title>Removing Software</title>
702 <body>
703
704 <p>
705 If you want to remove software from your system, you can use the <c>unmerge</c>
706 option (<c>-C</c> - capital C - in short):
707 </p>
708
709 <pre caption="Uninstalling software">
710 # <i>emerge unmerge gnumeric</i>
711 </pre>
712
713 <p>
714 If you want to test a removal (but not perform it), you can use <c>--pretend</c>
715 again:
716 </p>
717
718 <pre caption="Pretending to uninstall software">
719 # <i>emerge --pretend unmerge gnumeric</i>
720 </pre>
721
722 <warn>
723 Portage doesn't verify if a package is a dependency for another
724 installed package. It also doesn't warn you if the package is part of
725 <e>system</e>, i.e. a core application necessary for the correct functioning of
726 your system!
727 </warn>
728
729 <p>
730 Once the unmerge begins you will see a long list of filenames belonging to the
731 package. Some of these filenames will have a flag displayed to the
732 left of the filename. The flags <c>!mtime</c>, <c>!empty</c>, and <c>cfgpro</c>
733 specify reasons why certain files are not being removed while the package is.
734 Files listed without any of these three flags are removed from the
735 filesystem successfully. The three flags specify the following reasons:
736 </p>
737
738 <ul>
739 <li>
740 <c>!mtime</c> : The listed file has been changed since it was installed,
741 probably by you or some tool
742 </li>
743 <li>
744 <c>!empty</c> : The listed directory is not empty
745 </li>
746 <li>
747 <c>cfgpro</c> : This file is located inside a protected directory and will
748 not be touched for safety
749 </li>
750 </ul>
751
752 </body>
753 </subsection>
754 </section>
755 <section>
756 <title>Working with Masked Packages</title>
757 <subsection>
758 <title>ARCH or not?</title>
759 <body>
760
761 <p>
762 When a Gentoo developer puts an ebuild online it informs Portage how to treat
763 the package depending on the architecture and stability of the software title.
764 He does so by defining a variable called <c>KEYWORDS</c> inside the ebuild.
765 This variable contains one or more architectures and marks them with a special
766 flag. An explanation of the available flags is given in the next table.
767 </p>
768
769 <table>
770 <tr>
771 <th>Flag</th>
772 <th>Description</th>
773 </tr>
774 <tr>
775 <ti>ARCH</ti>
776 <ti>Known to work well on the given architecture</ti>
777 </tr>
778 <tr>
779 <ti>~ARCH</ti>
780 <ti>
781 Probably works well but needs some further testing on the given
782 architecture
783 </ti>
784 </tr>
785 <tr>
786 <ti>-ARCH</ti>
787 <ti>Known not to work on the given architecture</ti>
788 </tr>
789 <tr>
790 <ti>-*</ti>
791 <ti>Known not to work or being extremely dangerous on any architecture</ti>
792 </tr>
793 </table>
794
795 <p>
796 Let's take a look at an example:
797 </p>
798
799 <pre caption="Example KEYWORDS setting">
800 KEYWORDS="x86 -sparc ~alpha ~ppc"
801 </pre>
802
803 <p>
804 This example can be read as follows:
805 </p>
806
807 <ul>
808 <li>
809 The ebuild works well on the x86 architecture
810 </li>
811 <li>
812 The ebuild doesn't work on the sparc architecture
813 </li>
814 <li>
815 The ebuild probably works on the alpha architecture but needs more testing
816 </li>
817 <li>
818 The ebuild probably works on the ppc architecture but needs more testing
819 </li>
820 <li>
821 The ebuild might work on the other architectures but hasn't been tried yet
822 </li>
823 </ul>
824
825 <p>
826 Your system will use <e>ARCH</e> packages per default. If you want to live on
827 the edge, don't mind having a broken package once in a while, know how to deal
828 with a broken system and you like submitting bugreports to <uri
829 link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use
830 <e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system,
831 edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that
832 it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).
833 </p>
834
835 <p>
836 Note though that it is far from trivial (if even impossible) to go back to
837 <e>ARCH</e> from <e>~ARCH</e>.
838 </p>
839
840 <p>
841 If you want to update your system now, you will notice that <e>a lot</e> of
842 packages will be updated!
843 </p>
844
845 </body>
846 </subsection>
847 <subsection>
848 <title>Masked Packages</title>
849 <body>
850
851 <p>
852 When you want to install a package, you might come across the following message:
853 </p>
854
855 <pre caption="Message about masked packages">
856 Calculating dependencies
857 !!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment>
858 </pre>
859
860 <p>
861 A package can be masked due to several reasons:
862 </p>
863
864 <ol>
865 <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li>
866 <li>The package is hard-masked explicitly</li>
867 <li>The package isn't available for your ARCH entirely</li>
868 <li>The package is masked by your profile</li>
869 </ol>
870
871 <p>
872 Portage will inform you why a certain package cannot be installed:
873 </p>
874
875 <ul>
876 <li>
877 <b>~arch keyword</b>: the package is known to work on the given architecture
878 but requires more testing while your system requires that a package is
879 known to work well
880 </li>
881 <li>
882 <b>-arch keyword</b>: the package is known not to work on the given
883 architecture
884 </li>
885 <li>
886 <b>-* keyword</b>: the package is known not to work on any architecture
887 </li>
888 <li>
889 <b>package.mask</b>: the package is listed in the <path>package.mask</path>
890 file, meaning that it breaks something, crashes your system, has severe
891 security issues or worse
892 </li>
893 <li>
894 <b>profile</b>: the package is not available for your profile
895 </li>
896 </ul>
897
898 <p>
899 If the package is masked because of <b>~arch keyword</b>, and you <e>really</e>
900 want to install it (knowing that there <e>is</e> a reason why it isn't
901 available in <e>ARCH</e>), you can accept the <e>~ARCH</e> version of any
902 package by adding it to your <path>/etc/portage/package.keywords</path> file:
903 </p>
904
905 <pre caption="Accepting the ~ARCH version of a package">
906 <comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
907 # <i>mkdir /etc/portage</i>
908
909 # <i>echo "app-office/gnumeric ~x86" &gt;&gt; /etc/portage/package.keywords</i>
910 # <i>emerge gnumeric</i>
911 </pre>
912
913 <p>
914 Similarly, if you want to install a package marked <b>-arch keyword</b> or <b>-*
915 keyword</b> regardless of all the warnings we might put in front of you, edit
916 <path>/etc/portage/package.keywords</path> and add the package with the required
917 keyword:
918 </p>
919
920 <pre caption="Accepting the -arch or -* version of a package">
921 <comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
922 # <i>mkdir /etc/portage</i>
923
924 # <i>echo "app-office/gnumeric -x86" &gt;&gt; /etc/portage/package.keywords</i>
925 <comment>(or)</comment>
926 # <i>echo "app-office/gnumeric -*" &gt;&gt; /etc/portage/package.keywords</i>
927 # <i>emerge gnumeric</i>
928 </pre>
929
930 <p>
931 If you only want to allow the merging of such a package for a specific version
932 or version range, you can use the "&lt;, &lt;=, =, &gt;= or &gt;" operands:
933 </p>
934
935 <pre caption="Accepting a specific ~arch-marked version of a package">
936 # <i>echo "=app-office/gnumeric-2.0 ~x86" &gt;&gt; /etc/portage/package.keywords</i>
937 </pre>
938
939 <p>
940 A package is masked due to <b>package.mask</b> if it is listed in
941 <path>/usr/portage/profiles/package.mask</path>. If you read this file, you
942 will also read the reason why the package is hardmasked (it is usually added as
943 a comment). If you want to install the package nevertheless (despite all the
944 possible warnings we could ever throw at your head about "breaking your system",
945 "breaks other packages", or "badly needs testing"), create the
946 <path>/etc/portage/package.unmask</path> file and list the package in it (use
947 the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
948 </p>
949
950 <pre caption="Unmasking a hard-masked application">
951 <comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
952 # <i>mkdir /etc/portage</i>
953
954 # <i>echo "=app-office/gnumeric-1.2.12" &gt;&gt; /etc/portage/package.unmask</i>
955 </pre>
956
957 <p>
958 Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as
959 all changes are undone the next time you update your Portage tree.
960 </p>
961
962 <p>
963 Sometimes you might want to hardmask a (collection of) package(s). This is the
964 case when newer versions of an application don't support something you require
965 or when these versions break something else in your environment.
966 </p>
967
968 <p>
969 To hard-mask a package, create <path>/etc/portage/package.mask</path> and list
970 the package in it (use the same format as mentioned above).
971 </p>
972
973 <pre caption="Hard-masking a package">
974 <comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
975 # <i>mkdir /etc/portage</i>
976
977 # <i>echo "&gt;app-office/gnumeric-1.2.10" &gt;&gt; /etc/portage/package.mask</i>
978 </pre>
979
980 <p>
981 When Portage tells you that it cannot install a package due to <b>profile</b> it
982 means that you are working with a certain profile that doesn't allow the package
983 to be installed. But what is this "profile"?
984 </p>
985
986 <p>
987 A profile contains a list of package names and a set of default configuration
988 options to be used by Portage. Those files tell Portage which packages
989 and which specific versions of those packages to allow, disallow, or
990 treat as required. Users can switch profiles by changing a single symlink
991 (<path>/etc/make.profile</path>).
992 </p>
993
994 <p>
995 You cannot override a package that is blocked due to <b>profile</b>; if you
996 really want to use it, switch to the required profile.
997 </p>
998
999 <p>
1000 You will find more information in our <uri
1001 link="/proj/en/releng/docs/cascading-profiles.xml">Cascading Profiles
1002 Document</uri>.
1003 </p>
1004
1005 </body>
1006 </subsection>
1007 <subsection>
1008 <title>Blocked Packages</title>
1009 <body>
1010
1011 <p>
1012 You have a situation when you receive the following error on your screen:
1013 </p>
1014
1015 <pre caption="Blocking package">
1016 [blocks B ] gnome-base/bonobo-activation (from pkg gnome-base/libbonobo-2.4.0)
1017 </pre>
1018
1019 <p>
1020 In the above example, the package <c>bonobo-activation</c> is blocking the
1021 emerge of <c>libbonobo</c>. To resolve this issue, remove the
1022 <c>bonobo-activation</c> package and continue:
1023 </p>
1024
1025 <pre caption="Resolving a blocking situation">
1026 # <i>emerge unmerge bonobo-activation</i>
1027 </pre>
1028
1029 </body>
1030 </subsection>
1031 </section>
1032 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20