/[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.3 Revision 1.13
1<!-- The content of this document is licensed under the CC-BY-SA license --> 1<!-- The content of this document is licensed under the CC-BY-SA license -->
2<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> 2<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3 3
4<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.3 2003/11/26 20:19:59 swift Exp $ --> 4<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.13 2003/12/04 22:26:19 swift Exp $ -->
5 5
6<sections> 6<sections>
7<section> 7<section>
8<title>Obtaining Package Information</title> 8<title>Obtaining Package Information</title>
9<subsection> 9<subsection>
10<title>The Lord of All Tools: emerge</title> 10<title>The Lord of All Tools: emerge</title>
11<body> 11<body>
12 12
13<p> 13<p>
14We have briefly encountered <c>emerge</c> in the previous chapter, but not to 14The main Portage tool that most users will use is <c>emerge</c>. We have already
15the extent that you are now able to work with it to its fullest potential. We 15used it during the Gentoo installation and in the previous chapter, but we just
16will fix that right now ;-) 16briefly explained how to use it. This chapter will elaborate on <c>emerge</c>
17and teach you how to use <c>emerge</c> to fix all your software-related needs.
17</p> 18</p>
18 19
19<p> 20<p>
20<c>emerge</c> is the command used to install, remove, query and maintain 21<c>emerge</c> is the command used to install, remove, query and maintain
21software packages. It is a front-end for <c>ebuild</c>; people interested in 22software packages. It is a front-end for <c>ebuild</c>; people interested in
42<body> 43<body>
43 44
44<p> 45<p>
45Before we continue describing <c>emerge</c>, let us first take a look at the 46Before we continue describing <c>emerge</c>, let us first take a look at the
46Portage Tree. Go to <path>/usr/portage</path> and do a listing of the available 47Portage Tree. Go to <path>/usr/portage</path> and do a listing of the available
47directories. 48directories. We use <c>ls --classify</c> to list the contents of a
49directory as it will show directories with a trailing "/".
48</p> 50</p>
49 51
50<pre caption="Viewing the Portage Tree"> 52<pre caption="Viewing the Portage Tree">
51# <i>cd /usr/portage; ls --classify</i> 53# <i>cd /usr/portage; ls --classify</i>
52<comment>(The --classify will append a special character to note the filetype)</comment>
53app-admin/ dev-ml/ gnome-libs/ net-print/ 54app-admin/ dev-ml/ gnome-libs/ net-print/
54app-arch/ dev-perl/ gnome-office/ net-wireless/ 55app-arch/ dev-perl/ gnome-office/ net-wireless/
55app-benchmarks/ dev-php/ header.txt net-www/ 56app-benchmarks/ dev-php/ header.txt net-www/
56app-cdr/ dev-python/ incoming/ net-zope/ 57app-cdr/ dev-python/ incoming/ net-zope/
57app-crypt/ dev-ruby/ jython/ packages/ 58app-crypt/ dev-ruby/ jython/ packages/
102gnofin/ khacc/ mrproject/ phprojekt/ texmacs/ 103gnofin/ khacc/ mrproject/ phprojekt/ texmacs/
103</pre> 104</pre>
104 105
105<p> 106<p>
106Inside a category you will find the packages belonging to that category, with a 107Inside a category you will find the packages belonging to that category, with a
107seperate directory for each package. Let us take a look at the <c>openoffice</c> 108separate directory for each package. Let us take a look at the <c>openoffice</c>
108package: 109package:
109</p> 110</p>
110 111
111<pre caption="Viewing a package"> 112<pre caption="Viewing a package">
112# <i>cd openoffice; ls --classify</i> 113# <i>cd openoffice; ls --classify</i>
126<p> 127<p>
127The other files are the <path>ChangeLog</path> (which contains a listing of all 128The other files are the <path>ChangeLog</path> (which contains a listing of all
128the changes done to the ebuilds), <path>Manifest</path> (which contains the 129the changes done to the ebuilds), <path>Manifest</path> (which contains the
129checksums and permissions of all the files in the directory) and 130checksums and permissions of all the files in the directory) and
130<path>metadata.xml</path> (which contains more information about the package, 131<path>metadata.xml</path> (which contains more information about the package,
131such as the responsible development group -- called <e>herd</e> and a more 132such as the responsible development group -- called <e>herd</e> -- and a more
132extensive description). 133extensive description).
133</p> 134</p>
134 135
135<p> 136<p>
136Inside the <path>files</path> directory you will find extra files, needed by 137Inside the <path>files</path> directory you will find extra files, needed by
221the size of the downloaded files, the homepage and the small description. 222the size of the downloaded files, the homepage and the small description.
222</p> 223</p>
223 224
224<p> 225<p>
225You see something new? Yes, <e>downloaded files</e>. When you tell Portage to 226You see something new? Yes, <e>downloaded files</e>. When you tell Portage to
226install a package, it ofcourse needs to have the necessary sources (or 227install a package, it of course needs to have the necessary sources (or
227precompiled packages) available. It therefor checks the contents of 228precompiled packages) available. It therefore checks the contents of
228<path>/usr/portage/distfiles</path> (for sourcecode) or 229<path>/usr/portage/distfiles</path> (for sourcecode) or
229<path>/usr/portage/packages/All</path> (for precompiled packages) to see if the 230<path>/usr/portage/packages/All</path> (for precompiled packages) to see if the
230necessary files are already available. If not, it downloads the necessary files 231necessary files are already available. If not, it downloads the necessary files
231and places them in those directories. 232and places them in those directories.
232</p> 233</p>
265<body> 266<body>
266 267
267<p> 268<p>
268Searching through Portage is nice, but if you don't update your Portage Tree 269Searching through Portage is nice, but if you don't update your Portage Tree
269regularly, you will be stuck with the packages and versions available on your 270regularly, you will be stuck with the packages and versions available on your
270system. This means that your system will get outdated pretty soon, and that 271system. This means that your system will get outdated pretty soon and that
271packages with possible security problems will remain on your system. 272you will be missing bugfixes and remedies for possible security problems.
272</p> 273</p>
273 274
274<p> 275<p>
275There are several ways to update your Portage Tree. The most popular method is 276There are several ways to update your Portage Tree. The most popular method is
276by using one of our <uri link="/main/en/mirrors.xml">rsync mirrors</uri>. 277by using one of our <uri link="/main/en/mirrors.xml">rsync mirrors</uri>.
335</subsection> 336</subsection>
336</section> 337</section>
337<section> 338<section>
338<title>Maintaining Software</title> 339<title>Maintaining Software</title>
339<subsection> 340<subsection>
340<title>Building or Prebuild?</title> 341<title>Building or Prebuilt?</title>
341<body> 342<body>
342 343
343<p> 344<p>
344Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to 345Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to
345install such an ebuild, you can choose between <e>building</e> the package, or 346install such an ebuild, you can choose between <e>building</e> the package, or
346using a <e>prebuild</e> package. But what are the advantages/disadvantages of 347using a <e>prebuilt</e> package. But what are the advantages/disadvantages of
347both approaches, and can they be used next to each other? 348both approaches, and can they be used next to each other?
348</p> 349</p>
349 350
350<p> 351<p>
351As you probably have guessed, building packages takes a lot of time (especially 352As you probably have guessed, building packages takes a lot of time (especially
352if you have little resources or want to build big packages, such as <uri 353if you have little resources or want to build big packages, such as <uri
353link="http://www.kde.org">KDE</uri>, <uri 354link="http://www.kde.org">KDE</uri>, <uri
354link="http://www.openoffice.org">OpenOffice.org</uri>, etc.). By building the 355link="http://www.openoffice.org">OpenOffice.org</uri>, etc.). By building the
355package, you can use the <c>USE</c> setting to tweak the package to your system. 356package, you can use the <c>USE</c> setting to tweak the package to your system.
356Ofcourse, you can also define high optimization options (in the <c>CFLAGS</c> 357Of course, you can also define high optimization options (in the <c>CFLAGS</c>
357and <c>CXXFLAGS</c> variables) to compile the package with. 358and <c>CXXFLAGS</c> variables) to compile the package with.
358</p> 359</p>
359 360
360<p> 361<p>
361Using prebuild packages improves the installation time (as no more compilation 362Using prebuilt packages improves the installation time (as no more compilation
362is needed), but you will lose the advantages of the <c>USE</c> setting and the 363is 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<c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables.
364</p> 365</p>
365 366
366<p> 367<p>
367As previously stated, prebuild packages are stored in the 368As previously stated, prebuilt packages are stored in the
368<path>/usr/portage/packages/All</path> directory, while the sourcecode of the 369<path>/usr/portage/packages/All</path> directory, while the sourcecode of the
369packages are placed in <path>/usr/portage/distfiles</path>. If you have finished 370packages are placed in <path>/usr/portage/distfiles</path>. If you have finished
370installing a package you can remove the package or sourcecode from the 371installing a package you can remove the package or sourcecode from the
371respective directory. However, you might want to keep the package/sourcecode of 372respective directory. However, you might want to keep the package/sourcecode of
372the latest version, just in case you want to reinstall the package (so you don't 373the latest version, just in case you want to reinstall the package (so you don't
379<title>Installing Software from Sources</title> 380<title>Installing Software from Sources</title>
380<body> 381<body>
381 382
382<p> 383<p>
383Okay, enough talking, let's cut to the chase. To install a package, you will use 384Okay, enough talking, let's cut to the chase. To install a package, you will use
384the <c>emerge</c> command. If you don't want to use any prebuild packages, you 385the <c>emerge</c> command. If you don't want to use any prebuilt packages, you
385can just use <c>emerge &lt;package-name&gt;</c> or <c>emerge 386can 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&lt;category&gt;/&lt;package-name&gt;</c>. As an example we'll install
387<c>gnumeric</c>: 388<c>gnumeric</c>:
388</p> 389</p>
389 390
430<pre caption="Installing a specific gnumeric version"> 431<pre caption="Installing a specific gnumeric version">
431# <i>emerge "&lt;gnumeric-1.2"</i> 432# <i>emerge "&lt;gnumeric-1.2"</i>
432</pre> 433</pre>
433 434
434<p> 435<p>
435Other possibilities are ofcourse "&gt;" (later version) and "=" (the exact 436Other possibilities are of course "&gt;" (later version) and "=" (the exact
436version). 437version).
437</p> 438</p>
438 439
439</body> 440</body>
440</subsection> 441</subsection>
441<subsection> 442<subsection>
442<title>Installing Prebuild Packages</title> 443<title>Installing Prebuilt Packages</title>
443<body> 444<body>
444 445
445<p> 446<p>
446When you want to install a prebuild package, you should use the <c>--usepkg</c> 447When you want to install a prebuilt package, you should use the <c>--usepkg</c>
447option (<c>-k</c> in short). This will use the binary package available in 448option (<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<path>/usr/portage/packages/All</path> <e>if</e> the package and the version of
449the application you want to install match. 450the application you want to install match.
450</p> 451</p>
451 452
452<pre caption="Installing a prebuild package for gnumeric"> 453<pre caption="Installing a prebuilt package for gnumeric">
453# <i>emerge --usepkg gnumeric</i> 454# <i>emerge --usepkg gnumeric</i>
454</pre> 455</pre>
455 456
456<p> 457<p>
457If you want to use the binary package, even if the versions don't match, use 458If 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<c>--usepkgonly</c> (<c>-K</c> in short).
459</p> 460</p>
460 461
461<pre caption="Installing the prebuild package for gnumeric"> 462<pre caption="Installing the prebuilt package for gnumeric">
462# <i>emerge --usepkgonly gnumeric</i> 463# <i>emerge --usepkgonly gnumeric</i>
463</pre> 464</pre>
464 465
465<!-- TODO When handbook goes life, comment out this parts until the mirrors have
466 been updated with online GRP packages. -->
467<p> 466<p>
468If you don't have the prebuild package on your system yet, you can have 467If you don't have the prebuilt package on your system yet, you can have
469<c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c> 468<c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c>
470variable declared in <path>/etc/make.conf</path>. 469variable declared in <path>/etc/make.conf</path>.
471</p> 470</p>
472 471
473<p> 472<p>
474To download the binary package in case this package doesn't exist on 473To download the binary package in case this package doesn't exist on
475your system already, use <c>--getbinpkg</c> (<c>-g</c> in short): 474your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
476</p> 475</p>
477 476
478<pre caption="Downloading and installing a prebuild package for gnumeric"> 477<pre caption="Downloading and installing a prebuilt package for gnumeric">
479# <i>emerge --getbinpkg gnumeric</i> 478# <i>emerge --getbinpkg gnumeric</i>
480</pre> 479</pre>
481 480
482<p> 481<p>
483This will download the package and the package-related information for you and 482This will download the package and the package-related information for you and
484install it on your system, together with the dependencies. If you want to see 483install it on your system, together with the dependencies. If you want to see
485what dependencies will be installed with it, use the <c>--pretend</c> option 484what dependencies will be installed with it, use the <c>--pretend</c> option
486(<c>-p</c> in short): 485(<c>-p</c> in short):
487</p> 486</p>
488 487
489<pre caption="Pretending to download the prebuild packages for gnumeric"> 488<pre caption="Pretending to download the prebuilt packages for gnumeric">
490# <i>emerge --ginbinpkg --pretend gnumeric</i> 489# <i>emerge --getbinpkg --pretend gnumeric</i>
491</pre> 490</pre>
492 491
493<p> 492<p>
494You can also opt to download the prebuild package (and the package-related 493You can also opt to download the prebuilt package (and the package-related
495information) <e>without</e> checking the information on your local system and 494information) <e>without</e> checking the information on your local system and
496<e>without</e> using the prebuild package already on your system (if 495<e>without</e> using the prebuilt package already on your system (if
497applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short): 496applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short):
498</p> 497</p>
499 498
500<pre caption="Installing a prebuild package without using local information"> 499<pre caption="Installing a prebuilt package without using local information">
501# <i>emerge --getbinpkgonly gnumeric</i> 500# <i>emerge --getbinpkgonly gnumeric</i>
502</pre> 501</pre>
503
504<!-- TODO Up until here -->
505 502
506<p> 503<p>
507You can also opt to install a specific version of a package. 504You can also opt to install a specific version of a package.
508For instance, if you want to install a gnumeric version older than 1.2 -- for 505For instance, if you want to install a gnumeric version older than 1.2 -- for
509any reason whatsoever :) you would type: 506any reason whatsoever :) you would type:
512<pre caption="Installing a specific gnumeric version"> 509<pre caption="Installing a specific gnumeric version">
513# <i>emerge --usepkg "&lt;gnumeric-1.2"</i> 510# <i>emerge --usepkg "&lt;gnumeric-1.2"</i>
514</pre> 511</pre>
515 512
516<p> 513<p>
517Other possibilities are ofcourse "&gt;" (later version) and "=" (the exact 514Other possibilities are of course "&gt;" (later version) and "=" (the exact
518version). 515version).
519</p> 516</p>
520 517
518
519</body>
520</subsection>
521<subsection>
522<title>Working with Dependencies</title>
523<body>
524
525<p>
526Portage has an extensive support for dependency handling. Although you usually
527don't need to even think about this (as dependencies are automatically handled
528by Portage) some users might want to know how you can work with <c>emerge</c>
529and dependencies.
530</p>
531
532<p>
533For instance, if you want Portage to pretend that none of the dependencies of a
534package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This
535is useful with <c>--pretend</c> to display a complete tree of dependencies for
536any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile
537all listed packages. However, <c>glibc</c> will <e>not</e> be listed as
538dependency for safety reasons.
539</p>
540
541<pre caption="Show all dependencies of gnumeric">
542# <i>emerge --emptytree --pretend gnumeric</i>
543</pre>
544
545<p>
546Another argument is <c>--nodeps</c>, which will ask Portage to try install the
547given package without taking care of the dependencies. It is trivial that this
548can lead to failures.
549</p>
550
551<pre caption="Installing gnumeric without taking care of the dependencies">
552# <i>emerge --nodeps gnumeric</i>
553</pre>
554
555<p>
556To opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage
557install all dependencies of a given package, but not the package itself:
558</p>
559
560<pre caption="Installing the dependencies of gnumeric">
561# <i>emerge --onlydeps gnumeric</i>
562</pre>
521 563
522</body> 564</body>
523</subsection> 565</subsection>
524<subsection> 566<subsection>
525<title>Updating your System</title> 567<title>Updating your System</title>
618<pre caption="Upgrading your entire system"> 660<pre caption="Upgrading your entire system">
619# <i>emerge --update --upgradeonly world</i> 661# <i>emerge --update --upgradeonly world</i>
620</pre> 662</pre>
621 663
622<p> 664<p>
623Ofcourse, we are talking here about <e>system</e> and <e>world</e>, but you can 665Of course, we are talking here about <e>system</e> and <e>world</e>, but you can
624perform the same actions for individual software packages. 666perform the same actions for individual software packages.
625</p> 667</p>
626 668
627</body> 669</body>
628</subsection> 670</subsection>
652Portage doesn't verify if a package is a dependency for another 694Portage doesn't verify if a package is a dependency for another
653installed package. It also doesn't warn you if the package is part of 695installed 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 696<e>system</e>, i.e. a core application necessary for the correct functioning of
655your system! 697your system!
656</warn> 698</warn>
699
700<p>
701Once the unmerge begins you will see a long list of filenames belonging to the
702package. Some of these filenames will have a flag displayed to the
703left of the filename. The flags <c>!mtime</c>, <c>!empty</c>, and <c>cfgpro</c>
704specify reasons why certain files are not being removed while the package is.
705Files listed without any of these three flags are removed from the
706filesystem successfully. The three flags specify the following reasons:
707</p>
708
709<ul>
710 <li>
711 <c>!mtime</c> : The listed file has been changed since it was installed,
712 probably by you or some tool
713 </li>
714 <li>
715 <c>!empty</c> : The listed directory is not empty
716 </li>
717 <li>
718 <c>cfgpro</c> : Another already installed package claims to own this file
719 </li>
720</ul>
657 721
658</body> 722</body>
659</subsection> 723</subsection>
660</section> 724</section>
661<section> 725<section>

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.13

  ViewVC Help
Powered by ViewVC 1.1.20