/[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.13 Revision 1.32
1<?xml version='1.0' encoding='UTF-8'?>
2<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
1<!-- 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 -->
2<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> 5<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3 6
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 $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.32 2004/08/21 18:08:12 swift Exp $ -->
5 8
6<sections> 9<sections>
7<section> 10<section>
8<title>Obtaining Package Information</title> 11<title>Obtaining Package Information</title>
9<subsection> 12<subsection>
87dev-lisp/ gnome-extra/ net-p2p/ 90dev-lisp/ gnome-extra/ net-p2p/
88</pre> 91</pre>
89 92
90<p> 93<p>
91As 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
92the <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
93reside. Take a look at, for instance, <path>app-office</path>: 96instance, <path>app-office</path>:
94</p> 97</p>
95 98
96<pre caption="Viewing a category"> 99<pre caption="Viewing a category">
97# <i>cd app-office; ls --classify</i> 100# <i>cd app-office; ls --classify</i>
98abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x 101abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x
114ChangeLog 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
115Manifest 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
116</pre> 119</pre>
117 120
118<p> 121<p>
119Remember 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
120the example directory four of such ebuilds are stored. Their naming is 123which contains all the necessary information about a specific version of a
121almost identical: they only differ in the version name. 124package. The naming for the ebuilds is almost identical; they only differ in
125the version name.
122You 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
123will 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
124using Gentoo. 128using Gentoo.
125</p> 129</p>
126 130
127<p> 131<p>
128The other files are the <path>ChangeLog</path> (which contains a listing of all 132The other files are the <path>ChangeLog</path> (which contains a listing of all
129the changes done to the ebuilds), <path>Manifest</path> (which contains the 133the changes done to the ebuilds), <path>Manifest</path> (which contains the
130checksums and permissions of all the files in the directory) and 134checksums and filesizes of all the files in the directory) and
131<path>metadata.xml</path> (which contains more information about the package, 135<path>metadata.xml</path> (which contains more information about the package,
132such 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
133extensive description). 137extensive description).
134</p> 138</p>
135 139
136<p> 140<p>
137Inside 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
138Portage: digests (checksums and permissions of the files needed by a single 142Portage: digests (names, sizes and checksums of the files needed by a single
139version of the package), patches, example configuration files, etc. 143version of the package), patches, example configuration files, etc.
140</p> 144</p>
141 145
142<pre caption="Viewing the extra files"> 146<pre caption="Viewing the extra files">
143# <i>cd files; ls --classify</i> 147# <i>cd files; ls --classify</i>
150nptl.patch 154nptl.patch
151</pre> 155</pre>
152 156
153<p> 157<p>
154If 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
155will 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
156those later in this chapter. 160those later in this chapter.
157</p> 161</p>
158 162
159</body> 163</body>
160</subsection> 164</subsection>
224 228
225<p> 229<p>
226You 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
227install 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
228precompiled packages) available. It therefore checks the contents of 232precompiled packages) available. It therefore checks the contents of
229<path>/usr/portage/distfiles</path> (for sourcecode) or 233<path>/usr/portage/distfiles</path> 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 234necessary files are already available. If not, it downloads the necessary files
232and places them in those directories. 235and places them in thay directory.
233</p> 236</p>
234
235<note>
236Searching the Portage Tree, especially when using <c>--searchdesc</c>, is very
237time 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
239Other Tools</uri>.
240</note>
241 237
242</body> 238</body>
243</subsection> 239</subsection>
244<subsection> 240<subsection>
245<title>Viewing the ChangeLog</title> 241<title>Viewing the ChangeLog</title>
246<body> 242<body>
247 243
248<p> 244<p>
249While browsing through the Portage Tree, you saw that there was a ChangeLog for 245While browsing through the Portage Tree, you saw that there was a ChangeLog for
250each package. You can view this ChangeLog with <c>emerge</c> too. Use the 246each package. You can view the ChangeLog entries between the available version
247and the installed version with <c>emerge</c> too. Use the
251<c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we 248<c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we
252will view the ChangeLog entries for <c>gnumeric</c>: 249will view the ChangeLog entries for <c>gnumeric</c>:
253</p> 250</p>
254 251
255<pre caption="Viewing the ChangeLog entries for gnumeric"> 252<pre caption="Viewing the ChangeLog entries for gnumeric">
256# <i>emerge --pretend --changelog gnumeric</i> 253# <i>emerge --pretend --changelog gnumeric</i>
254<comment>(Some output removed to improve readability)</comment>
255*gnumeric-1.2.2
256
257 27 Nov 2003; foser &lt;foser@gentoo.org&gt; gnumeric-1.2.2.ebuild :
258 New release, requested in #34492
259 updated deps
260
261 12 Nov 2003; Jason Wever &lt;weeve@gentoo.org&gt; gnumeric-1.2.0.ebuild:
262 Marked stable on sparc, fixes bug #32405.
263
264 14 Oct 2003; Jason Wever &lt;weeve@gentoo.org&gt; gnumeric-1.0.8.ebuild:
265 Added ~sparc keyword. Fixes bug #31150.
257</pre> 266</pre>
258 267
259</body> 268</body>
260</subsection> 269</subsection>
261</section> 270</section>
298# <i>emerge --usepkg mirrorselect</i> 307# <i>emerge --usepkg mirrorselect</i>
299</pre> 308</pre>
300 309
301<p> 310<p>
302Now run <c>mirrorselect</c> to automatically select mirrors for you (it will 311Now run <c>mirrorselect</c> to automatically select mirrors for you (it will
303also setup Portage to use a mirror for the sourcecode): 312also setup Portage to use a mirror for the source code):
304</p> 313</p>
305 314
306<pre caption="Running mirrorselect"> 315<pre caption="Running mirrorselect">
307# <i>mirrorselect -a -s3</i> 316# <i>mirrorselect -a -s3</i>
308</pre> 317</pre>
341<title>Building or Prebuilt?</title> 350<title>Building or Prebuilt?</title>
342<body> 351<body>
343 352
344<p> 353<p>
345Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to 354Gentoo 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 355install such an ebuild, you can choose between <e>building</e> the package and
347using a <e>prebuilt</e> package. But what are the advantages/disadvantages of 356using a <e>prebuilt</e> package. But what are the advantages/disadvantages of
348both approaches, and can they be used next to each other? 357both approaches, and can they be used next to each other?
349</p> 358</p>
350 359
351<p> 360<p>
364<c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables. 373<c>CFLAGS</c> &amp; <c>CXXFLAGS</c> variables.
365</p> 374</p>
366 375
367<p> 376<p>
368As previously stated, prebuilt packages are stored in the 377As previously stated, prebuilt packages are stored in the
369<path>/usr/portage/packages/All</path> directory, while the sourcecode of the 378<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 379packages is placed in <path>/usr/portage/distfiles</path>. If you have finished
371installing a package you can remove the package or sourcecode from the 380installing a package you can remove the package or source code from the
372respective directory. However, you might want to keep the package/sourcecode of 381respective 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 382the latest version, just in case you want to reinstall the package (so you don't
374have to redownload it). 383have to redownload it).
375</p> 384</p>
376 385
377</body> 386</body>
391<pre caption="Building gnumeric"> 400<pre caption="Building gnumeric">
392# <i>emerge gnumeric</i> 401# <i>emerge gnumeric</i>
393</pre> 402</pre>
394 403
395<p> 404<p>
396This will download the sourcecode for you and unpacks, compiles and installs the 405This 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 406the 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 407If you want to see what dependencies will be installed with it, use the
399<c>--pretend</c> option (<c>-p</c> in short): 408<c>--pretend</c> option (<c>-p</c> in short):
400</p> 409</p>
401 410
402<pre caption="Pretending to build gnumeric"> 411<pre caption="Pretending to build gnumeric">
403# <i>emerge --pretend gnumeric</i> 412# <i>emerge --pretend gnumeric</i>
404</pre> 413</pre>
405 414
406<p> 415<p>
407If you want to download the sourcecode of the package and its dependencies, 416If 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 417but don't want to build the package, use the <c>--fetchonly</c> option
409(<c>-f</c> in short): 418(<c>-f</c> in short):
410</p> 419</p>
411 420
412<pre caption="Fetching sources for gnumeric"> 421<pre caption="Fetching sources for gnumeric">
467If 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
468<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>
469variable declared in <path>/etc/make.conf</path>. 478variable declared in <path>/etc/make.conf</path>.
470</p> 479</p>
471 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
472<p> 486<p>
473To 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
474your system already, use <c>--getbinpkg</c> (<c>-g</c> in short): 488your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
475</p> 489</p>
476 490
532<p> 546<p>
533For 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
534package 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
535is 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
536any 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
537all listed packages. However, <c>glibc</c> will <e>not</e> be listed as 551all listed packages.
538dependency for safety reasons.
539</p> 552</p>
540 553
541<pre caption="Show all dependencies of gnumeric"> 554<pre caption="Show all dependencies of gnumeric">
542# <i>emerge --emptytree --pretend gnumeric</i> 555# <i>emerge --emptytree --pretend gnumeric</i>
543</pre> 556</pre>
551<pre caption="Installing gnumeric without taking care of the dependencies"> 564<pre caption="Installing gnumeric without taking care of the dependencies">
552# <i>emerge --nodeps gnumeric</i> 565# <i>emerge --nodeps gnumeric</i>
553</pre> 566</pre>
554 567
555<p> 568<p>
556To opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage 569The 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: 570install all dependencies of a given package, but not the package itself:
558</p> 571</p>
559 572
560<pre caption="Installing the dependencies of gnumeric"> 573<pre caption="Installing the dependencies of gnumeric">
561# <i>emerge --onlydeps gnumeric</i> 574# <i>emerge --onlydeps gnumeric</i>
627 <li> 640 <li>
628 <e>N</e> (new) The package is new to your system and will be emerged for the 641 <e>N</e> (new) The package is new to your system and will be emerged for the
629 first time 642 first time
630 </li> 643 </li>
631 <li> 644 <li>
632 <e>R</e> (reemerge) The package isn't new, but needs to be reemerged 645 <e>R</e> (replace) The package isn't new, but will be reemerged
633 </li> 646 </li>
634 <li> 647 <li>
635 <e>F</e> (fetch) The package requires that you download the sourcecode 648 <e>F</e> (fetch) The package requires that you download the source code
636 manually (for instance due to licencing issues) 649 manually (for instance due to licencing issues)
637 </li> 650 </li>
638 <li> 651 <li>
639 <e>U</e> (update) The package already exists on your system but will be 652 <e>U</e> (update) The package already exists on your system but will be
640 upgraded 653 upgraded
641 </li> 654 </li>
642 <li> 655 <li>
643 <e>UD</e> (downgrade) The package already exists on your system but will be 656 <e>UD</e> (downgrade) The package already exists on your system but will be
644 downgraded 657 downgraded
645 </li> 658 </li>
646 <li>
647 <e>U-</e> (slot warning) The package you have installed on your system
648 is listed as a package that can not coexist with a different version, but
649 your update does. The update will be installed and the older version will be
650 removed.
651 </li>
652</ul> 659</ul>
653 660
654<p> 661<p>
655In certain cases, an update may mean a downgrade (i.e. install an older version 662We have mentioned that the <e>world</e> file doesn't contain dependencies. When
656instead of a newer version). If you don't want this to happen, use the 663you run <c>emerge --update world</c> only the packages mentioned in the
657<c>--upgradeonly</c> option (<c>-U</c> in short): 664<e>world</e> file and it's immediate dependencies are checked and, if necessary,
665upgraded. If you want <c>emerge</c> to check <e>all</e> the dependencies
666(including the dependencies of the dependencies), add the <c>--deep</c> flag:
658</p> 667</p>
659 668
660<pre caption="Upgrading your entire system"> 669<pre caption="Upgrading your entire system, including all dependencies">
661# <i>emerge --update --upgradeonly world</i> 670# <i>emerge --update --deep world</i>
662</pre> 671</pre>
663 672
664<p> 673<p>
665Of course, we are talking here about <e>system</e> and <e>world</e>, but you can 674Of course, we are talking here about <e>system</e> and <e>world</e>, but you can
666perform the same actions for individual software packages. 675perform the same actions for individual software packages.
713 </li> 722 </li>
714 <li> 723 <li>
715 <c>!empty</c> : The listed directory is not empty 724 <c>!empty</c> : The listed directory is not empty
716 </li> 725 </li>
717 <li> 726 <li>
718 <c>cfgpro</c> : Another already installed package claims to own this file 727 <c>cfgpro</c> : This file is located inside a protected directory and will
728 not be touched for safety
719 </li> 729 </li>
720</ul> 730</ul>
721 731
722</body> 732</body>
723</subsection> 733</subsection>
724</section> 734</section>
725<section> 735<section>
726<title>Software Availability</title> 736<title>Working with Masked Packages</title>
727<subsection> 737<subsection>
728<title>ARCH or not?</title> 738<title>ARCH or not?</title>
729<body> 739<body>
730 740
731<p> 741<p>
742to <e>ARCH</e> after being bugfree for a sufficient amount of time. 752to <e>ARCH</e> after being bugfree for a sufficient amount of time.
743</p> 753</p>
744 754
745<p> 755<p>
746Your system will use <e>ARCH</e> packages per default. If you want to live on 756Your system will use <e>ARCH</e> packages per default. If you want to live on
747the edge, don't mind having a broken package once in a while, and you like 757the edge, don't mind having a broken package once in a while, know how to deal
748submitting bugreports to <uri 758with a broken system and you like submitting bugreports to <uri
749link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use 759link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use
750<e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system, 760<e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system,
751edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that 761edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that
752it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.). 762it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).
753</p> 763</p>
754 764
755<p> 765<p>
766Note though that it is far from trivial (if even impossible) to go back to
767<e>ARCH</e> from <e>~ARCH</e>.
768</p>
769
770<p>
756If you want to update your system now, you will notice that <e>a lot</e> of 771If you want to update your system now, you will notice that <e>a lot</e> of
757packages will be updated! 772packages will be updated!
758</p> 773</p>
759 774
760</body> 775</body>
771Calculating dependencies 786Calculating dependencies
772!!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment> 787!!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment>
773</pre> 788</pre>
774 789
775<p> 790<p>
776A package can be masked due to two reasons: 791A package can be masked due to several reasons:
777</p> 792</p>
778 793
779<ol> 794<ol>
780 <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li> 795 <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li>
781 <li>The package is hard-masked explicitly</li> 796 <li>The package is hard-masked explicitly</li>
797 <li>The package isn't available for your ARCH entirely</li>
798 <li>The package is masked by your profile</li>
782</ol> 799</ol>
783 800
784<p> 801<p>
785If the package is masked because of the first reason, and you <e>really</e> want 802If the package is masked because of the first reason, and you <e>really</e>
786to install it (knowing that there <e>is</e> a reason why it isn't available in 803want to install it (knowing that there <e>is</e> a reason why it isn't
787<e>ARCH</e>), you can temporarily accept <e>~ARCH</e> packages: 804available in <e>ARCH</e>), you can accept the <e>~ARCH</e> version of any
805package by adding it to your <path>/etc/portage/package.keywords</path> file:
788</p> 806</p>
789 807
790<pre caption="Temporarily accepting ~ARCH packages"> 808<pre caption="Accepting the ~ARCH version of a package">
791# <i>ACCEPT_KEYWORDS="~x86" emerge gnumeric</i> 809<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
810# <i>mkdir /etc/portage</i>
811
812# <i>echo "app-office/gnumeric ~x86" &gt;&gt; /etc/portage/package.keywords</i>
813# <i>emerge gnumeric</i>
792</pre> 814</pre>
793 815
794<p> 816<p>
795A package is hardmasked if it is listed in 817A package is hardmasked if it is listed in
796<path>/usr/portage/profiles/package.mask</path>. If you read this file, you 818<path>/usr/portage/profiles/package.mask</path>. If you read this file, you
800"breaks other packages", or "badly needs testing"), create the 822"breaks other packages", or "badly needs testing"), create the
801<path>/etc/portage/package.unmask</path> file and list the package in it (use 823<path>/etc/portage/package.unmask</path> file and list the package in it (use
802the same format as is used in <path>/usr/portage/profiles/package.mask</path>). 824the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
803</p> 825</p>
804 826
827<pre caption="Unmasking a hard-masked application">
828<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
829# <i>mkdir /etc/portage</i>
830
831# <i>echo "=app-office/gnumeric-1.2.12" &gt;&gt; /etc/portage/package.unmask</i>
832</pre>
833
805<p> 834<p>
806Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as 835Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as
807all changes are undone the next time you update your Portage tree. 836all changes are undone the next time you update your Portage tree.
808</p>
809
810<p> 837</p>
811Another trick to circumvent the "masked package" problem is to install the 838
812package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c>
813settings and the <path>package.mask</path> listing.
814</p> 839<p>
840Sometimes you might want to hardmask a (collection of) package(s). This is the
841case when newer versions of an application don't support something you require
842or when these versions break something else in your environment.
843</p>
815 844
816<pre caption="Installing a package without checking for stadium / masking"> 845<p>
817# <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i> 846To hard-mask a package, create <path>/etc/portage/package.mask</path> and list the
847package in it (use the same format as mentioned above).
848</p>
849
850<pre caption="Hard-masking a package">
851<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
852# <i>mkdir /etc/portage</i>
853
854# <i>echo "&gt;app-office/gnumeric-1.2.10" &gt;&gt; /etc/portage/package.mask</i>
818</pre> 855</pre>
819 856
820</body> 857</body>
821</subsection> 858</subsection>
822<subsection> 859<subsection>

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

  ViewVC Help
Powered by ViewVC 1.1.20