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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.6 Revision 1.38
1<?xml version='1.0' encoding='UTF-8'?>
2<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
1<!-- The content of this document is licensed under the CC-BY-SA license --> 4<!-- The content of this document is licensed under the CC-BY-SA license -->
2<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> 5<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3 6
4<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.6 2003/11/27 14:45:38 swift Exp $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.38 2004/10/02 21:53:56 cam Exp $ -->
5 8
6<sections> 9<sections>
7<section> 10<section>
8<title>Obtaining Package Information</title> 11<title>Obtaining Package Information</title>
9<subsection> 12<subsection>
12 15
13<p> 16<p>
14The main Portage tool that most users will use is <c>emerge</c>. We have already 17The main Portage tool that most users will use is <c>emerge</c>. We have already
15used it during the Gentoo installation and in the previous chapter, but we just 18used it during the Gentoo installation and in the previous chapter, but we just
16briefly explained how to use it. This chapter will elaborate on <c>emerge</c> 19briefly explained how to use it. This chapter will elaborate on <c>emerge</c>
17and learn you how to use <c>emerge</c> to fix all your software-related needs. 20and teach you how to use <c>emerge</c> to fix all your software-related needs.
18</p> 21</p>
19 22
20<p> 23<p>
21<c>emerge</c> is the command used to install, remove, query and maintain 24<c>emerge</c> is the command used to install, remove, query and maintain
22software packages. It is a front-end for <c>ebuild</c>; people interested in 25software packages. It is a front-end for <c>ebuild</c>; people interested in
87dev-lisp/ gnome-extra/ net-p2p/ 90dev-lisp/ gnome-extra/ net-p2p/
88</pre> 91</pre>
89 92
90<p> 93<p>
91As you can see, the Portage tree has several subdirectories. Most of them are 94As you can see, the Portage tree has several subdirectories. Most of them are
92the <e>categories</e> in which the Gentoo packages, called <e>ebuilds</e>, 95the <e>categories</e> in which the Gentoo packages reside. Take a look at, for
93reside. Take a look at, for instance, <path>app-office</path>: 96instance, <path>app-office</path>:
94</p> 97</p>
95 98
96<pre caption="Viewing a category"> 99<pre caption="Viewing a category">
97# <i>cd app-office; ls --classify</i> 100# <i>cd app-office; ls --classify</i>
98abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x 101abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x
103gnofin/ khacc/ mrproject/ phprojekt/ texmacs/ 106gnofin/ khacc/ mrproject/ phprojekt/ texmacs/
104</pre> 107</pre>
105 108
106<p> 109<p>
107Inside a category you will find the packages belonging to that category, with a 110Inside a category you will find the packages belonging to that category, with a
108seperate directory for each package. Let us take a look at the <c>openoffice</c> 111separate directory for each package. Let us take a look at the <c>openoffice</c>
109package: 112package:
110</p> 113</p>
111 114
112<pre caption="Viewing a package"> 115<pre caption="Viewing a package">
113# <i>cd openoffice; ls --classify</i> 116# <i>cd openoffice; ls --classify</i>
114ChangeLog files/ openoffice-1.0.3-r1.ebuild openoffice-1.1.0-r2.ebuild 117ChangeLog files/ openoffice-1.0.3-r1.ebuild openoffice-1.1.0-r2.ebuild
115Manifest metadata.xml openoffice-1.1.0-r1.ebuild openoffice-1.1.0.ebuild 118Manifest metadata.xml openoffice-1.1.0-r1.ebuild openoffice-1.1.0.ebuild
116</pre> 119</pre>
117 120
118<p> 121<p>
119Remember that we told you that a Gentoo package is called an ebuild? Well, in 122In the example directory, four ebuilds are stored. An <e>ebuild</e> is a script
120the example directory four of such ebuilds are stored. Their naming is 123which contains all the necessary information about a specific version of a
121almost identical: they only differ in the version name. 124package. The naming for the ebuilds is almost identical; they only differ in
125the version name.
122You are free to view the contents of such a package: they are plain scripts. We 126You are free to view the contents of such an ebuild: they are plain scripts. We
123will not discuss it right now as it isn't important to know if you plan on just 127will not discuss it right now as it isn't important to know if you plan on just
124using Gentoo. 128using Gentoo.
125</p> 129</p>
126 130
127<p> 131<p>
128The other files are the <path>ChangeLog</path> (which contains a listing of all 132The other files are the <path>ChangeLog</path> (which contains a listing of all
129the changes done to the ebuilds), <path>Manifest</path> (which contains the 133the changes done to the ebuilds), <path>Manifest</path> (which contains the
130checksums and permissions of all the files in the directory) and 134checksums and filesizes of all the files in the directory) and
131<path>metadata.xml</path> (which contains more information about the package, 135<path>metadata.xml</path> (which contains more information about the package,
132such as the responsible development group -- called <e>herd</e> -- and a more 136such as the responsible development group -- called <e>herd</e> -- and a more
133extensive description). 137extensive description).
134</p> 138</p>
135 139
136<p> 140<p>
137Inside the <path>files</path> directory you will find extra files, needed by 141Inside the <path>files</path> directory, you will find extra files, needed by
138Portage: digests (checksums and permissions of the files needed by a single 142Portage: digests (names, sizes and checksums of the files needed by a single
139version of the package), patches, example configuration files, etc. 143version of the package), patches, example configuration files, etc.
140</p> 144</p>
141 145
142<pre caption="Viewing the extra files"> 146<pre caption="Viewing the extra files">
143# <i>cd files; ls --classify</i> 147# <i>cd files; ls --classify</i>
150nptl.patch 154nptl.patch
151</pre> 155</pre>
152 156
153<p> 157<p>
154If you go back to the root of the Portage tree (<path>/usr/portage</path>) you 158If you go back to the root of the Portage tree (<path>/usr/portage</path>) you
155will notice that there are other, non-category directories too. We will discuss 159will notice that there are other, non-category directories, too. We will discuss
156those later in this chapter. 160those later in this chapter.
157</p> 161</p>
158 162
159</body> 163</body>
160</subsection> 164</subsection>
217</pre> 221</pre>
218 222
219<p> 223<p>
220As you can see, the output of <c>emerge</c> informs you about the category and 224As you can see, the output of <c>emerge</c> informs you about the category and
221name of the package, the available version, the currently installed version, 225name of the package, the available version, the currently installed version,
222the size of the downloaded files, the homepage and the small description. 226the size of the downloaded files, the homepage and the short description.
223</p>
224
225<p> 227</p>
228
229<p>
226You see something new? Yes, <e>downloaded files</e>. When you tell Portage to 230Do you see something else? Yes, <e>downloaded files</e>. When you tell Portage
227install a package, it of course needs to have the necessary sources (or 231to install a package, it of course needs to have the necessary sources (or
228precompiled packages) available. It therefore checks the contents of 232precompiled packages) available. It therefore checks the contents of
229<path>/usr/portage/distfiles</path> (for sourcecode) or 233<path>/usr/portage/distfiles</path> to see if the necessary files are already
230<path>/usr/portage/packages/All</path> (for precompiled packages) to see if the 234available. If not, it downloads the necessary files and places them in that
231necessary files are already available. If not, it downloads the necessary files 235directory.
232and places them in those directories.
233</p> 236</p>
234
235<note>
236Searching the Portage Tree, especially when using <c>--searchdesc</c>, is very
237time consuming. There are other, more performant tools available. We will
238describe those in the chapter on <uri link="?part=2&amp;chap=7">Gentoolkit and
239Other Tools</uri>.
240</note>
241 237
242</body> 238</body>
243</subsection> 239</subsection>
244<subsection> 240<subsection>
245<title>Viewing the ChangeLog</title> 241<title>Viewing the ChangeLog</title>
246<body> 242<body>
247 243
248<p> 244<p>
249While browsing through the Portage Tree, you saw that there was a ChangeLog for 245While browsing through the Portage Tree, you saw that there was a ChangeLog for
250each package. You can view this ChangeLog with <c>emerge</c> too. Use the 246each package. You can view the ChangeLog entries between the available version
247and the installed version with <c>emerge</c> too. Use the
251<c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we 248<c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we
252will view the ChangeLog entries for <c>gnumeric</c>: 249will view the ChangeLog entries for <c>gnumeric</c>:
253</p> 250</p>
254 251
255<pre caption="Viewing the ChangeLog entries for gnumeric"> 252<pre caption="Viewing the ChangeLog entries for gnumeric">
256# <i>emerge --pretend --changelog gnumeric</i> 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.
257</pre> 266</pre>
258 267
259</body> 268</body>
260</subsection> 269</subsection>
261</section> 270</section>
284<subsection> 293<subsection>
285<title>Selecting a Mirror for rsync</title> 294<title>Selecting a Mirror for rsync</title>
286<body> 295<body>
287 296
288<p> 297<p>
289It is adviseable to first select a fast <uri 298It is advisable to first select a fast <uri
290link="/main/en/mirrors.xml">mirror</uri> close to you. You can do this manually 299link="/main/en/mirrors.xml">mirror</uri> close to you. You can do this manually
291(by setting the <c>SYNC</c> variable in <path>/etc/make.conf</path>) or use 300(by setting the <c>SYNC</c> variable in <path>/etc/make.conf</path>) or use
292<c>mirrorselect</c> to do this for you automatically. As the <c>SYNC</c> 301<c>mirrorselect</c> to do this for you automatically. As the <c>SYNC</c>
293variable will be discussed later on, we will focus on using <c>mirrorselect</c>. 302variable will be discussed later on, we will focus on using <c>mirrorselect</c>.
294First install <c>mirrorselect</c> by emerging it: 303First install <c>mirrorselect</c> by emerging it:
298# <i>emerge --usepkg mirrorselect</i> 307# <i>emerge --usepkg mirrorselect</i>
299</pre> 308</pre>
300 309
301<p> 310<p>
302Now run <c>mirrorselect</c> to automatically select mirrors for you (it will 311Now run <c>mirrorselect</c> to automatically select mirrors for you (it will
303also setup Portage to use a mirror for the sourcecode): 312also setup Portage to use a mirror for the source code):
304</p> 313</p>
305 314
306<pre caption="Running mirrorselect"> 315<pre caption="Running mirrorselect">
307# <i>mirrorselect -a -s3</i> 316# <i>mirrorselect -a -s3</i>
308</pre> 317</pre>
312<subsection> 321<subsection>
313<title>Updating Portage</title> 322<title>Updating Portage</title>
314<body> 323<body>
315 324
316<p> 325<p>
317To update Portage using rsync, simply run <c>emerge sync</c>: 326To update Portage using rsync, simply run <c>emerge --sync</c>:
318</p> 327</p>
319 328
320<pre caption="Updating Portage using emerge sync"> 329<pre caption="Updating Portage using emerge --sync">
321# <i>emerge sync</i> 330# <i>emerge --sync</i>
322</pre> 331</pre>
323 332
324<p> 333<p>
325If this fails (due to network problems, or a firewall), you can try using 334If this fails (due to network problems, or a firewall), you can try using
326<c>emerge-webrsync</c> which will download a Portage Tree snapshot using 335<c>emerge-webrsync</c> which will download a Portage Tree snapshot using
336</subsection> 345</subsection>
337</section> 346</section>
338<section> 347<section>
339<title>Maintaining Software</title> 348<title>Maintaining Software</title>
340<subsection> 349<subsection>
341<title>Building or Prebuild?</title> 350<title>Building or Prebuilt?</title>
342<body> 351<body>
343 352
344<p> 353<p>
345Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to 354Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to
346install such an ebuild, you can choose between <e>building</e> the package, or 355install such an ebuild, you can choose between <e>building</e> the package and
347using a <e>prebuild</e> package. But what are the advantages/disadvantages of 356using a <e>prebuilt</e> package. But what are the advantages/disadvantages of
348both approaches, and can they be used next to each other? 357both approaches, and can they be used alongside each other?
349</p> 358</p>
350 359
351<p> 360<p>
352As you probably have guessed, building packages takes a lot of time (especially 361As you probably have guessed, building packages takes a lot of time (especially
353if you have little resources or want to build big packages, such as <uri 362if you have little resources or want to build big packages, such as <uri
357Of course, you can also define high optimization options (in the <c>CFLAGS</c> 366Of course, you can also define high optimization options (in the <c>CFLAGS</c>
358and <c>CXXFLAGS</c> variables) to compile the package with. 367and <c>CXXFLAGS</c> variables) to compile the package with.
359</p> 368</p>
360 369
361<p> 370<p>
362Using prebuild packages improves the installation time (as no more compilation 371Using prebuilt packages improves the installation time (as no more compilation
363is needed), but you will lose the advantages of the <c>USE</c> setting and the 372is needed), but you will lose the advantages of the <c>USE</c> setting and the
364<c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables. 373<c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables.
365</p> 374</p>
366 375
367<p> 376<p>
368As previously stated, prebuild packages are stored in the 377As previously stated, prebuilt packages are stored in the
369<path>/usr/portage/packages/All</path> directory, while the sourcecode of the 378<path>/usr/portage/packages/All</path> directory, while the source code of the
370packages are placed in <path>/usr/portage/distfiles</path>. If you have finished 379packages is placed in <path>/usr/portage/distfiles</path>. If you have finished
371installing a package you can remove the package or sourcecode from the 380installing a package you can remove the package or source code from the
372respective directory. However, you might want to keep the package/sourcecode of 381respective directory. However, you might want to keep the package/source code of
373the latest version, just in case you want to reinstall the package (so you don't 382the latest version, just in case you want to reinstall the package (so you don't
374have to redownload it). 383have to redownload it).
375</p> 384</p>
376 385
377</body> 386</body>
380<title>Installing Software from Sources</title> 389<title>Installing Software from Sources</title>
381<body> 390<body>
382 391
383<p> 392<p>
384Okay, enough talking, let's cut to the chase. To install a package, you will use 393Okay, enough talking, let's cut to the chase. To install a package, you will use
385the <c>emerge</c> command. If you don't want to use any prebuild packages, you 394the <c>emerge</c> command. If you don't want to use any prebuilt packages, you
386can just use <c>emerge &lt;package-name&gt;</c> or <c>emerge 395can just use <c>emerge &lt;package-name&gt;</c> or <c>emerge
387&lt;category&gt;/&lt;package-name&gt;</c>. As an example we'll install 396&lt;category&gt;/&lt;package-name&gt;</c>. As an example we'll install
388<c>gnumeric</c>: 397<c>gnumeric</c>:
389</p> 398</p>
390 399
391<pre caption="Building gnumeric"> 400<pre caption="Building gnumeric">
392# <i>emerge gnumeric</i> 401# <i>emerge gnumeric</i>
393</pre> 402</pre>
394 403
395<p> 404<p>
396This will download the sourcecode for you and unpacks, compiles and installs the 405This will download the source code for you and unpacks, compiles and installs
397package on your system. It will also do the same for all the dependencies. If 406the package on your system. It will also do the same for all the dependencies.
398you want to see what dependencies will be installed with it, use the 407If you want to see what dependencies will be installed with it, use the
399<c>--pretend</c> option (<c>-p</c> in short): 408<c>--pretend</c> option (<c>-p</c> in short):
400</p> 409</p>
401 410
402<pre caption="Pretending to build gnumeric"> 411<pre caption="Pretending to build gnumeric">
403# <i>emerge --pretend gnumeric</i> 412# <i>emerge --pretend gnumeric</i>
404</pre> 413</pre>
405 414
406<p> 415<p>
407If you want to download the sourcecode of the package and its dependencies, 416If you want to download the source code of the package and its dependencies,
408but don't want to build the package, use the <c>--fetchonly</c> option 417but don't want to build the package, use the <c>--fetchonly</c> option
409(<c>-f</c> in short): 418(<c>-f</c> in short):
410</p> 419</p>
411 420
412<pre caption="Fetching sources for gnumeric"> 421<pre caption="Fetching sources for gnumeric">
431<pre caption="Installing a specific gnumeric version"> 440<pre caption="Installing a specific gnumeric version">
432# <i>emerge "&lt;gnumeric-1.2"</i> 441# <i>emerge "&lt;gnumeric-1.2"</i>
433</pre> 442</pre>
434 443
435<p> 444<p>
436Other possibilities are of course "&gt;" (later version) and "=" (the exact 445Other possibilities are of course "&gt;" (later version), "=" (the exact
437version). 446version) and the combinations "&lt;=" and "&gt;=".
438</p> 447</p>
439 448
440</body> 449</body>
441</subsection>
442<subsection> 450</subsection>
451<subsection>
443<title>Installing Prebuild Packages</title> 452<title>Installing Prebuilt Packages</title>
444<body> 453<body>
445 454
446<p> 455<p>
447When you want to install a prebuild package, you should use the <c>--usepkg</c> 456When you want to install a prebuilt package, you should use the <c>--usepkg</c>
448option (<c>-k</c> in short). This will use the binary package available in 457option (<c>-k</c> in short). This will use the binary package available in
449<path>/usr/portage/packages/All</path> <e>if</e> the package and the version of 458<path>/usr/portage/packages/All</path> <e>if</e> the package and the version of
450the application you want to install match. 459the application you want to install match.
451</p> 460</p>
452 461
453<pre caption="Installing a prebuild package for gnumeric"> 462<pre caption="Installing a prebuilt package for gnumeric">
454# <i>emerge --usepkg gnumeric</i> 463# <i>emerge --usepkg gnumeric</i>
455</pre> 464</pre>
456 465
457<p> 466<p>
458If you want to use the binary package, even if the versions don't match, use 467If you want to use the binary package, even if the versions don't match, use
459<c>--usepkgonly</c> (<c>-K</c> in short). 468<c>--usepkgonly</c> (<c>-K</c> in short).
460</p> 469</p>
461 470
462<pre caption="Installing the prebuild package for gnumeric"> 471<pre caption="Installing the prebuilt package for gnumeric">
463# <i>emerge --usepkgonly gnumeric</i> 472# <i>emerge --usepkgonly gnumeric</i>
464</pre> 473</pre>
465 474
466<!-- TODO When handbook goes life, comment out this parts until the mirrors have
467 been updated with online GRP packages. -->
468<p> 475<p>
469If you don't have the prebuild package on your system yet, you can have 476If you don't have the prebuilt package on your system yet, you can have
470<c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c> 477<c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c>
471variable declared in <path>/etc/make.conf</path>. 478variable declared in <path>/etc/make.conf</path>.
472</p> 479</p>
473 480
481<note>
482Gentoo does not have any server or mirror containing such prebuilt packages.
483Portage has been extended with this feature to fullfil the community request.
484</note>
485
474<p> 486<p>
475To download the binary package in case this package doesn't exist on 487To download the binary package in case this package doesn't exist on
476your system already, use <c>--getbinpkg</c> (<c>-g</c> in short): 488your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
477</p> 489</p>
478 490
479<pre caption="Downloading and installing a prebuild package for gnumeric"> 491<pre caption="Downloading and installing a prebuilt package for gnumeric">
480# <i>emerge --getbinpkg gnumeric</i> 492# <i>emerge --getbinpkg gnumeric</i>
481</pre> 493</pre>
482 494
483<p> 495<p>
484This will download the package and the package-related information for you and 496This will download the package and the package-related information for you and
485install it on your system, together with the dependencies. If you want to see 497install it on your system, together with the dependencies. If you want to see
486what dependencies will be installed with it, use the <c>--pretend</c> option 498what dependencies will be installed with it, use the <c>--pretend</c> option
487(<c>-p</c> in short): 499(<c>-p</c> in short):
488</p> 500</p>
489 501
490<pre caption="Pretending to download the prebuild packages for gnumeric"> 502<pre caption="Pretending to download the prebuilt packages for gnumeric">
491# <i>emerge --ginbinpkg --pretend gnumeric</i> 503# <i>emerge --getbinpkg --pretend gnumeric</i>
492</pre> 504</pre>
493 505
494<p> 506<p>
495You can also opt to download the prebuild package (and the package-related 507You can also opt to download the prebuilt package (and the package-related
496information) <e>without</e> checking the information on your local system and 508information) <e>without</e> checking the information on your local system and
497<e>without</e> using the prebuild package already on your system (if 509<e>without</e> using the prebuilt package already on your system (if
498applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short): 510applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short):
499</p> 511</p>
500 512
501<pre caption="Installing a prebuild package without using local information"> 513<pre caption="Installing a prebuilt package without using local information">
502# <i>emerge --getbinpkgonly gnumeric</i> 514# <i>emerge --getbinpkgonly gnumeric</i>
503</pre> 515</pre>
504
505<!-- TODO Up until here -->
506 516
507<p> 517<p>
508You can also opt to install a specific version of a package. 518You can also opt to install a specific version of a package.
509For instance, if you want to install a gnumeric version older than 1.2 -- for 519For instance, if you want to install a gnumeric version older than 1.2 -- for
510any reason whatsoever :) you would type: 520any reason whatsoever :) you would type:
513<pre caption="Installing a specific gnumeric version"> 523<pre caption="Installing a specific gnumeric version">
514# <i>emerge --usepkg "&lt;gnumeric-1.2"</i> 524# <i>emerge --usepkg "&lt;gnumeric-1.2"</i>
515</pre> 525</pre>
516 526
517<p> 527<p>
518Other possibilities are of course "&gt;" (later version) and "=" (the exact 528Other possibilities are of course "&gt;" (later version), "=" (the exact
519version). 529version) and the combinations "&lt;=" and "&gt;=".
530</p>
531
532
533</body>
534</subsection>
535<subsection>
536<title>Working with Dependencies</title>
537<body>
538
520</p> 539<p>
540Portage has extensive support for dependency handling. Although you usually
541don't need to even think about this (as dependencies are automatically handled
542by Portage) some users might want to know how you can work with <c>emerge</c>
543and dependencies.
544</p>
521 545
546<p>
547For instance, if you want Portage to pretend that none of the dependencies of a
548package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This
549is useful with <c>--pretend</c> to display a complete tree of dependencies for
550any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile
551all 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>
559Another argument is <c>--nodeps</c>, which will ask Portage to try install the
560given package without taking care of the dependencies. This can all too often
561lead 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>
569The opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage
570install 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>
578When you uninstall software Portage will not automatically unmerge the
579dependencies that aren't needed anymore. If you want to "clean" your system from
580those orphaned dependencies, you can use <c>emerge depclean</c>. This will
581search for all installed software that you haven't installed explicitly and that
582isn't a dependency of software that you have installed explicitly.
583</p>
584
585<warn>
586Using depclean can seriously impair your system. Use with caution and
587double-check the list of dependencies that Portage wants to remove before you go
588ahead!
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>
522 596
523</body> 597</body>
524</subsection> 598</subsection>
525<subsection> 599<subsection>
526<title>Updating your System</title> 600<title>Updating your System</title>
586 <li> 660 <li>
587 <e>N</e> (new) The package is new to your system and will be emerged for the 661 <e>N</e> (new) The package is new to your system and will be emerged for the
588 first time 662 first time
589 </li> 663 </li>
590 <li> 664 <li>
591 <e>R</e> (reemerge) The package isn't new, but needs to be reemerged 665 <e>R</e> (replace) The package isn't new, but will be reemerged
592 </li>
593 <li> 666 </li>
667 <li>
594 <e>F</e> (fetch) The package requires that you download the sourcecode 668 <e>F</e> (fetch) The package requires that you download the source code
595 manually (for instance due to licencing issues) 669 manually (for instance due to licencing issues)
596 </li> 670 </li>
597 <li> 671 <li>
598 <e>U</e> (update) The package already exists on your system but will be 672 <e>U</e> (update) The package already exists on your system but will be
599 upgraded 673 upgraded
600 </li> 674 </li>
601 <li> 675 <li>
602 <e>UD</e> (downgrade) The package already exists on your system but will be 676 <e>UD</e> (downgrade) The package already exists on your system but will be
603 downgraded 677 downgraded
604 </li> 678 </li>
605 <li>
606 <e>U-</e> (slot warning) The package you have installed on your system
607 is listed as a package that can not coexist with a different version, but
608 your update does. The update will be installed and the older version will be
609 removed.
610 </li>
611</ul> 679</ul>
612 680
613<p> 681<p>
614In certain cases, an update may mean a downgrade (i.e. install an older version 682We have mentioned that the <e>world</e> file doesn't contain dependencies. When
615instead of a newer version). If you don't want this to happen, use the 683you run <c>emerge --update world</c> only the packages mentioned in the
616<c>--upgradeonly</c> option (<c>-U</c> in short): 684<e>world</e> file and it's immediate dependencies are checked and, if necessary,
685upgraded. 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:
617</p> 687</p>
618 688
619<pre caption="Upgrading your entire system"> 689<pre caption="Upgrading your entire system, including all dependencies">
620# <i>emerge --update --upgradeonly world</i> 690# <i>emerge --update --deep world</i>
621</pre> 691</pre>
622 692
623<p> 693<p>
624Of course, we are talking here about <e>system</e> and <e>world</e>, but you can 694Of course, we are talking here about <e>system</e> and <e>world</e>, but you can
625perform the same actions for individual software packages. 695perform the same actions for individual software packages.
654installed package. It also doesn't warn you if the package is part of 724installed package. It also doesn't warn you if the package is part of
655<e>system</e>, i.e. a core application necessary for the correct functioning of 725<e>system</e>, i.e. a core application necessary for the correct functioning of
656your system! 726your system!
657</warn> 727</warn>
658 728
729<p>
730Once the unmerge begins you will see a long list of filenames belonging to the
731package. Some of these filenames will have a flag displayed to the
732left of the filename. The flags <c>!mtime</c>, <c>!empty</c>, and <c>cfgpro</c>
733specify reasons why certain files are not being removed while the package is.
734Files listed without any of these three flags are removed from the
735filesystem 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
659</body> 752</body>
660</subsection> 753</subsection>
661</section> 754</section>
662<section> 755<section>
663<title>Software Availability</title> 756<title>Working with Masked Packages</title>
664<subsection> 757<subsection>
665<title>ARCH or not?</title> 758<title>ARCH or not?</title>
666<body> 759<body>
667 760
668<p> 761<p>
669Gentoo places its packages in two possible stadia called <e>ARCH</e> and 762When a Gentoo developer puts an ebuild online it informs Portage how to treat
670<e>~ARCH</e>. Don't take this literally: the stadia depend on the architecture 763the package depending on the architecture and stability of the software title.
671you are using. In other words, for x86-based systems you have <e>x86</e> and 764He does so by defining a variable called <c>KEYWORDS</c> inside the ebuild.
672<e>~x86</e>, for ppc-based systems you have <e>ppc</e> and <e>~ppc</e> etc. 765This variable contains one or more architectures and marks them with a special
673</p> 766flag. An explanation of the available flags is given in the next table.
674
675<p> 767</p>
676The <e>~ARCH</e> stadium means that the package works for the developer in 768
677charge of the package, but that the package hasn't been tested thoroughly enough 769<table>
678by the community to be placed in <e>ARCH</e>. <e>~ARCH</e> packages usually go 770<tr>
679to <e>ARCH</e> after being bugfree for a sufficient amount of time. 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
680</p> 795<p>
796Let's take a look at an example:
797</p>
798
799<pre caption="Example KEYWORDS setting">
800KEYWORDS="x86 -sparc ~alpha ~ppc"
801</pre>
802
803<p>
804This 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>
681 824
682<p> 825<p>
683Your system will use <e>ARCH</e> packages per default. If you want to live on 826Your system will use <e>ARCH</e> packages per default. If you want to live on
684the edge, don't mind having a broken package once in a while, and you like 827the edge, don't mind having a broken package once in a while, know how to deal
685submitting bugreports to <uri 828with a broken system and you like submitting bugreports to <uri
686link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use 829link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use
687<e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system, 830<e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system,
688edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that 831edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that
689it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.). 832it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).
690</p> 833</p>
691 834
692<p> 835<p>
836Note though that it is far from simple (or even impossible) to go back to
837<e>ARCH</e> from <e>~ARCH</e>.
838</p>
839
840<p>
693If you want to update your system now, you will notice that <e>a lot</e> of 841If you want to update your system now, you will notice that <e>a lot</e> of
694packages will be updated! 842packages will be updated!
695</p> 843</p>
696 844
697</body> 845</body>
708Calculating dependencies 856Calculating dependencies
709!!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment> 857!!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment>
710</pre> 858</pre>
711 859
712<p> 860<p>
713A package can be masked due to two reasons: 861A package can be masked due to several reasons:
714</p> 862</p>
715 863
716<ol> 864<ol>
717 <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li> 865 <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li>
718 <li>The package is hard-masked explicitly</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>
719</ol> 869</ol>
720 870
721<p> 871<p>
872Portage 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>
722If the package is masked because of the first reason, and you <e>really</e> want 899If the package is masked because of <b>~arch keyword</b>, and you <e>really</e>
723to install it (knowing that there <e>is</e> a reason why it isn't available in 900want to install it (knowing that there <e>is</e> a reason why it isn't
724<e>ARCH</e>), you can temporarily accept <e>~ARCH</e> packages: 901available in <e>ARCH</e>), you can accept the <e>~ARCH</e> version of any
725</p> 902package by adding it to your <path>/etc/portage/package.keywords</path> file:
726
727<pre caption="Temporarily accepting ~ARCH packages">
728# <i>ACCEPT_KEYWORDS="~x86" emerge gnumeric</i>
729</pre>
730
731<p> 903</p>
732A package is hardmasked if it is listed in 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>
914Similarly, if you want to install a package marked <b>-arch keyword</b> or <b>-*
915keyword</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
917keyword:
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>
931If you only want to allow the merging of such a package for a specific version
932or 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>
940A package is masked due to <b>package.mask</b> if it is listed in
733<path>/usr/portage/profiles/package.mask</path>. If you read this file, you 941<path>/usr/portage/profiles/package.mask</path>. If you read this file, you
734will also read the reason why the package is hardmasked (it is usually added as 942will also read the reason why the package is hardmasked (it is usually added as
735a comment). If you want to install the package nevertheless (despite all the 943a comment). If you want to install the package nevertheless (despite all the
736possible warnings we could ever throw at your head about "breaking your system", 944possible warnings we could ever throw at your head about "breaking your system",
737"breaks other packages", or "badly needs testing"), create the 945"breaks other packages", or "badly needs testing"), create the
738<path>/etc/portage/package.unmask</path> file and list the package in it (use 946<path>/etc/portage/package.unmask</path> file and list the package in it (use
739the same format as is used in <path>/usr/portage/profiles/package.mask</path>). 947the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
740</p> 948</p>
741 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
742<p> 957<p>
743Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as 958Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as
744all changes are undone the next time you update your Portage tree. 959all changes are undone the next time you update your Portage tree.
745</p>
746
747<p> 960</p>
748Another trick to circumvent the "masked package" problem is to install the 961
749package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c>
750settings and the <path>package.mask</path> listing.
751</p> 962<p>
752 963Sometimes you might want to hardmask a (collection of) package(s). This is the
753<pre caption="Installing a package without checking for stadium / masking"> 964case when newer versions of an application don't support something you require
754# <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i> 965or when these versions break something else in your environment.
755</pre> 966</p>
967
968<p>
969To hard-mask a package, create <path>/etc/portage/package.mask</path> and list
970the 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>
981When Portage tells you that it cannot install a package due to <b>profile</b> it
982means that you are working with a certain profile that doesn't allow the package
983to be installed. But what is this "profile"?
984</p>
985
986<p>
987A profile contains a list of package names and a set of default configuration
988options to be used by Portage. Those files tell Portage which packages
989and which specific versions of those packages to allow, disallow, or
990treat as required. Users can switch profiles by changing a single symlink
991(<path>/etc/make.profile</path>).
992</p>
993
994<p>
995You cannot override a package that is blocked due to <b>profile</b>; if you
996really want to use it, switch to the required profile.
997</p>
998
999<p>
1000You will find more information in our <uri
1001link="/proj/en/releng/docs/cascading-profiles.xml">Cascading Profiles
1002Document</uri>.
1003</p>
756 1004
757</body> 1005</body>
758</subsection> 1006</subsection>
759<subsection> 1007<subsection>
760<title>Blocked Packages</title> 1008<title>Blocked Packages</title>

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.38

  ViewVC Help
Powered by ViewVC 1.1.20