/[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.16
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.6 2003/11/27 14:45:38 swift Exp $ --> 4<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.16 2004/01/06 15:39:48 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>
12 12
13<p> 13<p>
14The main Portage tool that most users will use is <c>emerge</c>. We have already 14The 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 15used 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> 16briefly 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. 17and teach you how to use <c>emerge</c> to fix all your software-related needs.
18</p> 18</p>
19 19
20<p> 20<p>
21<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
22software 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
103gnofin/ khacc/ mrproject/ phprojekt/ texmacs/ 103gnofin/ khacc/ mrproject/ phprojekt/ texmacs/
104</pre> 104</pre>
105 105
106<p> 106<p>
107Inside 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
108seperate 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>
109package: 109package:
110</p> 110</p>
111 111
112<pre caption="Viewing a package"> 112<pre caption="Viewing a package">
113# <i>cd openoffice; ls --classify</i> 113# <i>cd openoffice; ls --classify</i>
224 224
225<p> 225<p>
226You 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
227install a package, it of course needs to have the necessary sources (or 227install a package, it of course needs to have the necessary sources (or
228precompiled packages) available. It therefore checks the contents of 228precompiled packages) available. It therefore checks the contents of
229<path>/usr/portage/distfiles</path> (for sourcecode) or 229<path>/usr/portage/distfiles</path> (for source code) or
230<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
231necessary files are already available. If not, it downloads the necessary files 231necessary files are already available. If not, it downloads the necessary files
232and places them in those directories. 232and places them in those directories.
233</p> 233</p>
234 234
235<!--
235<note> 236<note>
236Searching the Portage Tree, especially when using <c>--searchdesc</c>, is very 237Searching the Portage Tree, especially when using <c>- -searchdesc</c>, is very
237time consuming. There are other, more performant tools available. We will 238time 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 239describe those in the chapter on <uri link="?part=2&amp;chap=7">Gentoolkit and
239Other Tools</uri>. 240Other Tools</uri>.
240</note> 241</note>
242-->
241 243
242</body> 244</body>
243</subsection> 245</subsection>
244<subsection> 246<subsection>
245<title>Viewing the ChangeLog</title> 247<title>Viewing the ChangeLog</title>
298# <i>emerge --usepkg mirrorselect</i> 300# <i>emerge --usepkg mirrorselect</i>
299</pre> 301</pre>
300 302
301<p> 303<p>
302Now run <c>mirrorselect</c> to automatically select mirrors for you (it will 304Now run <c>mirrorselect</c> to automatically select mirrors for you (it will
303also setup Portage to use a mirror for the sourcecode): 305also setup Portage to use a mirror for the source code):
304</p> 306</p>
305 307
306<pre caption="Running mirrorselect"> 308<pre caption="Running mirrorselect">
307# <i>mirrorselect -a -s3</i> 309# <i>mirrorselect -a -s3</i>
308</pre> 310</pre>
336</subsection> 338</subsection>
337</section> 339</section>
338<section> 340<section>
339<title>Maintaining Software</title> 341<title>Maintaining Software</title>
340<subsection> 342<subsection>
341<title>Building or Prebuild?</title> 343<title>Building or Prebuilt?</title>
342<body> 344<body>
343 345
344<p> 346<p>
345Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to 347Gentoo 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 348install 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 349using a <e>prebuilt</e> package. But what are the advantages/disadvantages of
348both approaches, and can they be used next to each other? 350both approaches, and can they be used next to each other?
349</p> 351</p>
350 352
351<p> 353<p>
352As you probably have guessed, building packages takes a lot of time (especially 354As you probably have guessed, building packages takes a lot of time (especially
357Of course, you can also define high optimization options (in the <c>CFLAGS</c> 359Of course, you can also define high optimization options (in the <c>CFLAGS</c>
358and <c>CXXFLAGS</c> variables) to compile the package with. 360and <c>CXXFLAGS</c> variables) to compile the package with.
359</p> 361</p>
360 362
361<p> 363<p>
362Using prebuild packages improves the installation time (as no more compilation 364Using 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 365is needed), but you will lose the advantages of the <c>USE</c> setting and the
364<c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables. 366<c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables.
365</p> 367</p>
366 368
367<p> 369<p>
368As previously stated, prebuild packages are stored in the 370As previously stated, prebuilt packages are stored in the
369<path>/usr/portage/packages/All</path> directory, while the sourcecode of the 371<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 372packages is placed in <path>/usr/portage/distfiles</path>. If you have finished
371installing a package you can remove the package or sourcecode from the 373installing a package you can remove the package or source code from the
372respective directory. However, you might want to keep the package/sourcecode of 374respective 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 375the latest version, just in case you want to reinstall the package (so you don't
374have to redownload it). 376have to redownload it).
375</p> 377</p>
376 378
377</body> 379</body>
380<title>Installing Software from Sources</title> 382<title>Installing Software from Sources</title>
381<body> 383<body>
382 384
383<p> 385<p>
384Okay, enough talking, let's cut to the chase. To install a package, you will use 386Okay, 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 387the <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 388can 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 389&lt;category&gt;/&lt;package-name&gt;</c>. As an example we'll install
388<c>gnumeric</c>: 390<c>gnumeric</c>:
389</p> 391</p>
390 392
391<pre caption="Building gnumeric"> 393<pre caption="Building gnumeric">
392# <i>emerge gnumeric</i> 394# <i>emerge gnumeric</i>
393</pre> 395</pre>
394 396
395<p> 397<p>
396This will download the sourcecode for you and unpacks, compiles and installs the 398This 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 399the 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 400If you want to see what dependencies will be installed with it, use the
399<c>--pretend</c> option (<c>-p</c> in short): 401<c>--pretend</c> option (<c>-p</c> in short):
400</p> 402</p>
401 403
402<pre caption="Pretending to build gnumeric"> 404<pre caption="Pretending to build gnumeric">
403# <i>emerge --pretend gnumeric</i> 405# <i>emerge --pretend gnumeric</i>
404</pre> 406</pre>
405 407
406<p> 408<p>
407If you want to download the sourcecode of the package and its dependencies, 409If 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 410but don't want to build the package, use the <c>--fetchonly</c> option
409(<c>-f</c> in short): 411(<c>-f</c> in short):
410</p> 412</p>
411 413
412<pre caption="Fetching sources for gnumeric"> 414<pre caption="Fetching sources for gnumeric">
438</p> 440</p>
439 441
440</body> 442</body>
441</subsection> 443</subsection>
442<subsection> 444<subsection>
443<title>Installing Prebuild Packages</title> 445<title>Installing Prebuilt Packages</title>
444<body> 446<body>
445 447
446<p> 448<p>
447When you want to install a prebuild package, you should use the <c>--usepkg</c> 449When 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 450option (<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 451<path>/usr/portage/packages/All</path> <e>if</e> the package and the version of
450the application you want to install match. 452the application you want to install match.
451</p> 453</p>
452 454
453<pre caption="Installing a prebuild package for gnumeric"> 455<pre caption="Installing a prebuilt package for gnumeric">
454# <i>emerge --usepkg gnumeric</i> 456# <i>emerge --usepkg gnumeric</i>
455</pre> 457</pre>
456 458
457<p> 459<p>
458If you want to use the binary package, even if the versions don't match, use 460If you want to use the binary package, even if the versions don't match, use
459<c>--usepkgonly</c> (<c>-K</c> in short). 461<c>--usepkgonly</c> (<c>-K</c> in short).
460</p> 462</p>
461 463
462<pre caption="Installing the prebuild package for gnumeric"> 464<pre caption="Installing the prebuilt package for gnumeric">
463# <i>emerge --usepkgonly gnumeric</i> 465# <i>emerge --usepkgonly gnumeric</i>
464</pre> 466</pre>
465 467
466<!-- TODO When handbook goes life, comment out this parts until the mirrors have
467 been updated with online GRP packages. -->
468<p> 468<p>
469If you don't have the prebuild package on your system yet, you can have 469If 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> 470<c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c>
471variable declared in <path>/etc/make.conf</path>. 471variable declared in <path>/etc/make.conf</path>.
472</p> 472</p>
473 473
474<p> 474<p>
475To download the binary package in case this package doesn't exist on 475To download the binary package in case this package doesn't exist on
476your system already, use <c>--getbinpkg</c> (<c>-g</c> in short): 476your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
477</p> 477</p>
478 478
479<pre caption="Downloading and installing a prebuild package for gnumeric"> 479<pre caption="Downloading and installing a prebuilt package for gnumeric">
480# <i>emerge --getbinpkg gnumeric</i> 480# <i>emerge --getbinpkg gnumeric</i>
481</pre> 481</pre>
482 482
483<p> 483<p>
484This will download the package and the package-related information for you and 484This 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 485install 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 486what dependencies will be installed with it, use the <c>--pretend</c> option
487(<c>-p</c> in short): 487(<c>-p</c> in short):
488</p> 488</p>
489 489
490<pre caption="Pretending to download the prebuild packages for gnumeric"> 490<pre caption="Pretending to download the prebuilt packages for gnumeric">
491# <i>emerge --ginbinpkg --pretend gnumeric</i> 491# <i>emerge --getbinpkg --pretend gnumeric</i>
492</pre> 492</pre>
493 493
494<p> 494<p>
495You can also opt to download the prebuild package (and the package-related 495You can also opt to download the prebuilt package (and the package-related
496information) <e>without</e> checking the information on your local system and 496information) <e>without</e> checking the information on your local system and
497<e>without</e> using the prebuild package already on your system (if 497<e>without</e> using the prebuilt package already on your system (if
498applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short): 498applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short):
499</p> 499</p>
500 500
501<pre caption="Installing a prebuild package without using local information"> 501<pre caption="Installing a prebuilt package without using local information">
502# <i>emerge --getbinpkgonly gnumeric</i> 502# <i>emerge --getbinpkgonly gnumeric</i>
503</pre> 503</pre>
504
505<!-- TODO Up until here -->
506 504
507<p> 505<p>
508You can also opt to install a specific version of a package. 506You 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 507For instance, if you want to install a gnumeric version older than 1.2 -- for
510any reason whatsoever :) you would type: 508any reason whatsoever :) you would type:
517<p> 515<p>
518Other possibilities are of course "&gt;" (later version) and "=" (the exact 516Other possibilities are of course "&gt;" (later version) and "=" (the exact
519version). 517version).
520</p> 518</p>
521 519
520
521</body>
522</subsection>
523<subsection>
524<title>Working with Dependencies</title>
525<body>
526
527<p>
528Portage has an extensive support for dependency handling. Although you usually
529don't need to even think about this (as dependencies are automatically handled
530by Portage) some users might want to know how you can work with <c>emerge</c>
531and dependencies.
532</p>
533
534<p>
535For instance, if you want Portage to pretend that none of the dependencies of a
536package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This
537is useful with <c>--pretend</c> to display a complete tree of dependencies for
538any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile
539all listed packages. However, <c>glibc</c> will <e>not</e> be listed as
540dependency for safety reasons.
541</p>
542
543<pre caption="Show all dependencies of gnumeric">
544# <i>emerge --emptytree --pretend gnumeric</i>
545</pre>
546
547<p>
548Another argument is <c>--nodeps</c>, which will ask Portage to try install the
549given package without taking care of the dependencies. It is trivial that this
550can lead to failures.
551</p>
552
553<pre caption="Installing gnumeric without taking care of the dependencies">
554# <i>emerge --nodeps gnumeric</i>
555</pre>
556
557<p>
558The opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage
559install all dependencies of a given package, but not the package itself:
560</p>
561
562<pre caption="Installing the dependencies of gnumeric">
563# <i>emerge --onlydeps gnumeric</i>
564</pre>
522 565
523</body> 566</body>
524</subsection> 567</subsection>
525<subsection> 568<subsection>
526<title>Updating your System</title> 569<title>Updating your System</title>
589 </li> 632 </li>
590 <li> 633 <li>
591 <e>R</e> (reemerge) The package isn't new, but needs to be reemerged 634 <e>R</e> (reemerge) The package isn't new, but needs to be reemerged
592 </li> 635 </li>
593 <li> 636 <li>
594 <e>F</e> (fetch) The package requires that you download the sourcecode 637 <e>F</e> (fetch) The package requires that you download the source code
595 manually (for instance due to licencing issues) 638 manually (for instance due to licencing issues)
596 </li> 639 </li>
597 <li> 640 <li>
598 <e>U</e> (update) The package already exists on your system but will be 641 <e>U</e> (update) The package already exists on your system but will be
599 upgraded 642 upgraded
653Portage doesn't verify if a package is a dependency for another 696Portage doesn't verify if a package is a dependency for another
654installed package. It also doesn't warn you if the package is part of 697installed 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 698<e>system</e>, i.e. a core application necessary for the correct functioning of
656your system! 699your system!
657</warn> 700</warn>
701
702<p>
703Once the unmerge begins you will see a long list of filenames belonging to the
704package. Some of these filenames will have a flag displayed to the
705left of the filename. The flags <c>!mtime</c>, <c>!empty</c>, and <c>cfgpro</c>
706specify reasons why certain files are not being removed while the package is.
707Files listed without any of these three flags are removed from the
708filesystem successfully. The three flags specify the following reasons:
709</p>
710
711<ul>
712 <li>
713 <c>!mtime</c> : The listed file has been changed since it was installed,
714 probably by you or some tool
715 </li>
716 <li>
717 <c>!empty</c> : The listed directory is not empty
718 </li>
719 <li>
720 <c>cfgpro</c> : This file is located inside a protected directory and will
721 not be touched for safety
722 </li>
723</ul>
658 724
659</body> 725</body>
660</subsection> 726</subsection>
661</section> 727</section>
662<section> 728<section>

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

  ViewVC Help
Powered by ViewVC 1.1.20