/[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.6		Revision 1.33
		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.6 2003/11/27 14:45:38 swift Exp $ -->	7	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.33 2004/08/23 15:33:29 neysx 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>
…		…
12		15
13	<p>	16	<p>
14	The main Portage tool that most users will use is <c>emerge</c>. We have already	17	The main Portage tool that most users will use is <c>emerge</c>. We have already
15	used it during the Gentoo installation and in the previous chapter, but we just	18	used it during the Gentoo installation and in the previous chapter, but we just
16	briefly explained how to use it. This chapter will elaborate on <c>emerge</c>	19	briefly explained how to use it. This chapter will elaborate on <c>emerge</c>
17	and learn you how to use <c>emerge</c> to fix all your software-related needs.	20	and teach you how to use <c>emerge</c> to fix all your software-related needs.
18	</p>	21	</p>
19		22
20	<p>	23	<p>
21	<c>emerge</c> is the command used to install, remove, query and maintain	24	<c>emerge</c> is the command used to install, remove, query and maintain
22	software packages. It is a front-end for <c>ebuild</c>; people interested in	25	software packages. It is a front-end for <c>ebuild</c>; people interested in
…		…
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
…		…
103	gnofin/ khacc/ mrproject/ phprojekt/ texmacs/	106	gnofin/ khacc/ mrproject/ phprojekt/ texmacs/
104	</pre>	107	</pre>
105		108
106	<p>	109	<p>
107	Inside a category you will find the packages belonging to that category, with a	110	Inside a category you will find the packages belonging to that category, with a
108	seperate directory for each package. Let us take a look at the <c>openoffice</c>	111	separate directory for each package. Let us take a look at the <c>openoffice</c>
109	package:	112	package:
110	</p>	113	</p>
111		114
112	<pre caption="Viewing a package">	115	<pre caption="Viewing a package">
113	# <i>cd openoffice; ls --classify</i>	116	# <i>cd openoffice; ls --classify</i>
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>
…		…
224		228
225	<p>	229	<p>
226	You see something new? Yes, <e>downloaded files</e>. When you tell Portage to	230	You see something new? Yes, <e>downloaded files</e>. When you tell Portage to
227	install a package, it of course needs to have the necessary sources (or	231	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>
…		…
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>
…		…
336	</subsection>	345	</subsection>
337	</section>	346	</section>
338	<section>	347	<section>
339	<title>Maintaining Software</title>	348	<title>Maintaining Software</title>
340	<subsection>	349	<subsection>
341	<title>Building or Prebuild?</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>prebuild</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 next to 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
…		…
357	Of course, you can also define high optimization options (in the <c>CFLAGS</c>	366	Of course, you can also define high optimization options (in the <c>CFLAGS</c>
358	and <c>CXXFLAGS</c> variables) to compile the package with.	367	and <c>CXXFLAGS</c> variables) to compile the package with.
359	</p>	368	</p>
360		369
361	<p>	370	<p>
362	Using prebuild packages improves the installation time (as no more compilation	371	Using prebuilt packages improves the installation time (as no more compilation
363	is needed), but you will lose the advantages of the <c>USE</c> setting and the	372	is needed), but you will lose the advantages of the <c>USE</c> setting and the
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, prebuild 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>
…		…
380	<title>Installing Software from Sources</title>	389	<title>Installing Software from Sources</title>
381	<body>	390	<body>
382		391
383	<p>	392	<p>
384	Okay, enough talking, let's cut to the chase. To install a package, you will use	393	Okay, enough talking, let's cut to the chase. To install a package, you will use
385	the <c>emerge</c> command. If you don't want to use any prebuild packages, you	394	the <c>emerge</c> command. If you don't want to use any prebuilt packages, you
386	can just use <c>emerge <package-name></c> or <c>emerge	395	can just use <c>emerge <package-name></c> or <c>emerge
387	<category>/<package-name></c>. As an example we'll install	396	<category>/<package-name></c>. As an example we'll install
388	<c>gnumeric</c>:	397	<c>gnumeric</c>:
389	</p>	398	</p>
390		399
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">
…		…
438	</p>	447	</p>
439		448
440	</body>	449	</body>
441	</subsection>	450	</subsection>
442	<subsection>	451	<subsection>
443	<title>Installing Prebuild Packages</title>	452	<title>Installing Prebuilt Packages</title>
444	<body>	453	<body>
445		454
446	<p>	455	<p>
447	When you want to install a prebuild package, you should use the <c>--usepkg</c>	456	When you want to install a prebuilt package, you should use the <c>--usepkg</c>
448	option (<c>-k</c> in short). This will use the binary package available in	457	option (<c>-k</c> in short). This will use the binary package available in
449	<path>/usr/portage/packages/All</path> <e>if</e> the package and the version of	458	<path>/usr/portage/packages/All</path> <e>if</e> the package and the version of
450	the application you want to install match.	459	the application you want to install match.
451	</p>	460	</p>
452		461
453	<pre caption="Installing a prebuild package for gnumeric">	462	<pre caption="Installing a prebuilt package for gnumeric">
454	# <i>emerge --usepkg gnumeric</i>	463	# <i>emerge --usepkg gnumeric</i>
455	</pre>	464	</pre>
456		465
457	<p>	466	<p>
458	If you want to use the binary package, even if the versions don't match, use	467	If you want to use the binary package, even if the versions don't match, use
459	<c>--usepkgonly</c> (<c>-K</c> in short).	468	<c>--usepkgonly</c> (<c>-K</c> in short).
460	</p>	469	</p>
461		470
462	<pre caption="Installing the prebuild package for gnumeric">	471	<pre caption="Installing the prebuilt package for gnumeric">
463	# <i>emerge --usepkgonly gnumeric</i>	472	# <i>emerge --usepkgonly gnumeric</i>
464	</pre>	473	</pre>
465		474
466	<!-- TODO When handbook goes life, comment out this parts until the mirrors have
467	been updated with online GRP packages. -->
468	<p>	475	<p>
469	If you don't have the prebuild package on your system yet, you can have	476	If you don't have the prebuilt package on your system yet, you can have
470	<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>
471	variable declared in <path>/etc/make.conf</path>.	478	variable declared in <path>/etc/make.conf</path>.
472	</p>	479	</p>
473		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
474	<p>	486	<p>
475	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
476	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):
477	</p>	489	</p>
478		490
479	<pre caption="Downloading and installing a prebuild package for gnumeric">	491	<pre caption="Downloading and installing a prebuilt package for gnumeric">
480	# <i>emerge --getbinpkg gnumeric</i>	492	# <i>emerge --getbinpkg gnumeric</i>
481	</pre>	493	</pre>
482		494
483	<p>	495	<p>
484	This will download the package and the package-related information for you and	496	This will download the package and the package-related information for you and
485	install it on your system, together with the dependencies. If you want to see	497	install it on your system, together with the dependencies. If you want to see
486	what dependencies will be installed with it, use the <c>--pretend</c> option	498	what dependencies will be installed with it, use the <c>--pretend</c> option
487	(<c>-p</c> in short):	499	(<c>-p</c> in short):
488	</p>	500	</p>
489		501
490	<pre caption="Pretending to download the prebuild packages for gnumeric">	502	<pre caption="Pretending to download the prebuilt packages for gnumeric">
491	# <i>emerge --ginbinpkg --pretend gnumeric</i>	503	# <i>emerge --getbinpkg --pretend gnumeric</i>
492	</pre>	504	</pre>
493		505
494	<p>	506	<p>
495	You can also opt to download the prebuild package (and the package-related	507	You can also opt to download the prebuilt package (and the package-related
496	information) <e>without</e> checking the information on your local system and	508	information) <e>without</e> checking the information on your local system and
497	<e>without</e> using the prebuild package already on your system (if	509	<e>without</e> using the prebuilt package already on your system (if
498	applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short):	510	applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short):
499	</p>	511	</p>
500		512
501	<pre caption="Installing a prebuild package without using local information">	513	<pre caption="Installing a prebuilt package without using local information">
502	# <i>emerge --getbinpkgonly gnumeric</i>	514	# <i>emerge --getbinpkgonly gnumeric</i>
503	</pre>	515	</pre>
504
505	<!-- TODO Up until here -->
506		516
507	<p>	517	<p>
508	You can also opt to install a specific version of a package.	518	You can also opt to install a specific version of a package.
509	For instance, if you want to install a gnumeric version older than 1.2 -- for	519	For instance, if you want to install a gnumeric version older than 1.2 -- for
510	any reason whatsoever :) you would type:	520	any reason whatsoever :) you would type:
…		…
517	<p>	527	<p>
518	Other possibilities are of course ">" (later version) and "=" (the exact	528	Other possibilities are of course ">" (later version) and "=" (the exact
519	version).	529	version).
520	</p>	530	</p>
521		531
		532
		533	</body>
		534	</subsection>
		535	<subsection>
		536	<title>Working with Dependencies</title>
		537	<body>
		538
		539	<p>
		540	Portage has an extensive support for dependency handling. Although you usually
		541	don't need to even think about this (as dependencies are automatically handled
		542	by Portage) some users might want to know how you can work with <c>emerge</c>
		543	and dependencies.
		544	</p>
		545
		546	<p>
		547	For instance, if you want Portage to pretend that none of the dependencies of a
		548	package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This
		549	is useful with <c>--pretend</c> to display a complete tree of dependencies for
		550	any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile
		551	all listed packages.
		552	</p>
		553
		554	<pre caption="Show all dependencies of gnumeric">
		555	# <i>emerge --emptytree --pretend gnumeric</i>
		556	</pre>
		557
		558	<p>
		559	Another argument is <c>--nodeps</c>, which will ask Portage to try install the
		560	given package without taking care of the dependencies. It is trivial that this
		561	can lead to failures.
		562	</p>
		563
		564	<pre caption="Installing gnumeric without taking care of the dependencies">
		565	# <i>emerge --nodeps gnumeric</i>
		566	</pre>
		567
		568	<p>
		569	The opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage
		570	install all dependencies of a given package, but not the package itself:
		571	</p>
		572
		573	<pre caption="Installing the dependencies of gnumeric">
		574	# <i>emerge --onlydeps gnumeric</i>
		575	</pre>
