/[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.4 - (show annotations) (download) (as text)
Thu Nov 27 11:08:00 2003 UTC (10 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.3: +6 -6 lines
File MIME type: application/xml
Ofcourse -> of course, of course :)

1 <!-- The content of this document is licensed under the CC-BY-SA license -->
2 <!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3
4 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.3 2003/11/26 20:19:59 swift Exp $ -->
5
6 <sections>
7 <section>
8 <title>Obtaining Package Information</title>
9 <subsection>
10 <title>The Lord of All Tools: emerge</title>
11 <body>
12
13 <p>
14 We have briefly encountered <c>emerge</c> in the previous chapter, but not to
15 the extent that you are now able to work with it to its fullest potential. We
16 will fix that right now ;-)
17 </p>
18
19 <p>
20 <c>emerge</c> is the command used to install, remove, query and maintain
21 software packages. It is a front-end for <c>ebuild</c>; people interested in
22 becoming Gentoo professionals will learn how to use <c>ebuild</c> later on. For
23 now, we will focus on <c>emerge</c> as it has functionality that <c>ebuild</c>
24 lacks (such as resolving dependencies, searching the Portage tree, etc.).
25 </p>
26
27 <p>
28 Since <c>emerge</c> is the most important tool for Gentoo users, it has an
29 extensive manpage you can read by issuing <c>man emerge</c>. You can also view
30 the in-command help by running <c>emerge --help</c>.
31 </p>
32
33 <pre caption="Retrieving help for emerge">
34 # <i>man emerge</i>
35 # <i>emerge --help</i>
36 </pre>
37
38 </body>
39 </subsection>
40 <subsection>
41 <title>The Portage Tree</title>
42 <body>
43
44 <p>
45 Before we continue describing <c>emerge</c>, let us first take a look at the
46 Portage Tree. Go to <path>/usr/portage</path> and do a listing of the available
47 directories.
48 </p>
49
50 <pre caption="Viewing the Portage Tree">
51 # <i>cd /usr/portage; ls --classify</i>
52 <comment>(The --classify will append a special character to note the filetype)</comment>
53 app-admin/ dev-ml/ gnome-libs/ net-print/
54 app-arch/ dev-perl/ gnome-office/ net-wireless/
55 app-benchmarks/ dev-php/ header.txt net-www/
56 app-cdr/ dev-python/ incoming/ net-zope/
57 app-crypt/ dev-ruby/ jython/ packages/
58 app-dicts/ dev-tcltk/ kde-apps/ profiles/
59 app-doc/ dev-tex/ kde-base/ releases/
60 app-editors/ dev-util/ kde-i18n/ scripts/
61 app-emacs/ distfiles/ kde-libs/ sec-policy/
62 app-emulation/ eclass/ licenses/ skel.ChangeLog
63 app-games/ experimental/ media-fonts/ skel.ebuild
64 app-gnustep/ files/ media-gfx/ skel.metadata.xml
65 app-i18n/ fresco-base/ media-libs/ snapshots/
66 app-misc/ games-action/ media-plugins/ sys-apps/
67 app-office/ games-arcade/ media-radio/ sys-build/
68 app-pda/ games-board/ media-sound/ sys-cluster/
69 app-portage/ games-emulation/ media-tv/ sys-devel/
70 app-sci/ games-engines/ media-video/ sys-fs/
71 app-shells/ games-fps/ metadata/ sys-kernel/
72 app-text/ games-kids/ net-analyzer/ sys-kmods/
73 app-vim/ games-misc/ net-apache/ sys-libs/
74 app-xemacs/ games-mud/ net-dialup/ unix2tcp/
75 berlin-base/ games-puzzle/ net-dns/ x11-base/
76 dev-ada/ games-roguelike/ net-firewall/ x11-libs/
77 dev-cpp/ games-rpg/ net-fs/ x11-misc/
78 dev-db/ games-server/ net-ftp/ x11-plugins/
79 dev-dotnet/ games-simulation/ net-im/ x11-terms/
80 dev-embedded/ games-sports/ net-irc/ x11-themes/
81 dev-games/ games-strategy/ net-libs/ x11-wm/
82 dev-haskell/ games-util/ net-mail/ xfce-base/
83 dev-java/ glep/ net-misc/ xfce-extra/
84 dev-lang/ gnome-apps/ net-nds/
85 dev-libs/ gnome-base/ net-news/
86 dev-lisp/ gnome-extra/ net-p2p/
87 </pre>
88
89 <p>
90 As you can see, the Portage tree has several subdirectories. Most of them are
91 the <e>categories</e> in which the Gentoo packages, called <e>ebuilds</e>,
92 reside. Take a look at, for instance, <path>app-office</path>:
93 </p>
94
95 <pre caption="Viewing a category">
96 # <i>cd app-office; ls --classify</i>
97 abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x
98 dia/ gnucash/ koffice/ oooqs/ qhacc/
99 dia2code/ gnumeric/ lxbank/ openoffice/ sc/
100 facturalux/ ical/ lyx/ openoffice-bin/ scribus/
101 gaby/ kbudget/ mdbtools/ openoffice-ximian/ siag/
102 gnofin/ khacc/ mrproject/ phprojekt/ texmacs/
103 </pre>
104
105 <p>
106 Inside a category you will find the packages belonging to that category, with a
107 seperate directory for each package. Let us take a look at the <c>openoffice</c>
108 package:
109 </p>
110
111 <pre caption="Viewing a package">
112 # <i>cd openoffice; ls --classify</i>
113 ChangeLog files/ openoffice-1.0.3-r1.ebuild openoffice-1.1.0-r2.ebuild
114 Manifest metadata.xml openoffice-1.1.0-r1.ebuild openoffice-1.1.0.ebuild
115 </pre>
116
117 <p>
118 Remember that we told you that a Gentoo package is called an ebuild? Well, in
119 the example directory four of such ebuilds are stored. Their naming is
120 almost identical: they only differ in the version name.
121 You are free to view the contents of such a package: they are plain scripts. We
122 will not discuss it right now as it isn't important to know if you plan on just
123 using Gentoo.
124 </p>
125
126 <p>
127 The other files are the <path>ChangeLog</path> (which contains a listing of all
128 the changes done to the ebuilds), <path>Manifest</path> (which contains the
129 checksums and permissions of all the files in the directory) and
130 <path>metadata.xml</path> (which contains more information about the package,
131 such as the responsible development group -- called <e>herd</e> and a more
132 extensive description).
133 </p>
134
135 <p>
136 Inside the <path>files</path> directory you will find extra files, needed by
137 Portage: digests (checksums and permissions of the files needed by a single
138 version of the package), patches, example configuration files, etc.
139 </p>
140
141 <pre caption="Viewing the extra files">
142 # <i>cd files; ls --classify</i>
143 1.0.3/ digest-openoffice-1.0.3-r1 digest-openoffice-1.1.0-r1
144 1.1.0/ digest-openoffice-1.1.0 digest-openoffice-1.1.0-r2
145 # <i>cd 1.1.0; ls --classify</i>
146 fixed-gcc.patch ooffice-wrapper-1.3
147 newstlportfix.patch openoffice-1.1.0-linux-2.6-fix.patch
148 no-mozab.patch openoffice-1.1.0-sparc64-fix.patch
149 nptl.patch
150 </pre>
151
152 <p>
153 If you go back to the root of the Portage tree (<path>/usr/portage</path>) you
154 will notice that there are other, non-category directories too. We will discuss
155 those later in this chapter.
156 </p>
157
158 </body>
159 </subsection>
160 <subsection>
161 <title>Search for a Package</title>
162 <body>
163
164 <p>
165 If you are new to Linux or Gentoo, you might not know what tool you need for
166 what job. To facilitate searching, <c>emerge</c> provides you with a way to
167 search through the available packages on your system. There are two ways you can
168 search through packages: by <e>name</e>, or by <e>name</e> and
169 <e>description</e>.
170 </p>
171
172 <p>
173 To search through the Portage tree by name, use <c>emerge search</c>. For
174 instance, to find out more about <c>mozilla</c>:
175 </p>
176
177 <pre caption="Showing information about mozilla">
178 # <i>emerge search mozilla</i>
179 Searching...
180 [ Results for search key : mozilla ]
181 [ Applications found : 5 ]
182 <comment>(Some output removed to improve readability)</comment>
183 * net-www/mozilla
184 Latest version available: 1.5-r1
185 Latest version installed: 1.4-r3
186 Size of downloaded files: 29,153 kB
187 Homepage: http://www.mozilla.org
188 Description: The Mozilla Web Browser
189
190 * net-www/mozilla-firebird
191 Latest version available: 0.7
192 Latest version installed: [ Not Installed ]
193 Size of downloaded files: 37,850 kB
194 Homepage: http://www.mozilla.org/projects/firebird/
195 Description: The Mozilla Firebird Web Browser
196 <comment>(...)</comment>
197 </pre>
198
199 <p>
200 If you want to include a search through the descriptions too, use the
201 <c>--searchdesc</c> argument:
202 </p>
203
204 <pre caption="Search through the descriptions too">
205 # <i>emerge --searchdesc mozilla</i>
206 Searching...
207 [ Results for search key : mozilla ]
208 [ Applications found : 10 ]
209 <comment>(Some output removed to improve readability)</comment>
210 * dev-libs/nss-3.8
211 Latest version available: 3.8
212 Latest version installed: 3.8
213 Size of downloaded files: 2,782 kB
214 Homepage: http://www.mozilla.org/projects/security/pki/nss/
215 Description: Mozilla's Netscape Security Services Library that implements PKI support
216 </pre>
217
218 <p>
219 As you can see, the output of <c>emerge</c> informs you about the category and
220 name of the package, the available version, the currently installed version,
221 the size of the downloaded files, the homepage and the small description.
222 </p>
223
224 <p>
225 You see something new? Yes, <e>downloaded files</e>. When you tell Portage to
226 install a package, it of course needs to have the necessary sources (or
227 precompiled packages) available. It therefor checks the contents of
228 <path>/usr/portage/distfiles</path> (for sourcecode) or
229 <path>/usr/portage/packages/All</path> (for precompiled packages) to see if the
230 necessary files are already available. If not, it downloads the necessary files
231 and places them in those directories.
232 </p>
233
234 <note>
235 Searching the Portage Tree, especially when using <c>--searchdesc</c>, is very
236 time consuming. There are other, more performant tools available. We will
237 describe those in the chapter on <uri link="?part=2&amp;chap=7">Gentoolkit and
238 Other Tools</uri>.
239 </note>
240
241 </body>
242 </subsection>
243 <subsection>
244 <title>Viewing the ChangeLog</title>
245 <body>
246
247 <p>
248 While browsing through the Portage Tree, you saw that there was a ChangeLog for
249 each package. You can view this ChangeLog with <c>emerge</c> too. Use the
250 <c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we
251 will view the ChangeLog entries for <c>gnumeric</c>:
252 </p>
253
254 <pre caption="Viewing the ChangeLog entries for gnumeric">
255 # <i>emerge --pretend --changelog gnumeric</i>
256 </pre>
257
258 </body>
259 </subsection>
260 </section>
261 <section>
262 <title>Updating Portage</title>
263 <subsection>
264 <title>Introduction</title>
265 <body>
266
267 <p>
268 Searching through Portage is nice, but if you don't update your Portage Tree
269 regularly, you will be stuck with the packages and versions available on your
270 system. This means that your system will get outdated pretty soon, and that
271 packages with possible security problems will remain on your system.
272 </p>
273
274 <p>
275 There are several ways to update your Portage Tree. The most popular method is
276 by using one of our <uri link="/main/en/mirrors.xml">rsync mirrors</uri>.
277 Another one is by using a Portage snapshot (in case a firewall or unavailability
278 of a network prohibits the use of the rsync server).
279 </p>
280
281 </body>
282 </subsection>
283 <subsection>
284 <title>Selecting a Mirror for rsync</title>
285 <body>
286
287 <p>
288 It is adviseable to first select a fast <uri
289 link="/main/en/mirrors.xml">mirror</uri> close to you. You can do this manually
290 (by setting the <c>SYNC</c> variable in <path>/etc/make.conf</path>) or use
291 <c>mirrorselect</c> to do this for you automatically. As the <c>SYNC</c>
292 variable will be discussed later on, we will focus on using <c>mirrorselect</c>.
293 First install <c>mirrorselect</c> by emerging it:
294 </p>
295
296 <pre caption="Installing mirrorselect">
297 # <i>emerge --usepkg mirrorselect</i>
298 </pre>
299
300 <p>
301 Now run <c>mirrorselect</c> to automatically select mirrors for you (it will
302 also setup Portage to use a mirror for the sourcecode):
303 </p>
304
305 <pre caption="Running mirrorselect">
306 # <i>mirrorselect -a -s3</i>
307 </pre>
308
309 </body>
310 </subsection>
311 <subsection>
312 <title>Updating Portage</title>
313 <body>
314
315 <p>
316 To update Portage using rsync, simply run <c>emerge sync</c>:
317 </p>
318
319 <pre caption="Updating Portage using emerge sync">
320 # <i>emerge sync</i>
321 </pre>
322
323 <p>
324 If this fails (due to network problems, or a firewall), you can try using
325 <c>emerge-webrsync</c> which will download a Portage Tree snapshot using
326 <c>wget</c>. This also means that you can use proxies if you want. We discussed
327 how to setup your system to use proxies during the Gentoo installation.
328 </p>
329
330 <pre caption="Updating Portage using emerge-webrsync">
331 # <i>emerge-webrsync</i>
332 </pre>
333
334 </body>
335 </subsection>
336 </section>
337 <section>
338 <title>Maintaining Software</title>
339 <subsection>
340 <title>Building or Prebuild?</title>
341 <body>
342
343 <p>
344 Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to
345 install such an ebuild, you can choose between <e>building</e> the package, or
346 using a <e>prebuild</e> package. But what are the advantages/disadvantages of
347 both approaches, and can they be used next to each other?
348 </p>
349
350 <p>
351 As you probably have guessed, building packages takes a lot of time (especially
352 if you have little resources or want to build big packages, such as <uri
353 link="http://www.kde.org">KDE</uri>, <uri
354 link="http://www.openoffice.org">OpenOffice.org</uri>, etc.). By building the
355 package, you can use the <c>USE</c> setting to tweak the package to your system.
356 Of course, you can also define high optimization options (in the <c>CFLAGS</c>
357 and <c>CXXFLAGS</c> variables) to compile the package with.
358 </p>
359
360 <p>
361 Using prebuild packages improves the installation time (as no more compilation
362 is needed), but you will lose the advantages of the <c>USE</c> setting and the
363 <c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables.
364 </p>
365
366 <p>
367 As previously stated, prebuild packages are stored in the
368 <path>/usr/portage/packages/All</path> directory, while the sourcecode of the
369 packages are placed in <path>/usr/portage/distfiles</path>. If you have finished
370 installing a package you can remove the package or sourcecode from the
371 respective directory. However, you might want to keep the package/sourcecode of
372 the latest version, just in case you want to reinstall the package (so you don't
373 have to redownload it).
374 </p>
375
376 </body>
377 </subsection>
378 <subsection>
379 <title>Installing Software from Sources</title>
380 <body>
381
382 <p>
383 Okay, enough talking, let's cut to the chase. To install a package, you will use
384 the <c>emerge</c> command. If you don't want to use any prebuild packages, you
385 can just use <c>emerge &lt;package-name&gt;</c> or <c>emerge
386 &lt;category&gt;/&lt;package-name&gt;</c>. As an example we'll install
387 <c>gnumeric</c>:
388 </p>
389
390 <pre caption="Building gnumeric">
391 # <i>emerge gnumeric</i>
392 </pre>
393
394 <p>
395 This will download the sourcecode for you and unpacks, compiles and installs the
396 package on your system. It will also do the same for all the dependencies. If
397 you want to see what dependencies will be installed with it, use the
398 <c>--pretend</c> option (<c>-p</c> in short):
399 </p>
400
401 <pre caption="Pretending to build gnumeric">
402 # <i>emerge --pretend gnumeric</i>
403 </pre>
404
405 <p>
406 If you want to download the sourcecode of the package and its dependencies,
407 but don't want to build the package, use the <c>--fetchonly</c> option
408 (<c>-f</c> in short):
409 </p>
410
411 <pre caption="Fetching sources for gnumeric">
412 # <i>emerge --fetchonly gnumeric</i>
413 </pre>
414
415 <p>
416 If you want to see where <c>emerge</c> downloads the sources from, combine the
417 <c>--fetchonly</c> and <c>--pretend</c> options:
418 </p>
419
420 <pre caption="Showing URLs of the sources for gnumeric">
421 # <i>emerge --fetchonly --pretend gnumeric</i>
422 </pre>
423
424 <p>
425 You can also opt to install a specific version of a package.
426 For instance, if you want to install a gnumeric version older than 1.2 -- for
427 any reason whatsoever :) you would type:
428 </p>
429
430 <pre caption="Installing a specific gnumeric version">
431 # <i>emerge "&lt;gnumeric-1.2"</i>
432 </pre>
433
434 <p>
435 Other possibilities are of course "&gt;" (later version) and "=" (the exact
436 version).
437 </p>
438
439 </body>
440 </subsection>
441 <subsection>
442 <title>Installing Prebuild Packages</title>
443 <body>
444
445 <p>
446 When you want to install a prebuild package, you should use the <c>--usepkg</c>
447 option (<c>-k</c> in short). This will use the binary package available in
448 <path>/usr/portage/packages/All</path> <e>if</e> the package and the version of
449 the application you want to install match.
450 </p>
451
452 <pre caption="Installing a prebuild package for gnumeric">
453 # <i>emerge --usepkg gnumeric</i>
454 </pre>
455
456 <p>
457 If you want to use the binary package, even if the versions don't match, use
458 <c>--usepkgonly</c> (<c>-K</c> in short).
459 </p>
460
461 <pre caption="Installing the prebuild package for gnumeric">
462 # <i>emerge --usepkgonly gnumeric</i>
463 </pre>
464
465 <!-- TODO When handbook goes life, comment out this parts until the mirrors have
466 been updated with online GRP packages. -->
467 <p>
468 If you don't have the prebuild package on your system yet, you can have
469 <c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c>
470 variable declared in <path>/etc/make.conf</path>.
471 </p>
472
473 <p>
474 To download the binary package in case this package doesn't exist on
475 your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
476 </p>
477
478 <pre caption="Downloading and installing a prebuild package for gnumeric">
479 # <i>emerge --getbinpkg gnumeric</i>
480 </pre>
481
482 <p>
483 This will download the package and the package-related information for you and
484 install it on your system, together with the dependencies. If you want to see
485 what dependencies will be installed with it, use the <c>--pretend</c> option
486 (<c>-p</c> in short):
487 </p>
488
489 <pre caption="Pretending to download the prebuild packages for gnumeric">
490 # <i>emerge --ginbinpkg --pretend gnumeric</i>
491 </pre>
492
493 <p>
494 You can also opt to download the prebuild package (and the package-related
495 information) <e>without</e> checking the information on your local system and
496 <e>without</e> using the prebuild package already on your system (if
497 applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short):
498 </p>
499
500 <pre caption="Installing a prebuild package without using local information">
501 # <i>emerge --getbinpkgonly gnumeric</i>
502 </pre>
503
504 <!-- TODO Up until here -->
505
506 <p>
507 You can also opt to install a specific version of a package.
508 For instance, if you want to install a gnumeric version older than 1.2 -- for
509 any reason whatsoever :) you would type:
510 </p>
511
512 <pre caption="Installing a specific gnumeric version">
513 # <i>emerge --usepkg "&lt;gnumeric-1.2"</i>
514 </pre>
515
516 <p>
517 Other possibilities are of course "&gt;" (later version) and "=" (the exact
518 version).
519 </p>
520
521
522 </body>
523 </subsection>
524 <subsection>
525 <title>Updating your System</title>
526 <body>
527
528 <p>
529 Portage knows two special tags to denote a set of software packages:
530 <e>system</e> and <e>world</e>. You have already seen the former while
531 installing Gentoo if you didn't use a <e>stage3</e> installation. To refresh
532 things: <e>system</e> is the collection of <e>core</e> packages, necessary to
533 have a working Gentoo system.
534 </p>
535
536 <p>
537 The <e>world</e> tag consists of all software you have installed yourself on
538 your system plus the <e>system</e> information. In other words, every time you
539 emerge a package using <c>emerge &lt;package-name&gt;</c>, the
540 <c>&lt;package-name&gt;</c> is registered in the <e>world</e> file
541 (<path>/var/cache/edb/world</path>). Dependencies are <e>not</e> part of the
542 <e>world</e> file, but we will get to that later.
543 </p>
544
545 <p>
546 If you want to update the system packages, use the <c>--update</c> option
547 (<c>-u</c> in short):
548 </p>
549
550 <pre caption="Updating the system packages">
551 # <i>emerge --update system</i>
552 </pre>
553
554 <p>
555 An identical approach can be used for the world packages:
556 </p>
557
558 <pre caption="Updating your entire system">
559 # <i>emerge --update world</i>
560 </pre>
561
562 <p>
563 Again, if you want to see what <c>emerge</c> wants to update, use the
564 <c>--pretend</c> option together with the <c>--update</c> option:
565 </p>
566
567 <pre caption="Pretending to update your entire system">
568 # <i>emerge --pretend --update world</i>
569 <comment>(Some output removed to improve readability)</comment>
570 [ebuild U ] net-misc/wget-1.9-r1 [1.9]
571 [ebuild UD] media-video/dvdauthor-0.5.0 [0.5.3]
572 [ebuild U ] net-analyzer/ethereal-0.9.16 [0.9.14]
573 </pre>
574
575 <p>
576 Right next to the word "ebuild" you will notice a letter (or combination of
577 letters) which gives you more information about the package:
578 </p>
579
580 <ul>
581 <li>
582 <e>B</e> (blocks) The package listed to the left is blocking the emerge of
583 the package listed to the right
584 </li>
585 <li>
586 <e>N</e> (new) The package is new to your system and will be emerged for the
587 first time
588 </li>
589 <li>
590 <e>R</e> (reemerge) The package isn't new, but needs to be reemerged
591 </li>
592 <li>
593 <e>F</e> (fetch) The package requires that you download the sourcecode
594 manually (for instance due to licencing issues)
595 </li>
596 <li>
597 <e>U</e> (update) The package already exists on your system but will be
598 upgraded
599 </li>
600 <li>
601 <e>UD</e> (downgrade) The package already exists on your system but will be
602 downgraded
603 </li>
604 <li>
605 <e>U-</e> (slot warning) The package you have installed on your system
606 is listed as a package that can not coexist with a different version, but
607 your update does. The update will be installed and the older version will be
608 removed.
609 </li>
610 </ul>
611
612 <p>
613 In certain cases, an update may mean a downgrade (i.e. install an older version
614 instead of a newer version). If you don't want this to happen, use the
615 <c>--upgradeonly</c> option (<c>-U</c> in short):
616 </p>
617
618 <pre caption="Upgrading your entire system">
619 # <i>emerge --update --upgradeonly world</i>
620 </pre>
621
622 <p>
623 Of course, we are talking here about <e>system</e> and <e>world</e>, but you can
624 perform the same actions for individual software packages.
625 </p>
626
627 </body>
628 </subsection>
629 <subsection>
630 <title>Removing Software</title>
631 <body>
632
633 <p>
634 If you want to remove software from your system, you can use the <c>unmerge</c>
635 option (<c>-C</c> - capital C - in short):
636 </p>
637
638 <pre caption="Uninstalling software">
639 # <i>emerge unmerge gnumeric</i>
640 </pre>
641
642 <p>
643 If you want to test a removal (but not perform it), you can use <c>--pretend</c>
644 again:
645 </p>
646
647 <pre caption="Pretending to uninstall software">
648 # <i>emerge --pretend unmerge gnumeric</i>
649 </pre>
650
651 <warn>
652 Portage doesn't verify if a package is a dependency for another
653 installed package. It also doesn't warn you if the package is part of
654 <e>system</e>, i.e. a core application necessary for the correct functioning of
655 your system!
656 </warn>
657
658 </body>
659 </subsection>
660 </section>
661 <section>
662 <title>Software Availability</title>
663 <subsection>
664 <title>ARCH or not?</title>
665 <body>
666
667 <p>
668 Gentoo places its packages in two possible stadia called <e>ARCH</e> and
669 <e>~ARCH</e>. Don't take this literally: the stadia depend on the architecture
670 you are using. In other words, for x86-based systems you have <e>x86</e> and
671 <e>~x86</e>, for ppc-based systems you have <e>ppc</e> and <e>~ppc</e> etc.
672 </p>
673
674 <p>
675 The <e>~ARCH</e> stadium means that the package works for the developer in
676 charge of the package, but that the package hasn't been tested thoroughly enough
677 by the community to be placed in <e>ARCH</e>. <e>~ARCH</e> packages usually go
678 to <e>ARCH</e> after being bugfree for a sufficient amount of time.
679 </p>
680
681 <p>
682 Your system will use <e>ARCH</e> packages per default. If you want to live on
683 the edge, don't mind having a broken package once in a while, and you like
684 submitting bugreports to <uri
685 link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use
686 <e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system,
687 edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that
688 it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).
689 </p>
690
691 <p>
692 If you want to update your system now, you will notice that <e>a lot</e> of
693 packages will be updated!
694 </p>
695
696 </body>
697 </subsection>
698 <subsection>
699 <title>Masked Packages</title>
700 <body>
701
702 <p>
703 When you want to install a package, you might come across the following message:
704 </p>
705
706 <pre caption="Message about masked packages">
707 Calculating dependencies
708 !!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment>
709 </pre>
710
711 <p>
712 A package can be masked due to two reasons:
713 </p>
714
715 <ol>
716 <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li>
717 <li>The package is hard-masked explicitly</li>
718 </ol>
719
720 <p>
721 If the package is masked because of the first reason, and you <e>really</e> want
722 to install it (knowing that there <e>is</e> a reason why it isn't available in
723 <e>ARCH</e>), you can temporarily accept <e>~ARCH</e> packages:
724 </p>
725
726 <pre caption="Temporarily accepting ~ARCH packages">
727 # <i>ACCEPT_KEYWORDS="~x86" emerge gnumeric</i>
728 </pre>
729
730 <p>
731 A package is hardmasked if it is listed in
732 <path>/usr/portage/profiles/package.mask</path>. If you read this file, you
733 will also read the reason why the package is hardmasked (it is usually added as
734 a comment). If you want to install the package nevertheless (despite all the
735 possible warnings we could ever throw at your head about "breaking your system",
736 "breaks other packages", or "badly needs testing"), create the
737 <path>/etc/portage/package.unmask</path> file and list the package in it (use
738 the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
739 </p>
740
741 <p>
742 Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as
743 all changes are undone the next time you update your Portage tree.
744 </p>
745
746 <p>
747 Another trick to circumvent the "masked package" problem is to install the
748 package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c>
749 settings and the <path>package.mask</path> listing.
750 </p>
751
752 <pre caption="Installing a package without checking for stadium / masking">
753 # <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i>
754 </pre>
755
756 </body>
757 </subsection>
758 <subsection>
759 <title>Blocked Packages</title>
760 <body>
761
762 <p>
763 You have a situation when you receive the following error on your screen:
764 </p>
765
766 <pre caption="Blocking package">
767 [blocks B ] gnome-base/bonobo-activation (from pkg gnome-base/libbonobo-2.4.0)
768 </pre>
769
770 <p>
771 In the above example, the package <c>bonobo-activation</c> is blocking the
772 emerge of <c>libbonobo</c>. To resolve this issue, remove the
773 <c>bonobo-activation</c> package and continue:
774 </p>
775
776 <pre caption="Resolving a blocking situation">
777 # <i>emerge unmerge bonobo-activation</i>
778 </pre>
779
780 </body>
781 </subsection>
782 </section>
783 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20