/[gentoo]/xml/htdocs/doc/en/handbook/hb-working-portage.xml

Diff of /xml/htdocs/doc/en/handbook/hb-working-portage.xml

Parent Directory | Revision Log | View Patch Patch

Revision 1.13		Revision 1.38
		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.38 2004/10/02 21:53:56 cam 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>
…		…
87	dev-lisp/ gnome-extra/ net-p2p/	90	dev-lisp/ gnome-extra/ net-p2p/
88	</pre>	91	</pre>
89		92
90	<p>	93	<p>
91	As you can see, the Portage tree has several subdirectories. Most of them are	94	As you can see, the Portage tree has several subdirectories. Most of them are
92	the <e>categories</e> in which the Gentoo packages, called <e>ebuilds</e>,	95	the <e>categories</e> in which the Gentoo packages reside. Take a look at, for
93	reside. Take a look at, for instance, <path>app-office</path>:	96	instance, <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>
98	abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x	101	abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x
…		…
114	ChangeLog files/ openoffice-1.0.3-r1.ebuild openoffice-1.1.0-r2.ebuild	117	ChangeLog files/ openoffice-1.0.3-r1.ebuild openoffice-1.1.0-r2.ebuild
115	Manifest metadata.xml openoffice-1.1.0-r1.ebuild openoffice-1.1.0.ebuild	118	Manifest metadata.xml openoffice-1.1.0-r1.ebuild openoffice-1.1.0.ebuild
116	</pre>	119	</pre>
117		120
118	<p>	121	<p>
119	Remember that we told you that a Gentoo package is called an ebuild? Well, in	122	In the example directory, four ebuilds are stored. An <e>ebuild</e> is a script
120	the example directory four of such ebuilds are stored. Their naming is	123	which contains all the necessary information about a specific version of a
121	almost identical: they only differ in the version name.	124	package. The naming for the ebuilds is almost identical; they only differ in
		125	the version name.