522		576
523	</body>	577	</body>
524	</subsection>	578	</subsection>
525	<subsection>	579	<subsection>
526	<title>Updating your System</title>	580	<title>Updating your System</title>
…		…
586	<li>	640	<li>
587	<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
588	first time	642	first time
589	</li>	643	</li>
590	<li>	644	<li>
591	<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
592	</li>	646	</li>
593	<li>	647	<li>
594	<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
595	manually (for instance due to licencing issues)	649	manually (for instance due to licencing issues)
596	</li>	650	</li>
597	<li>	651	<li>
598	<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
599	upgraded	653	upgraded
600	</li>	654	</li>
601	<li>	655	<li>
602	<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
603	downgraded	657	downgraded
604	</li>	658	</li>
605	<li>
606	<e>U-</e> (slot warning) The package you have installed on your system
607	is listed as a package that can not coexist with a different version, but
608	your update does. The update will be installed and the older version will be
609	removed.
610	</li>
611	</ul>	659	</ul>
612		660
613	<p>	661	<p>
614	In certain cases, an update may mean a downgrade (i.e. install an older version	662	We have mentioned that the <e>world</e> file doesn't contain dependencies. When
615	instead of a newer version). If you don't want this to happen, use the	663	you run <c>emerge --update world</c> only the packages mentioned in the
616	<c>--upgradeonly</c> option (<c>-U</c> in short):	664	<e>world</e> file and it's immediate dependencies are checked and, if necessary,
		665	upgraded. 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:
