/[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.22 Revision 1.34
2<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> 2<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3 3
4<!-- 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 -->
5<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> 5<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
6 6
7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.22 2004/02/03 20:25:45 swift Exp $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.34 2004/08/28 11:30:43 swift Exp $ -->
8 8
9<sections> 9<sections>
10<section> 10<section>
11<title>Obtaining Package Information</title> 11<title>Obtaining Package Information</title>
12<subsection> 12<subsection>
90dev-lisp/ gnome-extra/ net-p2p/ 90dev-lisp/ gnome-extra/ net-p2p/
91</pre> 91</pre>
92 92
93<p> 93<p>
94As 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
95the <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
96reside. Take a look at, for instance, <path>app-office</path>: 96instance, <path>app-office</path>:
97</p> 97</p>
98 98
99<pre caption="Viewing a category"> 99<pre caption="Viewing a category">
100# <i>cd app-office; ls --classify</i> 100# <i>cd app-office; ls --classify</i>
101abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x 101abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x
117ChangeLog 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
118Manifest 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
119</pre> 119</pre>
120 120
121<p> 121<p>
122Remember 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
123the example directory four of such ebuilds are stored. Their naming is 123which contains all the necessary information about a specific version of a
124almost identical: they only differ in the version name. 124package. The naming for the ebuilds is almost identical; they only differ in
125the version name.
125You 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
126will 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
127using Gentoo. 128using Gentoo.
128</p> 129</p>
129 130
130<p> 131<p>
135such 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
136extensive description). 137extensive description).
137</p> 138</p>
138 139
139<p> 140<p>
140Inside 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
141Portage: digests (checksums and permissions of the files needed by a single 142Portage: digests (names, sizes and checksums of the files needed by a single
142version of the package), patches, example configuration files, etc. 143version of the package), patches, example configuration files, etc.
143</p> 144</p>
144 145
145<pre caption="Viewing the extra files"> 146<pre caption="Viewing the extra files">
146# <i>cd files; ls --classify</i> 147# <i>cd files; ls --classify</i>
153nptl.patch 154nptl.patch
154</pre> 155</pre>
155 156
156<p> 157<p>
157If 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
158will 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
159those later in this chapter. 160those later in this chapter.
160</p> 161</p>
161 162
162</body> 163</body>
163</subsection> 164</subsection>
227 228
228<p> 229<p>
229You see something new? Yes, <e>downloaded files</e>. When you tell Portage to 230You see something new? Yes, <e>downloaded files</e>. When you tell Portage to
230install a package, it of course needs to have the necessary sources (or 231install a package, it of course needs to have the necessary sources (or
231precompiled packages) available. It therefore checks the contents of 232precompiled packages) available. It therefore checks the contents of
232<path>/usr/portage/distfiles</path> (for source code) or 233<path>/usr/portage/distfiles</path> to see if the necessary files are already
233<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
234necessary files are already available. If not, it downloads the necessary files 235directory.
235and places them in those directories.
236</p> 236</p>
237
238<!--
239<note>
240Searching the Portage Tree, especially when using <c>- -searchdesc</c>, is very
241time consuming. There are other, more performant tools available. We will
242describe those in the chapter on <uri link="?part=2&amp;chap=7">Gentoolkit and
243Other Tools</uri>.
244</note>
245-->
246 237
247</body> 238</body>
248</subsection> 239</subsection>
249<subsection> 240<subsection>
250<title>Viewing the ChangeLog</title> 241<title>Viewing the ChangeLog</title>
485If you don't have the prebuilt package on your system yet, you can have 476If you don't have the prebuilt package on your system yet, you can have
486<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>
487variable declared in <path>/etc/make.conf</path>. 478variable declared in <path>/etc/make.conf</path>.
488</p> 479</p>
489 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
490<p> 486<p>
491To 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
492your system already, use <c>--getbinpkg</c> (<c>-g</c> in short): 488your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
493</p> 489</p>
494 490
550<p> 546<p>
551For instance, if you want Portage to pretend that none of the dependencies of a 547For instance, if you want Portage to pretend that none of the dependencies of a
552package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This 548package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This
553is useful with <c>--pretend</c> to display a complete tree of dependencies for 549is useful with <c>--pretend</c> to display a complete tree of dependencies for
554any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile 550any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile
555all listed packages. However, <c>glibc</c> will <e>not</e> be listed as 551all listed packages.
556dependency for safety reasons.
557</p> 552</p>
558 553
559<pre caption="Show all dependencies of gnumeric"> 554<pre caption="Show all dependencies of gnumeric">
560# <i>emerge --emptytree --pretend gnumeric</i> 555# <i>emerge --emptytree --pretend gnumeric</i>
561</pre> 556</pre>
575install all dependencies of a given package, but not the package itself: 570install all dependencies of a given package, but not the package itself:
576</p> 571</p>
577 572
578<pre caption="Installing the dependencies of gnumeric"> 573<pre caption="Installing the dependencies of gnumeric">
579# <i>emerge --onlydeps gnumeric</i> 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>
580</pre> 595</pre>
581 596
582</body> 597</body>
583</subsection> 598</subsection>
584<subsection> 599<subsection>
645 <li> 660 <li>
646 <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
647 first time 662 first time
648 </li> 663 </li>
649 <li> 664 <li>
650 <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
651 </li> 666 </li>
652 <li> 667 <li>
653 <e>F</e> (fetch) The package requires that you download the source code 668 <e>F</e> (fetch) The package requires that you download the source code
654 manually (for instance due to licencing issues) 669 manually (for instance due to licencing issues)
655 </li> 670 </li>
659 </li> 674 </li>
660 <li> 675 <li>
661 <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
662 downgraded 677 downgraded
663 </li> 678 </li>
664 <li>
665 <e>U-</e> (slot warning) The package you have installed on your system
666 is listed as a package that can not coexist with a different version, but
667 your update does. The update will be installed and the older version will be
668 removed.
669 </li>
670</ul> 679</ul>
671 680
672<p> 681<p>
673In 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
674instead 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
675<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:
676</p> 687</p>
677 688
678<pre caption="Upgrading your entire system"> 689<pre caption="Upgrading your entire system, including all dependencies">
679# <i>emerge --update --upgradeonly world</i> 690# <i>emerge --update --deep world</i>
680</pre> 691</pre>
681 692
682<p> 693<p>
683Of 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
684perform the same actions for individual software packages. 695perform the same actions for individual software packages.
740 751
741</body> 752</body>
742</subsection> 753</subsection>
743</section> 754</section>
744<section> 755<section>
745<title>Software Availability</title> 756<title>Working with Masked Packages</title>
746<subsection> 757<subsection>
747<title>ARCH or not?</title> 758<title>ARCH or not?</title>
748<body> 759<body>
749 760
750<p> 761<p>
795Calculating dependencies 806Calculating dependencies
796!!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment> 807!!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment>
797</pre> 808</pre>
798 809
799<p> 810<p>
800A package can be masked due to two reasons: 811A package can be masked due to several reasons:
801</p> 812</p>
802 813
803<ol> 814<ol>
804 <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li> 815 <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li>
805 <li>The package is hard-masked explicitly</li> 816 <li>The package is hard-masked explicitly</li>
817 <li>The package isn't available for your ARCH entirely</li>
818 <li>The package is masked by your profile</li>
806</ol> 819</ol>
807 820
808<p> 821<p>
809If the package is masked because of the first reason, and you <e>really</e> want 822If the package is masked because of the first reason, and you <e>really</e>
810to install it (knowing that there <e>is</e> a reason why it isn't available in 823want to install it (knowing that there <e>is</e> a reason why it isn't
811<e>ARCH</e>), you can temporarily accept <e>~ARCH</e> packages: 824available in <e>ARCH</e>), you can accept the <e>~ARCH</e> version of any
825package by adding it to your <path>/etc/portage/package.keywords</path> file:
812</p> 826</p>
813 827
814<pre caption="Temporarily accepting ~ARCH packages"> 828<pre caption="Accepting the ~ARCH version of a package">
815# <i>ACCEPT_KEYWORDS="~x86" emerge gnumeric</i> 829<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
830# <i>mkdir /etc/portage</i>
831
832# <i>echo "app-office/gnumeric ~x86" &gt;&gt; /etc/portage/package.keywords</i>
833# <i>emerge gnumeric</i>
816</pre> 834</pre>
817 835
818<p> 836<p>
819A package is hardmasked if it is listed in 837A package is hardmasked if it is listed in
820<path>/usr/portage/profiles/package.mask</path>. If you read this file, you 838<path>/usr/portage/profiles/package.mask</path>. If you read this file, you
824"breaks other packages", or "badly needs testing"), create the 842"breaks other packages", or "badly needs testing"), create the
825<path>/etc/portage/package.unmask</path> file and list the package in it (use 843<path>/etc/portage/package.unmask</path> file and list the package in it (use
826the same format as is used in <path>/usr/portage/profiles/package.mask</path>). 844the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
827</p> 845</p>
828 846
847<pre caption="Unmasking a hard-masked application">
848<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
849# <i>mkdir /etc/portage</i>
850
851# <i>echo "=app-office/gnumeric-1.2.12" &gt;&gt; /etc/portage/package.unmask</i>
852</pre>
853
829<p> 854<p>
830Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as 855Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as
831all changes are undone the next time you update your Portage tree. If you want 856all changes are undone the next time you update your Portage tree.
857</p>
858
859<p>
860Sometimes you might want to hardmask a (collection of) package(s). This is the
861case when newer versions of an application don't support something you require
862or when these versions break something else in your environment.
863</p>
864
865<p>
832to hardmask a package create <path>/etc/portage/package.mask</path> and list the 866To hard-mask a package, create <path>/etc/portage/package.mask</path> and list the
833package in it (use the same format as mentioned above). 867package in it (use the same format as mentioned above).
834</p> 868</p>
835 869
836<!-- 870<pre caption="Hard-masking a package">
837<p> 871<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
838Another trick to circumvent the "masked package" problem is to install the 872# <i>mkdir /etc/portage</i>
839package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c> 873
840settings and the <path>package.mask</path> listing. 874# <i>echo "&gt;app-office/gnumeric-1.2.10" &gt;&gt; /etc/portage/package.mask</i>
841</p> 875</pre>
842
843<pre caption="Installing a package without checking for stadium / masking">
844# <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i>
845</pre>
846-->
847 876
848</body> 877</body>
849</subsection> 878</subsection>
850<subsection> 879<subsection>
851<title>Blocked Packages</title> 880<title>Blocked Packages</title>

Legend:
Removed from v.1.22  
changed lines
  Added in v.1.34

  ViewVC Help
Powered by ViewVC 1.1.20