/[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.27 - (hide annotations) (download) (as text)
Sun Jul 18 10:41:51 2004 UTC (10 years ago) by neysx
Branch: MAIN
Changes since 1.26: +8 -6 lines
File MIME type: application/xml
#57290: ACCEPT_KEYWORDS on the command line is evil. Use /etc/portage/package.keywords instead

1 swift 1.18 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3    
4 swift 1.1 <!-- 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 neysx 1.27 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.26 2004/07/16 09:37:11 neysx Exp $ -->
8 swift 1.1
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 swift 1.2 <p>
17 swift 1.5 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 swift 1.13 and teach you how to use <c>emerge</c> to fix all your software-related needs.
21 swift 1.2 </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 swift 1.6 directories. We use <c>ls --classify</c> to list the contents of a
52     directory as it will show directories with a trailing "/".
53 swift 1.2 </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, called <e>ebuilds</e>,
96     reside. Take a look at, for 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 swift 1.12 separate directory for each package. Let us take a look at the <c>openoffice</c>
112 swift 1.2 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     Remember that we told you that a Gentoo package is called an ebuild? Well, in
123     the example directory four of such ebuilds are stored. Their naming is
124     almost identical: they only differ in the version name.
125     You are free to view the contents of such a package: they are plain scripts. We
126     will not discuss it right now as it isn't important to know if you plan on just
127     using Gentoo.
128     </p>
129    
130     <p>
131     The other files are the <path>ChangeLog</path> (which contains a listing of all
132     the changes done to the ebuilds), <path>Manifest</path> (which contains the
133 swift 1.20 checksums and filesizes of all the files in the directory) and
134 swift 1.2 <path>metadata.xml</path> (which contains more information about the package,
135 swift 1.6 such as the responsible development group -- called <e>herd</e> -- and a more
136 swift 1.2 extensive description).
137     </p>
138    
139     <p>
140     Inside the <path>files</path> directory you will find extra files, needed by
141     Portage: digests (checksums and permissions of the files needed by a single
142     version of the package), patches, example configuration files, etc.
143     </p>
144    
145     <pre caption="Viewing the extra files">
146     # <i>cd files; ls --classify</i>
147     1.0.3/ digest-openoffice-1.0.3-r1 digest-openoffice-1.1.0-r1
148     1.1.0/ digest-openoffice-1.1.0 digest-openoffice-1.1.0-r2
149     # <i>cd 1.1.0; ls --classify</i>
150     fixed-gcc.patch ooffice-wrapper-1.3
151     newstlportfix.patch openoffice-1.1.0-linux-2.6-fix.patch
152     no-mozab.patch openoffice-1.1.0-sparc64-fix.patch
153     nptl.patch
154     </pre>
155    
156     <p>
157     If you go back to the root of the Portage tree (<path>/usr/portage</path>) you
158     will notice that there are other, non-category directories too. We will discuss
159     those later in this chapter.
160     </p>
161    
162 swift 1.1 </body>
163     </subsection>
164     <subsection>
165     <title>Search for a Package</title>
166     <body>
167    
168 swift 1.2 <p>
169     If you are new to Linux or Gentoo, you might not know what tool you need for
170     what job. To facilitate searching, <c>emerge</c> provides you with a way to
171     search through the available packages on your system. There are two ways you can
172     search through packages: by <e>name</e>, or by <e>name</e> and
173     <e>description</e>.
174     </p>
175    
176     <p>
177     To search through the Portage tree by name, use <c>emerge search</c>. For
178     instance, to find out more about <c>mozilla</c>:
179     </p>
180    
181     <pre caption="Showing information about mozilla">
182     # <i>emerge search mozilla</i>
183     Searching...
184     [ Results for search key : mozilla ]
185     [ Applications found : 5 ]
186     <comment>(Some output removed to improve readability)</comment>
187     * net-www/mozilla
188     Latest version available: 1.5-r1
189     Latest version installed: 1.4-r3
190     Size of downloaded files: 29,153 kB
191     Homepage: http://www.mozilla.org
192     Description: The Mozilla Web Browser
193    
194     * net-www/mozilla-firebird
195     Latest version available: 0.7
196     Latest version installed: [ Not Installed ]
197     Size of downloaded files: 37,850 kB
198     Homepage: http://www.mozilla.org/projects/firebird/
199     Description: The Mozilla Firebird Web Browser
200     <comment>(...)</comment>
201     </pre>
202    
203     <p>
204     If you want to include a search through the descriptions too, use the
205     <c>--searchdesc</c> argument:
206     </p>
207    
208     <pre caption="Search through the descriptions too">
209     # <i>emerge --searchdesc mozilla</i>
210     Searching...
211     [ Results for search key : mozilla ]
212     [ Applications found : 10 ]
213     <comment>(Some output removed to improve readability)</comment>
214     * dev-libs/nss-3.8
215     Latest version available: 3.8
216     Latest version installed: 3.8
217     Size of downloaded files: 2,782 kB
218     Homepage: http://www.mozilla.org/projects/security/pki/nss/
219     Description: Mozilla's Netscape Security Services Library that implements PKI support
220     </pre>
221    
222     <p>
223     As you can see, the output of <c>emerge</c> informs you about the category and
224     name of the package, the available version, the currently installed version,
225     the size of the downloaded files, the homepage and the small description.
226     </p>
227    
228     <p>
229     You see something new? Yes, <e>downloaded files</e>. When you tell Portage to
230 swift 1.4 install a package, it of course needs to have the necessary sources (or
231 swift 1.6 precompiled packages) available. It therefore checks the contents of
232 swift 1.15 <path>/usr/portage/distfiles</path> (for source code) or
233 swift 1.2 <path>/usr/portage/packages/All</path> (for precompiled packages) to see if the
234     necessary files are already available. If not, it downloads the necessary files
235     and places them in those directories.
236 swift 1.14 </p>
237 swift 1.2
238 swift 1.14 <!--
239 swift 1.2 <note>
240 swift 1.14 Searching the Portage Tree, especially when using <c>- -searchdesc</c>, is very
241 neysx 1.26 time consuming. There are other, best performing tools available. We will
242 swift 1.2 describe those in the chapter on <uri link="?part=2&amp;chap=7">Gentoolkit and
243     Other Tools</uri>.
244     </note>
245 swift 1.14 -->
246 swift 1.2
247 swift 1.1 </body>
248     </subsection>
249 swift 1.3 <subsection>
250     <title>Viewing the ChangeLog</title>
251     <body>
252    
253     <p>
254     While browsing through the Portage Tree, you saw that there was a ChangeLog for
255 swift 1.17 each package. You can view the ChangeLog entries between the available version
256     and the installed version with <c>emerge</c> too. Use the
257 swift 1.3 <c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we
258     will view the ChangeLog entries for <c>gnumeric</c>:
259     </p>
260    
261     <pre caption="Viewing the ChangeLog entries for gnumeric">
262     # <i>emerge --pretend --changelog gnumeric</i>
263 swift 1.17 <comment>(Some output removed to improve readability)</comment>
264     *gnumeric-1.2.2
265    
266     27 Nov 2003; foser &lt;foser@gentoo.org&gt; gnumeric-1.2.2.ebuild :
267     New release, requested in #34492
268     updated deps
269    
270     12 Nov 2003; Jason Wever &lt;weeve@gentoo.org&gt; gnumeric-1.2.0.ebuild:
271     Marked stable on sparc, fixes bug #32405.
272    
273     14 Oct 2003; Jason Wever &lt;weeve@gentoo.org&gt; gnumeric-1.0.8.ebuild:
274     Added ~sparc keyword. Fixes bug #31150.
275 swift 1.3 </pre>
276    
277     </body>
278     </subsection>
279 swift 1.1 </section>
280     <section>
281     <title>Updating Portage</title>
282     <subsection>
283 swift 1.2 <title>Introduction</title>
284     <body>
285    
286     <p>
287     Searching through Portage is nice, but if you don't update your Portage Tree
288     regularly, you will be stuck with the packages and versions available on your
289 swift 1.6 system. This means that your system will get outdated pretty soon and that
290     you will be missing bugfixes and remedies for possible security problems.
291 swift 1.2 </p>
292    
293     <p>
294     There are several ways to update your Portage Tree. The most popular method is
295     by using one of our <uri link="/main/en/mirrors.xml">rsync mirrors</uri>.
296     Another one is by using a Portage snapshot (in case a firewall or unavailability
297     of a network prohibits the use of the rsync server).
298     </p>
299    
300     </body>
301     </subsection>
302     <subsection>
303     <title>Selecting a Mirror for rsync</title>
304 swift 1.1 <body>
305    
306 swift 1.2 <p>
307     It is adviseable to first select a fast <uri
308     link="/main/en/mirrors.xml">mirror</uri> close to you. You can do this manually
309     (by setting the <c>SYNC</c> variable in <path>/etc/make.conf</path>) or use
310     <c>mirrorselect</c> to do this for you automatically. As the <c>SYNC</c>
311     variable will be discussed later on, we will focus on using <c>mirrorselect</c>.
312     First install <c>mirrorselect</c> by emerging it:
313     </p>
314    
315     <pre caption="Installing mirrorselect">
316     # <i>emerge --usepkg mirrorselect</i>
317     </pre>
318    
319     <p>
320     Now run <c>mirrorselect</c> to automatically select mirrors for you (it will
321 swift 1.15 also setup Portage to use a mirror for the source code):
322 swift 1.2 </p>
323    
324     <pre caption="Running mirrorselect">
325     # <i>mirrorselect -a -s3</i>
326     </pre>
327    
328 swift 1.1 </body>
329     </subsection>
330     <subsection>
331 swift 1.2 <title>Updating Portage</title>
332 swift 1.1 <body>
333 swift 1.2
334     <p>
335     To update Portage using rsync, simply run <c>emerge sync</c>:
336     </p>
337    
338     <pre caption="Updating Portage using emerge sync">
339     # <i>emerge sync</i>
340     </pre>
341    
342     <p>
343     If this fails (due to network problems, or a firewall), you can try using
344     <c>emerge-webrsync</c> which will download a Portage Tree snapshot using
345     <c>wget</c>. This also means that you can use proxies if you want. We discussed
346     how to setup your system to use proxies during the Gentoo installation.
347     </p>
348    
349     <pre caption="Updating Portage using emerge-webrsync">
350     # <i>emerge-webrsync</i>
351     </pre>
352 swift 1.1
353     </body>
354     </subsection>
355     </section>
356     <section>
357     <title>Maintaining Software</title>
358     <subsection>
359 swift 1.8 <title>Building or Prebuilt?</title>
360 swift 1.1 <body>
361    
362 swift 1.3 <p>
363     Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to
364 swift 1.15 install such an ebuild, you can choose between <e>building</e> the package and
365 swift 1.8 using a <e>prebuilt</e> package. But what are the advantages/disadvantages of
366 swift 1.3 both approaches, and can they be used next to each other?
367     </p>
368    
369     <p>
370     As you probably have guessed, building packages takes a lot of time (especially
371     if you have little resources or want to build big packages, such as <uri
372     link="http://www.kde.org">KDE</uri>, <uri
373     link="http://www.openoffice.org">OpenOffice.org</uri>, etc.). By building the
374     package, you can use the <c>USE</c> setting to tweak the package to your system.
375 swift 1.4 Of course, you can also define high optimization options (in the <c>CFLAGS</c>
376 swift 1.3 and <c>CXXFLAGS</c> variables) to compile the package with.
377     </p>
378    
379     <p>
380 swift 1.8 Using prebuilt packages improves the installation time (as no more compilation
381 swift 1.3 is needed), but you will lose the advantages of the <c>USE</c> setting and the
382     <c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables.
383     </p>
384    
385     <p>
386 swift 1.8 As previously stated, prebuilt packages are stored in the
387 swift 1.15 <path>/usr/portage/packages/All</path> directory, while the source code of the
388     packages is placed in <path>/usr/portage/distfiles</path>. If you have finished
389     installing a package you can remove the package or source code from the
390     respective directory. However, you might want to keep the package/source code of
391 swift 1.3 the latest version, just in case you want to reinstall the package (so you don't
392     have to redownload it).
393     </p>
394    
395     </body>
396     </subsection>
397     <subsection>
398     <title>Installing Software from Sources</title>
399     <body>
400    
401     <p>
402     Okay, enough talking, let's cut to the chase. To install a package, you will use
403 swift 1.8 the <c>emerge</c> command. If you don't want to use any prebuilt packages, you
404 swift 1.3 can just use <c>emerge &lt;package-name&gt;</c> or <c>emerge
405     &lt;category&gt;/&lt;package-name&gt;</c>. As an example we'll install
406     <c>gnumeric</c>:
407     </p>
408    
409     <pre caption="Building gnumeric">
410     # <i>emerge gnumeric</i>
411     </pre>
412    
413     <p>
414 swift 1.15 This will download the source code for you and unpacks, compiles and installs
415     the package on your system. It will also do the same for all the dependencies.
416     If you want to see what dependencies will be installed with it, use the
417 swift 1.3 <c>--pretend</c> option (<c>-p</c> in short):
418     </p>
419    
420     <pre caption="Pretending to build gnumeric">
421     # <i>emerge --pretend gnumeric</i>
422     </pre>
423    
424     <p>
425 swift 1.15 If you want to download the source code of the package and its dependencies,
426 swift 1.3 but don't want to build the package, use the <c>--fetchonly</c> option
427     (<c>-f</c> in short):
428     </p>
429    
430     <pre caption="Fetching sources for gnumeric">
431     # <i>emerge --fetchonly gnumeric</i>
432     </pre>
433    
434     <p>
435     If you want to see where <c>emerge</c> downloads the sources from, combine the
436     <c>--fetchonly</c> and <c>--pretend</c> options:
437     </p>
438    
439     <pre caption="Showing URLs of the sources for gnumeric">
440     # <i>emerge --fetchonly --pretend gnumeric</i>
441     </pre>
442    
443     <p>
444     You can also opt to install a specific version of a package.
445     For instance, if you want to install a gnumeric version older than 1.2 -- for
446     any reason whatsoever :) you would type:
447     </p>
448    
449     <pre caption="Installing a specific gnumeric version">
450     # <i>emerge "&lt;gnumeric-1.2"</i>
451     </pre>
452    
453     <p>
454 swift 1.4 Other possibilities are of course "&gt;" (later version) and "=" (the exact
455 swift 1.3 version).
456     </p>
457    
458     </body>
459     </subsection>
460     <subsection>
461 swift 1.8 <title>Installing Prebuilt Packages</title>
462 swift 1.3 <body>
463    
464     <p>
465 swift 1.8 When you want to install a prebuilt package, you should use the <c>--usepkg</c>
466 swift 1.3 option (<c>-k</c> in short). This will use the binary package available in
467     <path>/usr/portage/packages/All</path> <e>if</e> the package and the version of
468     the application you want to install match.
469     </p>
470    
471 swift 1.8 <pre caption="Installing a prebuilt package for gnumeric">
472 swift 1.3 # <i>emerge --usepkg gnumeric</i>
473     </pre>
474    
475     <p>
476     If you want to use the binary package, even if the versions don't match, use
477     <c>--usepkgonly</c> (<c>-K</c> in short).
478     </p>
479    
480 swift 1.8 <pre caption="Installing the prebuilt package for gnumeric">
481 swift 1.3 # <i>emerge --usepkgonly gnumeric</i>
482     </pre>
483    
484     <p>
485 swift 1.8 If you don't have the prebuilt package on your system yet, you can have
486 swift 1.3 <c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c>
487     variable declared in <path>/etc/make.conf</path>.
488     </p>
489    
490     <p>
491     To download the binary package in case this package doesn't exist on
492 swift 1.10 your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
493 swift 1.3 </p>
494    
495 swift 1.8 <pre caption="Downloading and installing a prebuilt package for gnumeric">
496 swift 1.10 # <i>emerge --getbinpkg gnumeric</i>
497 swift 1.3 </pre>
498    
499     <p>
500     This will download the package and the package-related information for you and
501     install it on your system, together with the dependencies. If you want to see
502 swift 1.10 what dependencies will be installed with it, use the <c>--pretend</c> option
503 swift 1.3 (<c>-p</c> in short):
504     </p>
505    
506 swift 1.8 <pre caption="Pretending to download the prebuilt packages for gnumeric">
507 swift 1.10 # <i>emerge --getbinpkg --pretend gnumeric</i>
508 swift 1.3 </pre>
509    
510     <p>
511 swift 1.8 You can also opt to download the prebuilt package (and the package-related
512 swift 1.3 information) <e>without</e> checking the information on your local system and
513 swift 1.8 <e>without</e> using the prebuilt package already on your system (if
514 swift 1.10 applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short):
515 swift 1.3 </p>
516    
517 swift 1.8 <pre caption="Installing a prebuilt package without using local information">
518 swift 1.10 # <i>emerge --getbinpkgonly gnumeric</i>
519 swift 1.3 </pre>
520    
521     <p>
522     You can also opt to install a specific version of a package.
523     For instance, if you want to install a gnumeric version older than 1.2 -- for
524     any reason whatsoever :) you would type:
525     </p>
526    
527     <pre caption="Installing a specific gnumeric version">
528     # <i>emerge --usepkg "&lt;gnumeric-1.2"</i>
529     </pre>
530    
531     <p>
532 swift 1.4 Other possibilities are of course "&gt;" (later version) and "=" (the exact
533 swift 1.3 version).
534     </p>
535    
536    
537 swift 1.1 </body>
538     </subsection>
539     <subsection>
540 swift 1.11 <title>Working with Dependencies</title>
541     <body>
542    
543     <p>
544     Portage has an extensive support for dependency handling. Although you usually
545     don't need to even think about this (as dependencies are automatically handled
546     by Portage) some users might want to know how you can work with <c>emerge</c>
547     and dependencies.
548     </p>
549    
550     <p>
551     For instance, if you want Portage to pretend that none of the dependencies of a
552     package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This
553     is useful with <c>--pretend</c> to display a complete tree of dependencies for
554     any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile
555 swift 1.24 all listed packages.
556 swift 1.11 </p>
557    
558     <pre caption="Show all dependencies of gnumeric">
559     # <i>emerge --emptytree --pretend gnumeric</i>
560     </pre>
561    
562     <p>
563     Another argument is <c>--nodeps</c>, which will ask Portage to try install the
564     given package without taking care of the dependencies. It is trivial that this
565     can lead to failures.
566     </p>
567    
568     <pre caption="Installing gnumeric without taking care of the dependencies">
569     # <i>emerge --nodeps gnumeric</i>
570     </pre>
571    
572     <p>
573 swift 1.15 The opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage
574 swift 1.11 install all dependencies of a given package, but not the package itself:
575     </p>
576    
577     <pre caption="Installing the dependencies of gnumeric">
578     # <i>emerge --onlydeps gnumeric</i>
579     </pre>
580    
581     </body>
582     </subsection>
583     <subsection>
584 swift 1.3 <title>Updating your System</title>
585 swift 1.1 <body>
586    
587 swift 1.3 <p>
588     Portage knows two special tags to denote a set of software packages:
589     <e>system</e> and <e>world</e>. You have already seen the former while
590     installing Gentoo if you didn't use a <e>stage3</e> installation. To refresh
591     things: <e>system</e> is the collection of <e>core</e> packages, necessary to
592     have a working Gentoo system.
593     </p>
594    
595     <p>
596     The <e>world</e> tag consists of all software you have installed yourself on
597     your system plus the <e>system</e> information. In other words, every time you
598     emerge a package using <c>emerge &lt;package-name&gt;</c>, the
599     <c>&lt;package-name&gt;</c> is registered in the <e>world</e> file
600     (<path>/var/cache/edb/world</path>). Dependencies are <e>not</e> part of the
601     <e>world</e> file, but we will get to that later.
602     </p>
603    
604     <p>
605     If you want to update the system packages, use the <c>--update</c> option
606     (<c>-u</c> in short):
607     </p>
608    
609     <pre caption="Updating the system packages">
610     # <i>emerge --update system</i>
611     </pre>
612    
613     <p>
614     An identical approach can be used for the world packages:
615     </p>
616    
617     <pre caption="Updating your entire system">
618     # <i>emerge --update world</i>
619     </pre>
620    
621     <p>
622     Again, if you want to see what <c>emerge</c> wants to update, use the
623     <c>--pretend</c> option together with the <c>--update</c> option:
624     </p>
625    
626     <pre caption="Pretending to update your entire system">
627     # <i>emerge --pretend --update world</i>
628     <comment>(Some output removed to improve readability)</comment>
629     [ebuild U ] net-misc/wget-1.9-r1 [1.9]
630     [ebuild UD] media-video/dvdauthor-0.5.0 [0.5.3]
631     [ebuild U ] net-analyzer/ethereal-0.9.16 [0.9.14]
632     </pre>
633    
634     <p>
635     Right next to the word "ebuild" you will notice a letter (or combination of
636     letters) which gives you more information about the package:
637     </p>
638    
639     <ul>
640     <li>
641     <e>B</e> (blocks) The package listed to the left is blocking the emerge of
642     the package listed to the right
643     </li>
644     <li>
645     <e>N</e> (new) The package is new to your system and will be emerged for the
646     first time
647     </li>
648     <li>
649     <e>R</e> (reemerge) The package isn't new, but needs to be reemerged
650     </li>
651     <li>
652 swift 1.15 <e>F</e> (fetch) The package requires that you download the source code
653 swift 1.3 manually (for instance due to licencing issues)
654     </li>
655     <li>
656     <e>U</e> (update) The package already exists on your system but will be
657     upgraded
658     </li>
659     <li>
660     <e>UD</e> (downgrade) The package already exists on your system but will be
661     downgraded
662     </li>
663     <li>
664     <e>U-</e> (slot warning) The package you have installed on your system
665     is listed as a package that can not coexist with a different version, but
666     your update does. The update will be installed and the older version will be
667     removed.
668     </li>
669     </ul>
670    
671     <p>
672     In certain cases, an update may mean a downgrade (i.e. install an older version
673     instead of a newer version). If you don't want this to happen, use the
674     <c>--upgradeonly</c> option (<c>-U</c> in short):
675     </p>
676    
677     <pre caption="Upgrading your entire system">
678     # <i>emerge --update --upgradeonly world</i>
679     </pre>
680    
681     <p>
682 swift 1.25 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 swift 1.4 Of course, we are talking here about <e>system</e> and <e>world</e>, but you can
695 swift 1.3 perform the same actions for individual software packages.
696     </p>
697    
698 swift 1.1 </body>
699     </subsection>
700     <subsection>
701     <title>Removing Software</title>
702     <body>
703    
704 swift 1.3 <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 swift 1.11
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 swift 1.16 <c>cfgpro</c> : This file is located inside a protected directory and will
748     not be touched for safety
749 swift 1.11 </li>
750     </ul>
751 swift 1.3
752 swift 1.1 </body>
753     </subsection>
754     </section>
755     <section>
756     <title>Software Availability</title>
757     <subsection>
758     <title>ARCH or not?</title>
759     <body>
760    
761 swift 1.3 <p>
762     Gentoo places its packages in two possible stadia called <e>ARCH</e> and
763     <e>~ARCH</e>. Don't take this literally: the stadia depend on the architecture
764     you are using. In other words, for x86-based systems you have <e>x86</e> and
765     <e>~x86</e>, for ppc-based systems you have <e>ppc</e> and <e>~ppc</e> etc.
766     </p>
767    
768     <p>
769     The <e>~ARCH</e> stadium means that the package works for the developer in
770     charge of the package, but that the package hasn't been tested thoroughly enough
771     by the community to be placed in <e>ARCH</e>. <e>~ARCH</e> packages usually go
772     to <e>ARCH</e> after being bugfree for a sufficient amount of time.
773     </p>
774    
775     <p>
776     Your system will use <e>ARCH</e> packages per default. If you want to live on
777 swift 1.21 the edge, don't mind having a broken package once in a while, know how to deal
778     with a broken system and you like submitting bugreports to <uri
779 swift 1.3 link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use
780     <e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system,
781     edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that
782     it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).
783     </p>
784    
785     <p>
786 swift 1.21 Note though that it is far from trivial (if even impossible) to go back to
787     <e>ARCH</e> from <e>~ARCH</e>.
788     </p>
789    
790     <p>
791 swift 1.3 If you want to update your system now, you will notice that <e>a lot</e> of
792     packages will be updated!
793     </p>
794    
795 swift 1.1 </body>
796     </subsection>
797     <subsection>
798     <title>Masked Packages</title>
799     <body>
800    
801 swift 1.3 <p>
802     When you want to install a package, you might come across the following message:
803     </p>
804    
805     <pre caption="Message about masked packages">
806     Calculating dependencies
807     !!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment>
808     </pre>
809    
810     <p>
811     A package can be masked due to two reasons:
812     </p>
813    
814     <ol>
815     <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li>
816     <li>The package is hard-masked explicitly</li>
817     </ol>
818    
819     <p>
820 neysx 1.27 If the package is masked because of the first reason, and you <e>really</e>
821     want to install it (knowing that there <e>is</e> a reason why it isn't
822     available in <e>ARCH</e>), you can accept the <e>~ARCH</e> version of any
823     package by adding it to your <path>/etc/portage/package.keywords</path> file:
824 swift 1.3 </p>
825    
826 neysx 1.27 <pre caption="Accepting the ~ARCH version of a package">
827     # <i>echo "app-office/gnumeric ~x86" &gt;&gt; /etc/portage/package.keywords</i>
828     # <i>emerge gnumeric</i>
829 swift 1.3 </pre>
830    
831     <p>
832     A package is hardmasked if it is listed in
833     <path>/usr/portage/profiles/package.mask</path>. If you read this file, you
834     will also read the reason why the package is hardmasked (it is usually added as
835     a comment). If you want to install the package nevertheless (despite all the
836     possible warnings we could ever throw at your head about "breaking your system",
837     "breaks other packages", or "badly needs testing"), create the
838     <path>/etc/portage/package.unmask</path> file and list the package in it (use
839     the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
840     </p>
841    
842     <p>
843     Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as
844 dertobi123 1.19 all changes are undone the next time you update your Portage tree. If you want
845     to hardmask a package create <path>/etc/portage/package.mask</path> and list the
846     package in it (use the same format as mentioned above).
847 swift 1.3 </p>
848    
849 swift 1.22 <!--
850 swift 1.3 <p>
851     Another trick to circumvent the "masked package" problem is to install the
852     package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c>
853     settings and the <path>package.mask</path> listing.
854     </p>
855    
856     <pre caption="Installing a package without checking for stadium / masking">
857     # <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i>
858     </pre>
859 swift 1.22 -->
860 swift 1.3
861 swift 1.1 </body>
862     </subsection>
863     <subsection>
864     <title>Blocked Packages</title>
865     <body>
866 swift 1.3
867     <p>
868     You have a situation when you receive the following error on your screen:
869     </p>
870    
871     <pre caption="Blocking package">
872     [blocks B ] gnome-base/bonobo-activation (from pkg gnome-base/libbonobo-2.4.0)
873     </pre>
874    
875     <p>
876     In the above example, the package <c>bonobo-activation</c> is blocking the
877     emerge of <c>libbonobo</c>. To resolve this issue, remove the
878     <c>bonobo-activation</c> package and continue:
879     </p>
880    
881     <pre caption="Resolving a blocking situation">
882     # <i>emerge unmerge bonobo-activation</i>
883     </pre>
884 swift 1.1
885     </body>
886     </subsection>
887     </section>
888     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20