617	</p>	667	</p>
618		668
619	<pre caption="Upgrading your entire system">	669	<pre caption="Upgrading your entire system, including all dependencies">
620	# <i>emerge --update --upgradeonly world</i>	670	# <i>emerge --update --deep world</i>
621	</pre>	671	</pre>
622		672
623	<p>	673	<p>
624	Of course, we are talking here about <e>system</e> and <e>world</e>, but you can	674	Of course, we are talking here about <e>system</e> and <e>world</e>, but you can
625	perform the same actions for individual software packages.	675	perform the same actions for individual software packages.
…		…
654	installed package. It also doesn't warn you if the package is part of	704	installed package. It also doesn't warn you if the package is part of
655	<e>system</e>, i.e. a core application necessary for the correct functioning of	705	<e>system</e>, i.e. a core application necessary for the correct functioning of
656	your system!	706	your system!
657	</warn>	707	</warn>
658		708
		709	<p>
		710	Once the unmerge begins you will see a long list of filenames belonging to the
		711	package. Some of these filenames will have a flag displayed to the
		712	left of the filename. The flags <c>!mtime</c>, <c>!empty</c>, and <c>cfgpro</c>
		713	specify reasons why certain files are not being removed while the package is.
		714	Files listed without any of these three flags are removed from the
		715	filesystem successfully. The three flags specify the following reasons:
		716	</p>
		717
		718	<ul>
		719	<li>
		720	<c>!mtime</c> : The listed file has been changed since it was installed,
		721	probably by you or some tool
		722	</li>
		723	<li>
		724	<c>!empty</c> : The listed directory is not empty
		725	</li>
		726	<li>
		727	<c>cfgpro</c> : This file is located inside a protected directory and will
		728	not be touched for safety
		729	</li>
		730	</ul>
		731