122	You are free to view the contents of such a package: they are plain scripts. We	126	You are free to view the contents of such an ebuild: they are plain scripts. We
123	will not discuss it right now as it isn't important to know if you plan on just	127	will not discuss it right now as it isn't important to know if you plan on just
124	using Gentoo.	128	using Gentoo.
125	</p>	129	</p>
126		130
127	<p>	131	<p>
128	The other files are the <path>ChangeLog</path> (which contains a listing of all	132	The other files are the <path>ChangeLog</path> (which contains a listing of all
129	the changes done to the ebuilds), <path>Manifest</path> (which contains the	133	the changes done to the ebuilds), <path>Manifest</path> (which contains the
130	checksums and permissions of all the files in the directory) and	134	checksums 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,
132	such as the responsible development group -- called <e>herd</e> -- and a more	136	such as the responsible development group -- called <e>herd</e> -- and a more
133	extensive description).	137	extensive description).
134	</p>	138	</p>
135		139
136	<p>	140	<p>
137	Inside the <path>files</path> directory you will find extra files, needed by	141	Inside the <path>files</path> directory, you will find extra files, needed by
138	Portage: digests (checksums and permissions of the files needed by a single	142	Portage: digests (names, sizes and checksums of the files needed by a single
139	version of the package), patches, example configuration files, etc.	143	version 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>
…		…
150	nptl.patch	154	nptl.patch
151	</pre>	155	</pre>
152		156
153	<p>	157	<p>
154	If you go back to the root of the Portage tree (<path>/usr/portage</path>) you	158	If you go back to the root of the Portage tree (<path>/usr/portage</path>) you
155	will notice that there are other, non-category directories too. We will discuss	159	will notice that there are other, non-category directories, too. We will discuss
156	those later in this chapter.	160	those later in this chapter.
157	</p>	161	</p>
158		162
159	</body>	163	</body>
160	</subsection>	164	</subsection>
…		…
217	</pre>	221	</pre>
218		222
219	<p>	223	<p>
220	As you can see, the output of <c>emerge</c> informs you about the category and	224	As you can see, the output of <c>emerge</c> informs you about the category and
221	name of the package, the available version, the currently installed version,	225	name of the package, the available version, the currently installed version,
222	the size of the downloaded files, the homepage and the small description.	226	the size of the downloaded files, the homepage and the short description.
223	</p>
224
225	<p>	227	</p>
		228
		229	<p>
226	You see something new? Yes, <e>downloaded files</e>. When you tell Portage to	230	Do you see something else? Yes, <e>downloaded files</e>. When you tell Portage
227	install a package, it of course needs to have the necessary sources (or	231	to install a package, it of course needs to have the necessary sources (or
228	precompiled packages) available. It therefore checks the contents of	232	precompiled 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 necessary files are already
230	<path>/usr/portage/packages/All</path> (for precompiled packages) to see if the	234	available. If not, it downloads the necessary files and places them in that
231	necessary files are already available. If not, it downloads the necessary files	235	directory.
232	and places them in those directories.
233	</p>	236	</p>
234
235	<note>
236	Searching the Portage Tree, especially when using <c>--searchdesc</c>, is very
237	time consuming. There are other, more performant tools available. We will
238	describe those in the chapter on <uri link="?part=2&chap=7">Gentoolkit and
239	Other 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>
249	While browsing through the Portage Tree, you saw that there was a ChangeLog for	245	While browsing through the Portage Tree, you saw that there was a ChangeLog for
250	each package. You can view this ChangeLog with <c>emerge</c> too. Use the	246	each package. You can view the ChangeLog entries between the available version
		247	and 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
252	will view the ChangeLog entries for <c>gnumeric</c>:	249	will 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 <foser@gentoo.org> gnumeric-1.2.2.ebuild :
		258	New release, requested in #34492
		259	updated deps
		260
		261	12 Nov 2003; Jason Wever <weeve@gentoo.org> gnumeric-1.2.0.ebuild:
		262	Marked stable on sparc, fixes bug #32405.
		263
		264	14 Oct 2003; Jason Wever <weeve@gentoo.org> 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>
…		…
284	<subsection>	293	<subsection>
285	<title>Selecting a Mirror for rsync</title>	294	<title>Selecting a Mirror for rsync</title>
286	<body>	295	<body>
287		296
288	<p>	297	<p>
289	It is adviseable to first select a fast <uri	298	It is advisable to first select a fast <uri
290	link="/main/en/mirrors.xml">mirror</uri> close to you. You can do this manually	299	link="/main/en/mirrors.xml">mirror</uri> close to you. You can do this manually
291	(by setting the <c>SYNC</c> variable in <path>/etc/make.conf</path>) or use	300	(by setting the <c>SYNC</c> variable in <path>/etc/make.conf</path>) or use
292	<c>mirrorselect</c> to do this for you automatically. As the <c>SYNC</c>	301	<c>mirrorselect</c> to do this for you automatically. As the <c>SYNC</c>
293	variable will be discussed later on, we will focus on using <c>mirrorselect</c>.	302	variable will be discussed later on, we will focus on using <c>mirrorselect</c>.
294	First install <c>mirrorselect</c> by emerging it:	303	First install <c>mirrorselect</c> by emerging it:
…		…
298	# <i>emerge --usepkg mirrorselect</i>	307	# <i>emerge --usepkg mirrorselect</i>
299	</pre>	308	</pre>
300		309
301	<p>	310	<p>
302	Now run <c>mirrorselect</c> to automatically select mirrors for you (it will	311	Now run <c>mirrorselect</c> to automatically select mirrors for you (it will
303	also setup Portage to use a mirror for the sourcecode):	312	also 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>
…		…
312	<subsection>	321	<subsection>
313	<title>Updating Portage</title>	322	<title>Updating Portage</title>
314	<body>	323	<body>
315		324
316	<p>	325	<p>
317	To update Portage using rsync, simply run <c>emerge sync</c>:	326	To update Portage using rsync, simply run <c>emerge --sync</c>:
318	</p>	327	</p>
319		328
320	<pre caption="Updating Portage using emerge sync">	329	<pre caption="Updating Portage using emerge --sync">
321	# <i>emerge sync</i>	330	# <i>emerge --sync</i>
322	</pre>	331	</pre>
323		332
324	<p>	333	<p>
325	If this fails (due to network problems, or a firewall), you can try using	334	If this fails (due to network problems, or a firewall), you can try using
326	<c>emerge-webrsync</c> which will download a Portage Tree snapshot using	335	<c>emerge-webrsync</c> which will download a Portage Tree snapshot using
…		…
341	<title>Building or Prebuilt?</title>	350	<title>Building or Prebuilt?</title>
342	<body>	351	<body>
343		352
344	<p>	353	<p>
345	Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to	354	Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to
346	install such an ebuild, you can choose between <e>building</e> the package, or	355	install such an ebuild, you can choose between <e>building</e> the package and
347	using a <e>prebuilt</e> package. But what are the advantages/disadvantages of	356	using a <e>prebuilt</e> package. But what are the advantages/disadvantages of
348	both approaches, and can they be used next to each other?	357	both approaches, and can they be used alongside each other?
349	</p>	358	</p>
350		359
351	<p>	360	<p>
352	As you probably have guessed, building packages takes a lot of time (especially	361	As you probably have guessed, building packages takes a lot of time (especially
353	if you have little resources or want to build big packages, such as <uri	362	if you have little resources or want to build big packages, such as <uri
…		…
364	<c>CFLAGS</c> & <c>CXXFLAGS</c> variables.	373	<c>CFLAGS</c> & <c>CXXFLAGS</c> variables.
365	</p>	374	</p>
366		375
367	<p>	376	<p>
368	As previously stated, prebuilt packages are stored in the	377	As 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
370	packages are placed in <path>/usr/portage/distfiles</path>. If you have finished	379	packages is placed in <path>/usr/portage/distfiles</path>. If you have finished
371	installing a package you can remove the package or sourcecode from the	380	installing a package you can remove the package or source code from the
372	respective directory. However, you might want to keep the package/sourcecode of	381	respective directory. However, you might want to keep the package/source code of
373	the latest version, just in case you want to reinstall the package (so you don't	382	the latest version, just in case you want to reinstall the package (so you don't
374	have to redownload it).	383	have 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>
396	This will download the sourcecode for you and unpacks, compiles and installs the	405	This will download the source code for you and unpacks, compiles and installs
397	package on your system. It will also do the same for all the dependencies. If	406	the package on your system. It will also do the same for all the dependencies.
398	you want to see what dependencies will be installed with it, use the	407	If 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>
407	If you want to download the sourcecode of the package and its dependencies,	416	If you want to download the source code of the package and its dependencies,
408	but don't want to build the package, use the <c>--fetchonly</c> option	417	but 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">
…		…
431	<pre caption="Installing a specific gnumeric version">	440	<pre caption="Installing a specific gnumeric version">
432	# <i>emerge "<gnumeric-1.2"</i>	441	# <i>emerge "<gnumeric-1.2"</i>
433	</pre>	442	</pre>
434		443
435	<p>	444	<p>
436	Other possibilities are of course ">" (later version) and "=" (the exact	445	Other possibilities are of course ">" (later version), "=" (the exact
437	version).	446	version) and the combinations "<=" and ">=".
438	</p>	447	</p>
439		448
440	</body>	449	</body>
441	</subsection>	450	</subsection>
442	<subsection>	451	<subsection>
…		…
467	If you don't have the prebuilt package on your system yet, you can have	476	If 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>
469	variable declared in <path>/etc/make.conf</path>.	478	variable declared in <path>/etc/make.conf</path>.
470	</p>	479	</p>
471		480
		481	<note>
		482	Gentoo does not have any server or mirror containing such prebuilt packages.
		483	Portage has been extended with this feature to fullfil the community request.
		484	</note>
		485
472	<p>	486	<p>
473	To download the binary package in case this package doesn't exist on	487	To download the binary package in case this package doesn't exist on
474	your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):	488	your system already, use <c>--getbinpkg</c> (<c>-g</c> in short):
475	</p>	489	</p>
476		490
…		…
509	<pre caption="Installing a specific gnumeric version">	523	<pre caption="Installing a specific gnumeric version">
510	# <i>emerge --usepkg "<gnumeric-1.2"</i>	524	# <i>emerge --usepkg "<gnumeric-1.2"</i>
511	</pre>	525	</pre>
512		526
513	<p>	527	<p>
514	Other possibilities are of course ">" (later version) and "=" (the exact	528	Other possibilities are of course ">" (later version), "=" (the exact
515	version).	529	version) and the combinations "<=" and ">=".
516	</p>	530	</p>
517		531
518		532
519	</body>	533	</body>
520	</subsection>	534	</subsection>
521	<subsection>	535	<subsection>
522	<title>Working with Dependencies</title>	536	<title>Working with Dependencies</title>
523	<body>	537	<body>
524		538
525	<p>	539	<p>
526	Portage has an extensive support for dependency handling. Although you usually	540	Portage has extensive support for dependency handling. Although you usually
527	don't need to even think about this (as dependencies are automatically handled	541	don't need to even think about this (as dependencies are automatically handled
528	by Portage) some users might want to know how you can work with <c>emerge</c>	542	by Portage) some users might want to know how you can work with <c>emerge</c>
529	and dependencies.	543	and dependencies.
530	</p>	544	</p>
531		545
532	<p>	546	<p>
533	For instance, if you want Portage to pretend that none of the dependencies of a	547	For instance, if you want Portage to pretend that none of the dependencies of a
534	package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This	548	package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This
535	is useful with <c>--pretend</c> to display a complete tree of dependencies for	549	is useful with <c>--pretend</c> to display a complete tree of dependencies for
536	any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile	550	any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile
537	all listed packages. However, <c>glibc</c> will <e>not</e> be listed as	551	all listed packages.
538	dependency 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>
544		557
545	<p>	558	<p>
546	Another argument is <c>--nodeps</c>, which will ask Portage to try install the	559	Another argument is <c>--nodeps</c>, which will ask Portage to try install the
547	given package without taking care of the dependencies. It is trivial that this	560	given package without taking care of the dependencies. This can all too often
548	can lead to failures.	561	lead to failures.
549	</p>	562	</p>
550		563
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>
556	To opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage	569	The opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage
557	install all dependencies of a given package, but not the package itself:	570	install 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>
		575	</pre>
		576
		577	<p>
		578	When you uninstall software Portage will not automatically unmerge the
		579	dependencies that aren't needed anymore. If you want to "clean" your system from
		580	those orphaned dependencies, you can use <c>emerge depclean</c>. This will
		581	search for all installed software that you haven't installed explicitly and that
		582	isn't a dependency of software that you have installed explicitly.
		583	</p>
		584
		585	<warn>
		586	Using depclean can seriously impair your system. Use with caution and
		587	double-check the list of dependencies that Portage wants to remove before you go
		588	ahead!
		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>
562	</pre>	595	</pre>
563		596
564	</body>	597	</body>
565	</subsection>	598	</subsection>
566	<subsection>	599	<subsection>
…		…
627	<li>	660	<li>
628	<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
629	first time	662	first time
630	</li>	663	</li>
631	<li>	664	<li>
632	<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
633	</li>
634	<li>	666	</li>
		667	<li>
635	<e>F</e> (fetch) The package requires that you download the sourcecode	668	<e>F</e> (fetch) The package requires that you download the source code
636	manually (for instance due to licencing issues)	669	manually (for instance due to licencing issues)
637	</li>	670	</li>
638	<li>	671	<li>
639	<e>U</e> (update) The package already exists on your system but will be	672	<e>U</e> (update) The package already exists on your system but will be
640	upgraded	673	upgraded
641	</li>	674	</li>
642	<li>	675	<li>
643	<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
644	downgraded	677	downgraded
645	</li>	678	</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>	679	</ul>
653		680
654	<p>	681	<p>
655	In certain cases, an update may mean a downgrade (i.e. install an older version	682	We have mentioned that the <e>world</e> file doesn't contain dependencies. When
656	instead of a newer version). If you don't want this to happen, use the	683	you run <c>emerge --update world</c> only the packages mentioned in the
657	<c>--upgradeonly</c> option (<c>-U</c> in short):	684	<e>world</e> file and it's immediate dependencies are checked and, if necessary,
		685	upgraded. 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:
658	</p>	687	</p>
659		688
660	<pre caption="Upgrading your entire system">	689	<pre caption="Upgrading your entire system, including all dependencies">
661	# <i>emerge --update --upgradeonly world</i>	690	# <i>emerge --update --deep world</i>
662	</pre>	691	</pre>
663		692
664	<p>	693	<p>
665	Of course, we are talking here about <e>system</e> and <e>world</e>, but you can	694	Of course, we are talking here about <e>system</e> and <e>world</e>, but you can
666	perform the same actions for individual software packages.	695	perform the same actions for individual software packages.
…		…
713	</li>	742	</li>
714	<li>	743	<li>
715	<c>!empty</c> : The listed directory is not empty	744	<c>!empty</c> : The listed directory is not empty
716	</li>	745	</li>
717	<li>	746	<li>
718	<c>cfgpro</c> : Another already installed package claims to own this file	747	<c>cfgpro</c> : This file is located inside a protected directory and will
		748	not be touched for safety
719	</li>	749	</li>
720	</ul>	750	</ul>
721		751
722	</body>	752	</body>
723	</subsection>	753	</subsection>
724	</section>	754	</section>
725	<section>	755	<section>
726	<title>Software Availability</title>	756	<title>Working with Masked Packages</title>
727	<subsection>	757	<subsection>
728	<title>ARCH or not?</title>	758	<title>ARCH or not?</title>
729	<body>	759	<body>
730		760
731	<p>	761	<p>
732	Gentoo places its packages in two possible stadia called <e>ARCH</e> and	762	When a Gentoo developer puts an ebuild online it informs Portage how to treat
733	<e>~ARCH</e>. Don't take this literally: the stadia depend on the architecture	763	the package depending on the architecture and stability of the software title.
734	you are using. In other words, for x86-based systems you have <e>x86</e> and	764	He does so by defining a variable called <c>KEYWORDS</c> inside the ebuild.
735	<e>~x86</e>, for ppc-based systems you have <e>ppc</e> and <e>~ppc</e> etc.	765	This variable contains one or more architectures and marks them with a special
736	</p>	766	flag. An explanation of the available flags is given in the next table.
737
738	<p>	767	</p>
739	The <e>~ARCH</e> stadium means that the package works for the developer in	768
740	charge of the package, but that the package hasn't been tested thoroughly enough	769	<table>
741	by the community to be placed in <e>ARCH</e>. <e>~ARCH</e> packages usually go	770	<tr>
742	to <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
743	</p>	795	<p>
		796	Let's take a look at an example:
		797	</p>
		798
		799	<pre caption="Example KEYWORDS setting">
		800	KEYWORDS="x86 -sparc ~alpha ~ppc"
		801	</pre>
		802
		803	<p>
		804	This 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>
744		824
745	<p>	825	<p>
746	Your system will use <e>ARCH</e> packages per default. If you want to live on	826	Your system will use <e>ARCH</e> packages per default. If you want to live on
747	the edge, don't mind having a broken package once in a while, and you like	827	the edge, don't mind having a broken package once in a while, know how to deal
748	submitting bugreports to <uri	828	with a broken system and you like submitting bugreports to <uri
749	link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use	829	link="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,	830	<e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system,
751	edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that	831	edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that
752	it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).	832	it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).
753	</p>	833	</p>
754		834
755	<p>	835	<p>
		836	Note though that it is far from simple (or even impossible) to go back to
		837	<e>ARCH</e> from <e>~ARCH</e>.
		838	</p>
		839
		840	<p>
756	If you want to update your system now, you will notice that <e>a lot</e> of	841	If you want to update your system now, you will notice that <e>a lot</e> of
757	packages will be updated!	842	packages will be updated!
758	</p>	843	</p>
759		844
760	</body>	845	</body>
…		…
771	Calculating dependencies	856	Calculating dependencies
772	!!! <comment>all ebuilds that could satisfy </comment><your package><comment> have been masked.</comment>	857	!!! <comment>all ebuilds that could satisfy </comment><your package><comment> have been masked.</comment>
773	</pre>	858	</pre>
774		859
775	<p>	860	<p>
776	A package can be masked due to two reasons:	861	A package can be masked due to several reasons:
777	</p>	862	</p>
778		863
779	<ol>	864	<ol>
780	<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>
781	<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>
782	</ol>	869	</ol>
783		870
784	<p>	871	<p>
		872	Portage 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>
785	If the package is masked because of the first reason, and you <e>really</e> want	899	If the package is masked because of <b>~arch keyword</b>, and you <e>really</e>
786	to install it (knowing that there <e>is</e> a reason why it isn't available in	900	want 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:	901	available in <e>ARCH</e>), you can accept the <e>~ARCH</e> version of any
788	</p>	902	package by adding it to your <path>/etc/portage/package.keywords</path> file:
789
790	<pre caption="Temporarily accepting ~ARCH packages">
791	# <i>ACCEPT_KEYWORDS="~x86" emerge gnumeric</i>
792	</pre>
793
794	<p>	903	</p>
795	A 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" >> /etc/portage/package.keywords</i>
		910	# <i>emerge gnumeric</i>
		911	</pre>
		912
		913	<p>
		914	Similarly, if you want to install a package marked <b>-arch keyword</b> or <b>-*
		915	keyword</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
		917	keyword:
		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" >> /etc/portage/package.keywords</i>
		925	<comment>(or)</comment>
		926	# <i>echo "app-office/gnumeric -*" >> /etc/portage/package.keywords</i>
		927	# <i>emerge gnumeric</i>
		928	</pre>
		929
		930	<p>
		931	If you only want to allow the merging of such a package for a specific version
		932	or version range, you can use the "<, <=, =, >= or >" 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" >> /etc/portage/package.keywords</i>
		937	</pre>
		938
		939	<p>
		940	A package is masked due to <b>package.mask</b> if it is listed in
796	<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
797	will also read the reason why the package is hardmasked (it is usually added as	942	will also read the reason why the package is hardmasked (it is usually added as
798	a comment). If you want to install the package nevertheless (despite all the	943	a comment). If you want to install the package nevertheless (despite all the
799	possible warnings we could ever throw at your head about "breaking your system",	944	possible warnings we could ever throw at your head about "breaking your system",
800	"breaks other packages", or "badly needs testing"), create the	945	"breaks other packages", or "badly needs testing"), create the
801	<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
802	the same format as is used in <path>/usr/portage/profiles/package.mask</path>).	947	the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
803	</p>	948	</p>
804		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" >> /etc/portage/package.unmask</i>
		955	</pre>
		956
805	<p>	957	<p>
806	Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as	958	Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as
807	all changes are undone the next time you update your Portage tree.	959	all changes are undone the next time you update your Portage tree.
808	</p>
809
810	<p>	960	</p>
811	Another trick to circumvent the "masked package" problem is to install the	961
812	package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c>
813	settings and the <path>package.mask</path> listing.
814	</p>	962	<p>
815		963	Sometimes you might want to hardmask a (collection of) package(s). This is the
816	<pre caption="Installing a package without checking for stadium / masking">	964	case when newer versions of an application don't support something you require
817	# <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i>	965	or when these versions break something else in your environment.
818	</pre>	966	</p>
		967
		968	<p>
		969	To hard-mask a package, create <path>/etc/portage/package.mask</path> and list
		970	the package in it (use the same format as mentioned above).
		971	</p>
		972
		973	<pre caption="Hard-masking a package">
		974	<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
		975	# <i>mkdir /etc/portage</i>
		976
		977	# <i>echo ">app-office/gnumeric-1.2.10" >> /etc/portage/package.mask</i>
		978	</pre>
		979
		980	<p>
		981	When Portage tells you that it cannot install a package due to <b>profile</b> it
		982	means that you are working with a certain profile that doesn't allow the package
		983	to be installed. But what is this "profile"?
		984	</p>
		985
		986	<p>
		987	A profile contains a list of package names and a set of default configuration
		988	options to be used by Portage. Those files tell Portage which packages
		989	and which specific versions of those packages to allow, disallow, or
		990	treat as required. Users can switch profiles by changing a single symlink
		991	(<path>/etc/make.profile</path>).
		992	</p>
		993
		994	<p>
		995	You cannot override a package that is blocked due to <b>profile</b>; if you
		996	really want to use it, switch to the required profile.
		997	</p>
		998
		999	<p>
		1000	You will find more information in our <uri
		1001	link="/proj/en/releng/docs/cascading-profiles.xml">Cascading Profiles
		1002	Document</uri>.
		1003	</p>
819		1004
820	</body>	1005	</body>
821	</subsection>	1006	</subsection>
822	<subsection>	1007	<subsection>
823	<title>Blocked Packages</title>	1008	<title>Blocked Packages</title>

 Legend:



Removed from v.1.13
 


changed lines


 
Added in v.1.38
 Legend:



Removed from v.1.13
 


changed lines


 
Added in v.1.38
-Removed from v.1.13
+Added in v.1.38

	ViewVC Help
Powered by ViewVC 1.1.13