/[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.35
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.35 2004/08/29 10:56:31 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>
751Gentoo 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
752<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.
753you 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.
754<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
755</p> 766flag. An explanation of the available flags is given in the next table.
756
757<p> 767</p>
758The <e>~ARCH</e> stadium means that the package works for the developer in 768
759charge of the package, but that the package hasn't been tested thoroughly enough 769<table>
760by the community to be placed in <e>ARCH</e>. <e>~ARCH</e> packages usually go 770<tr>
761to <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
762</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>
763 824
764<p> 825<p>
765Your 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
766the edge, don't mind having a broken package once in a while, know how to deal 827the edge, don't mind having a broken package once in a while, know how to deal
767with a broken system and you like submitting bugreports to <uri 828with a broken system and you like submitting bugreports to <uri
795Calculating dependencies 856Calculating dependencies
796!!! <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>
797</pre> 858</pre>
798 859
799<p> 860<p>
800A package can be masked due to two reasons: 861A package can be masked due to several reasons:
801</p> 862</p>
802 863
803<ol> 864<ol>
804 <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>
805 <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>
806</ol> 869</ol>
807 870
808<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>
809If 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>
810to 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
811<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
812</p> 902package by adding it to your <path>/etc/portage/package.keywords</path> file:
813
814<pre caption="Temporarily accepting ~ARCH packages">
815# <i>ACCEPT_KEYWORDS="~x86" emerge gnumeric</i>
816</pre>
817
818<p> 903</p>
819A 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
820<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
821will 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
822a 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
823possible 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",
824"breaks other packages", or "badly needs testing"), create the 945"breaks other packages", or "badly needs testing"), create the
825<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
826the 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>).
827</p> 948</p>
828 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
829<p> 957<p>
830Do <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
831all changes are undone the next time you update your Portage tree. If you want 959all changes are undone the next time you update your Portage tree.
960</p>
961
962<p>
963Sometimes you might want to hardmask a (collection of) package(s). This is the
964case when newer versions of an application don't support something you require
965or when these versions break something else in your environment.
966</p>
967
968<p>
832to hardmask a package create <path>/etc/portage/package.mask</path> and list the 969To hard-mask a package, create <path>/etc/portage/package.mask</path> and list
833package in it (use the same format as mentioned above). 970the package in it (use the same format as mentioned above).
834</p>
835
836<!--
837<p> 971</p>
838Another trick to circumvent the "masked package" problem is to install the 972
839package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c> 973<pre caption="Hard-masking a package">
840settings and the <path>package.mask</path> listing. 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
841</p> 980<p>
842 981When Portage tells you that it cannot install a package due to <b>profile</b> it
843<pre caption="Installing a package without checking for stadium / masking"> 982means that you are working with a certain profile that doesn't allow the package
844# <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i> 983to be installed. But what is this "profile"?
845</pre> 984</p>
846--> 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>
847 1004
848</body> 1005</body>
849</subsection> 1006</subsection>
850<subsection> 1007<subsection>
851<title>Blocked Packages</title> 1008<title>Blocked Packages</title>

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

  ViewVC Help
Powered by ViewVC 1.1.20