659	</body>	732	</body>
660	</subsection>	733	</subsection>
661	</section>	734	</section>
662	<section>	735	<section>
663	<title>Software Availability</title>	736	<title>Working with Masked Packages</title>
664	<subsection>	737	<subsection>
665	<title>ARCH or not?</title>	738	<title>ARCH or not?</title>
666	<body>	739	<body>
667		740
668	<p>	741	<p>
…		…
679	to <e>ARCH</e> after being bugfree for a sufficient amount of time.	752	to <e>ARCH</e> after being bugfree for a sufficient amount of time.
680	</p>	753	</p>
681		754
682	<p>	755	<p>
683	Your system will use <e>ARCH</e> packages per default. If you want to live on	756	Your system will use <e>ARCH</e> packages per default. If you want to live on
684	the edge, don't mind having a broken package once in a while, and you like	757	the edge, don't mind having a broken package once in a while, know how to deal
685	submitting bugreports to <uri	758	with a broken system and you like submitting bugreports to <uri
686	link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use	759	link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use
687	<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,
688	edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that	761	edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that
689	it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).	762	it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).
690	</p>	763	</p>
691		764
692	<p>	765	<p>
		766	Note 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>
693	If you want to update your system now, you will notice that <e>a lot</e> of	771	If you want to update your system now, you will notice that <e>a lot</e> of
694	packages will be updated!	772	packages will be updated!
695	</p>	773	</p>
696		774
697	</body>	775	</body>
…		…
708	Calculating dependencies	786	Calculating dependencies
709	!!! <comment>all ebuilds that could satisfy </comment><your package><comment> have been masked.</comment>	787	!!! <comment>all ebuilds that could satisfy </comment><your package><comment> have been masked.</comment>
710	</pre>	788	</pre>
711		789
712	<p>	790	<p>
713	A package can be masked due to two reasons:	791	A package can be masked due to several reasons:
714	</p>	792	</p>
715		793
716	<ol>	794	<ol>
717	<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>
718	<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>
719	</ol>	799	</ol>
720		800
721	<p>	801	<p>
722	If the package is masked because of the first reason, and you <e>really</e> want	802	If the package is masked because of the first reason, and you <e>really</e>
723	to install it (knowing that there <e>is</e> a reason why it isn't available in	803	want to install it (knowing that there <e>is</e> a reason why it isn't
724	<e>ARCH</e>), you can temporarily accept <e>~ARCH</e> packages:	804	available in <e>ARCH</e>), you can accept the <e>~ARCH</e> version of any
		805	package by adding it to your <path>/etc/portage/package.keywords</path> file:
725	</p>	806	</p>
726		807
727	<pre caption="Temporarily accepting ~ARCH packages">	808	<pre caption="Accepting the ~ARCH version of a package">
728	# <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" >> /etc/portage/package.keywords</i>
		813	# <i>emerge gnumeric</i>
729	</pre>	814	</pre>
730		815
731	<p>	816	<p>
732	A package is hardmasked if it is listed in	817	A package is hardmasked if it is listed in
733	<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
…		…
737	"breaks other packages", or "badly needs testing"), create the	822	"breaks other packages", or "badly needs testing"), create the
738	<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
739	the same format as is used in <path>/usr/portage/profiles/package.mask</path>).	824	the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
740	</p>	825	</p>
741		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" >> /etc/portage/package.unmask</i>
		832	</pre>
		833
742	<p>	834	<p>
743	Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as	835	Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as
744	all changes are undone the next time you update your Portage tree.	836	all changes are undone the next time you update your Portage tree.
745	</p>
746
747	<p>	837	</p>
748	Another trick to circumvent the "masked package" problem is to install the	838
749	package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c>
750	settings and the <path>package.mask</path> listing.
751	</p>	839	<p>
		840	Sometimes you might want to hardmask a (collection of) package(s). This is the
		841	case when newer versions of an application don't support something you require
		842	or when these versions break something else in your environment.
		843	</p>
752		844
753	<pre caption="Installing a package without checking for stadium / masking">	845	<p>
754	# <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i>	846	To hard-mask a package, create <path>/etc/portage/package.mask</path> and list the
		847	package 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 ">app-office/gnumeric-1.2.10" >> /etc/portage/package.mask</i>
755	</pre>	855	</pre>
756		856
757	</body>	857	</body>
758	</subsection>	858	</subsection>
759	<subsection>	859	<subsection>

 Legend:



Removed from v.1.6
 


changed lines


 
Added in v.1.33
 Legend:



Removed from v.1.6
 


changed lines


 
Added in v.1.33
-Removed from v.1.6
+Added in v.1.33

	ViewVC Help
Powered by ViewVC 1.1.13