/[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.2 Revision 1.3
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.2 2003/11/25 17:34:47 swift Exp $ --> 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 $ -->
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>
238Other Tools</uri>. 238Other Tools</uri>.
239</note> 239</note>
240 240
241</body> 241</body>
242</subsection> 242</subsection>
243<subsection>
244<title>Viewing the ChangeLog</title>
245<body>
246
247<p>
248While browsing through the Portage Tree, you saw that there was a ChangeLog for
249each package. You can view this ChangeLog with <c>emerge</c> too. Use the
250<c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we
251will view the ChangeLog entries for <c>gnumeric</c>:
252</p>
253
254<pre caption="Viewing the ChangeLog entries for gnumeric">
255# <i>emerge --pretend --changelog gnumeric</i>
256</pre>
257
258</body>
259</subsection>
243</section> 260</section>
244<section> 261<section>
245<title>Updating Portage</title> 262<title>Updating Portage</title>
246<subsection> 263<subsection>
247<title>Introduction</title> 264<title>Introduction</title>
318</subsection> 335</subsection>
319</section> 336</section>
320<section> 337<section>
321<title>Maintaining Software</title> 338<title>Maintaining Software</title>
322<subsection> 339<subsection>
323<title>Installing Software</title> 340<title>Building or Prebuild?</title>
324<body>
325
326</body> 341<body>
327</subsection> 342
343<p>
344Gentoo 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
346using a <e>prebuild</e> package. But what are the advantages/disadvantages of
347both approaches, and can they be used next to each other?
348</p>
349
350<p>
351As 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
353link="http://www.kde.org">KDE</uri>, <uri
354link="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.
356Ofcourse, you can also define high optimization options (in the <c>CFLAGS</c>
357and <c>CXXFLAGS</c> variables) to compile the package with.
358</p>
359
360<p>
361Using prebuild 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
363<c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables.
364</p>
365
366<p>
367As previously stated, prebuild packages are stored in the
368<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
370installing a package you can remove the package or sourcecode from the
371respective 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
373have to redownload it).
374</p>
375
376</body>
328<subsection> 377</subsection>
329<title>Updating Software</title> 378<subsection>
379<title>Installing Software from Sources</title>
380<body>
381
382<p>
383Okay, 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
385can just use <c>emerge &lt;package-name&gt;</c> or <c>emerge
386&lt;category&gt;/&lt;package-name&gt;</c>. As an example we'll install
387<c>gnumeric</c>:
388</p>
389
390<pre caption="Building gnumeric">
391# <i>emerge gnumeric</i>
392</pre>
393
394<p>
395This will download the sourcecode for you and unpacks, compiles and installs the
396package on your system. It will also do the same for all the dependencies. If
397you want to see what dependencies will be installed with it, use the
398<c>--pretend</c> option (<c>-p</c> in short):
399</p>
400
401<pre caption="Pretending to build gnumeric">
402# <i>emerge --pretend gnumeric</i>
403</pre>
404
405<p>
406If you want to download the sourcecode of the package and its dependencies,
407but don't want to build the package, use the <c>--fetchonly</c> option
408(<c>-f</c> in short):
409</p>
410
411<pre caption="Fetching sources for gnumeric">
412# <i>emerge --fetchonly gnumeric</i>
413</pre>
414
415<p>
416If you want to see where <c>emerge</c> downloads the sources from, combine the
417<c>--fetchonly</c> and <c>--pretend</c> options:
418</p>
419
420<pre caption="Showing URLs of the sources for gnumeric">
421# <i>emerge --fetchonly --pretend gnumeric</i>
422</pre>
423
424<p>
425You can also opt to install a specific version of a package.
426For instance, if you want to install a gnumeric version older than 1.2 -- for
427any reason whatsoever :) you would type:
428</p>
429
430<pre caption="Installing a specific gnumeric version">
431# <i>emerge "&lt;gnumeric-1.2"</i>
432</pre>
433
434<p>
435Other possibilities are ofcourse "&gt;" (later version) and "=" (the exact
436version).
437</p>
438
330<body> 439</body>
440</subsection>
441<subsection>
442<title>Installing Prebuild Packages</title>
443<body>
444
445<p>
446When you want to install a prebuild package, you should use the <c>--usepkg</c>
447option (<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
449the application you want to install match.
450</p>
451
452<pre caption="Installing a prebuild package for gnumeric">
453# <i>emerge --usepkg gnumeric</i>
454</pre>
455
456<p>
457If you want to use the binary package, even if the versions don't match, use
458<c>--usepkgonly</c> (<c>-K</c> in short).
459</p>
460
461<pre caption="Installing the prebuild package for gnumeric">
462# <i>emerge --usepkgonly gnumeric</i>
463</pre>
464
465<!-- TODO When handbook goes life, comment out this parts until the mirrors have
466 been updated with online GRP packages. -->
467<p>
468If you don't have the prebuild package on your system yet, you can have
469<c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c>
470variable declared in <path>/etc/make.conf</path>.
471</p>
472
473<p>
474To download the binary package in case this package doesn't exist on
475your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
476</p>
477
478<pre caption="Downloading and installing a prebuild package for gnumeric">
479# <i>emerge --getbinpkg gnumeric</i>
480</pre>
481
482<p>
483This 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
485what dependencies will be installed with it, use the <c>--pretend</c> option
486(<c>-p</c> in short):
487</p>
488
489<pre caption="Pretending to download the prebuild packages for gnumeric">
490# <i>emerge --ginbinpkg --pretend gnumeric</i>
491</pre>
492
493<p>
494You can also opt to download the prebuild package (and the package-related
495information) <e>without</e> checking the information on your local system and
496<e>without</e> using the prebuild package already on your system (if
497applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short):
498</p>
499
500<pre caption="Installing a prebuild package without using local information">
501# <i>emerge --getbinpkgonly gnumeric</i>
502</pre>
503
504<!-- TODO Up until here -->
505
506<p>
507You 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
509any reason whatsoever :) you would type:
510</p>
511
512<pre caption="Installing a specific gnumeric version">
513# <i>emerge --usepkg "&lt;gnumeric-1.2"</i>
514</pre>
515
516<p>
517Other possibilities are ofcourse "&gt;" (later version) and "=" (the exact
518version).
519</p>
520
521
522</body>
523</subsection>
524<subsection>
525<title>Updating your System</title>
526<body>
527
528<p>
529Portage knows two special tags to denote a set of software packages:
530<e>system</e> and <e>world</e>. You have already seen the former while
531installing Gentoo if you didn't use a <e>stage3</e> installation. To refresh
532things: <e>system</e> is the collection of <e>core</e> packages, necessary to
533have a working Gentoo system.
534</p>
535
536<p>
537The <e>world</e> tag consists of all software you have installed yourself on
538your system plus the <e>system</e> information. In other words, every time you
539emerge a package using <c>emerge &lt;package-name&gt;</c>, the
540<c>&lt;package-name&gt;</c> is registered in the <e>world</e> file
541(<path>/var/cache/edb/world</path>). Dependencies are <e>not</e> part of the
542<e>world</e> file, but we will get to that later.
543</p>
544
545<p>
546If you want to update the system packages, use the <c>--update</c> option
547(<c>-u</c> in short):
548</p>
549
550<pre caption="Updating the system packages">
551# <i>emerge --update system</i>
552</pre>
553
554<p>
555An identical approach can be used for the world packages:
556</p>
557
558<pre caption="Updating your entire system">
559# <i>emerge --update world</i>
560</pre>
561
562<p>
563Again, if you want to see what <c>emerge</c> wants to update, use the
564<c>--pretend</c> option together with the <c>--update</c> option:
565</p>
566
567<pre caption="Pretending to update your entire system">
568# <i>emerge --pretend --update world</i>
569<comment>(Some output removed to improve readability)</comment>
570[ebuild U ] net-misc/wget-1.9-r1 [1.9]
571[ebuild UD] media-video/dvdauthor-0.5.0 [0.5.3]
572[ebuild U ] net-analyzer/ethereal-0.9.16 [0.9.14]
573</pre>
574
575<p>
576Right next to the word "ebuild" you will notice a letter (or combination of
577letters) which gives you more information about the package:
578</p>
579
580<ul>
581 <li>
582 <e>B</e> (blocks) The package listed to the left is blocking the emerge of
583 the package listed to the right
584 </li>
585 <li>
586 <e>N</e> (new) The package is new to your system and will be emerged for the
587 first time
588 </li>
589 <li>
590 <e>R</e> (reemerge) The package isn't new, but needs to be reemerged
591 </li>
592 <li>
593 <e>F</e> (fetch) The package requires that you download the sourcecode
594 manually (for instance due to licencing issues)
595 </li>
596 <li>
597 <e>U</e> (update) The package already exists on your system but will be
598 upgraded
599 </li>
600 <li>
601 <e>UD</e> (downgrade) The package already exists on your system but will be
602 downgraded
603 </li>
604 <li>
605 <e>U-</e> (slot warning) The package you have installed on your system
606 is listed as a package that can not coexist with a different version, but
607 your update does. The update will be installed and the older version will be
608 removed.
609 </li>
610</ul>
611
612<p>
613In certain cases, an update may mean a downgrade (i.e. install an older version
614instead of a newer version). If you don't want this to happen, use the
615<c>--upgradeonly</c> option (<c>-U</c> in short):
616</p>
617
618<pre caption="Upgrading your entire system">
619# <i>emerge --update --upgradeonly world</i>
620</pre>
621
622<p>
623Ofcourse, we are talking here about <e>system</e> and <e>world</e>, but you can
624perform the same actions for individual software packages.
625</p>
331 626
332</body> 627</body>
333</subsection> 628</subsection>
334<subsection> 629<subsection>
335<title>Removing Software</title> 630<title>Removing Software</title>
336<body> 631<body>
632
633<p>
634If you want to remove software from your system, you can use the <c>unmerge</c>
635option (<c>-C</c> - capital C - in short):
636</p>
637
638<pre caption="Uninstalling software">
639# <i>emerge unmerge gnumeric</i>
640</pre>
641
642<p>
643If you want to test a removal (but not perform it), you can use <c>--pretend</c>
644again:
645</p>
646
647<pre caption="Pretending to uninstall software">
648# <i>emerge --pretend unmerge gnumeric</i>
649</pre>
650
651<warn>
652Portage 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
654<e>system</e>, i.e. a core application necessary for the correct functioning of
655your system!
656</warn>
337 657
338</body> 658</body>
339</subsection> 659</subsection>
340</section> 660</section>
341<section> 661<section>
342<title>Software Availability</title> 662<title>Software Availability</title>
343<subsection> 663<subsection>
344<title>ARCH or not?</title> 664<title>ARCH or not?</title>
345<body> 665<body>
346 666
667<p>
668Gentoo places its packages in two possible stadia called <e>ARCH</e> and
669<e>~ARCH</e>. Don't take this literally: the stadia depend on the architecture
670you are using. In other words, for x86-based systems you have <e>x86</e> and
671<e>~x86</e>, for ppc-based systems you have <e>ppc</e> and <e>~ppc</e> etc.
672</p>
673
674<p>
675The <e>~ARCH</e> stadium means that the package works for the developer in
676charge of the package, but that the package hasn't been tested thoroughly enough
677by the community to be placed in <e>ARCH</e>. <e>~ARCH</e> packages usually go
678to <e>ARCH</e> after being bugfree for a sufficient amount of time.
679</p>
680
681<p>
682Your system will use <e>ARCH</e> packages per default. If you want to live on
683the edge, don't mind having a broken package once in a while, and you like
684submitting bugreports to <uri
685link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use
686<e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system,
687edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that
688it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).
689</p>
690
691<p>
692If you want to update your system now, you will notice that <e>a lot</e> of
693packages will be updated!
694</p>
695
347</body> 696</body>
348</subsection> 697</subsection>
349<subsection> 698<subsection>
350<title>Masked Packages</title> 699<title>Masked Packages</title>
351<body> 700<body>
352 701
702<p>
703When you want to install a package, you might come across the following message:
704</p>
705
706<pre caption="Message about masked packages">
707Calculating dependencies
708!!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment>
709</pre>
710
711<p>
712A package can be masked due to two reasons:
713</p>
714
715<ol>
716 <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li>
717 <li>The package is hard-masked explicitly</li>
718</ol>
719
720<p>
721If the package is masked because of the first reason, and you <e>really</e> want
722to install it (knowing that there <e>is</e> a reason why it isn't available in
723<e>ARCH</e>), you can temporarily accept <e>~ARCH</e> packages:
724</p>
725
726<pre caption="Temporarily accepting ~ARCH packages">
727# <i>ACCEPT_KEYWORDS="~x86" emerge gnumeric</i>
728</pre>
729
730<p>
731A package is hardmasked if it is listed in
732<path>/usr/portage/profiles/package.mask</path>. If you read this file, you
733will also read the reason why the package is hardmasked (it is usually added as
734a comment). If you want to install the package nevertheless (despite all the
735possible warnings we could ever throw at your head about "breaking your system",
736"breaks other packages", or "badly needs testing"), create the
737<path>/etc/portage/package.unmask</path> file and list the package in it (use
738the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
739</p>
740
741<p>
742Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as
743all changes are undone the next time you update your Portage tree.
744</p>
745
746<p>
747Another trick to circumvent the "masked package" problem is to install the
748package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c>
749settings and the <path>package.mask</path> listing.
750</p>
751
752<pre caption="Installing a package without checking for stadium / masking">
753# <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i>
754</pre>
755
353</body> 756</body>
354</subsection> 757</subsection>
355<subsection> 758<subsection>
356<title>Blocked Packages</title> 759<title>Blocked Packages</title>
357<body> 760<body>
761
762<p>
763You have a situation when you receive the following error on your screen:
764</p>
765
766<pre caption="Blocking package">
767[blocks B ] gnome-base/bonobo-activation (from pkg gnome-base/libbonobo-2.4.0)
768</pre>
769
770<p>
771In the above example, the package <c>bonobo-activation</c> is blocking the
772emerge of <c>libbonobo</c>. To resolve this issue, remove the
773<c>bonobo-activation</c> package and continue:
774</p>
775
776<pre caption="Resolving a blocking situation">
777# <i>emerge unmerge bonobo-activation</i>
778</pre>
358 779
359</body> 780</body>
360</subsection> 781</subsection>
361</section> 782</section>
362</sections> 783</sections>

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

  ViewVC Help
Powered by ViewVC 1.1.20