1 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
2 |
<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> |
3 |
|
4 |
<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.16 2004/01/06 15:39:48 swift Exp $ --> |
5 |
|
6 |
<sections> |
7 |
<section> |
8 |
<title>Obtaining Package Information</title> |
9 |
<subsection> |
10 |
<title>The Lord of All Tools: emerge</title> |
11 |
<body> |
12 |
|
13 |
<p> |
14 |
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 |
16 |
briefly explained how to use it. This chapter will elaborate on <c>emerge</c> |
17 |
and teach you how to use <c>emerge</c> to fix all your software-related needs. |
18 |
</p> |
19 |
|
20 |
<p> |
21 |
<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 |
23 |
becoming Gentoo professionals will learn how to use <c>ebuild</c> later on. For |
24 |
now, we will focus on <c>emerge</c> as it has functionality that <c>ebuild</c> |
25 |
lacks (such as resolving dependencies, searching the Portage tree, etc.). |
26 |
</p> |
27 |
|
28 |
<p> |
29 |
Since <c>emerge</c> is the most important tool for Gentoo users, it has an |
30 |
extensive manpage you can read by issuing <c>man emerge</c>. You can also view |
31 |
the in-command help by running <c>emerge --help</c>. |
32 |
</p> |
33 |
|
34 |
<pre caption="Retrieving help for emerge"> |
35 |
# <i>man emerge</i> |
36 |
# <i>emerge --help</i> |
37 |
</pre> |
38 |
|
39 |
</body> |
40 |
</subsection> |
41 |
<subsection> |
42 |
<title>The Portage Tree</title> |
43 |
<body> |
44 |
|
45 |
<p> |
46 |
Before we continue describing <c>emerge</c>, let us first take a look at the |
47 |
Portage Tree. Go to <path>/usr/portage</path> and do a listing of the available |
48 |
directories. We use <c>ls --classify</c> to list the contents of a |
49 |
directory as it will show directories with a trailing "/". |
50 |
</p> |
51 |
|
52 |
<pre caption="Viewing the Portage Tree"> |
53 |
# <i>cd /usr/portage; ls --classify</i> |
54 |
app-admin/ dev-ml/ gnome-libs/ net-print/ |
55 |
app-arch/ dev-perl/ gnome-office/ net-wireless/ |
56 |
app-benchmarks/ dev-php/ header.txt net-www/ |
57 |
app-cdr/ dev-python/ incoming/ net-zope/ |
58 |
app-crypt/ dev-ruby/ jython/ packages/ |
59 |
app-dicts/ dev-tcltk/ kde-apps/ profiles/ |
60 |
app-doc/ dev-tex/ kde-base/ releases/ |
61 |
app-editors/ dev-util/ kde-i18n/ scripts/ |
62 |
app-emacs/ distfiles/ kde-libs/ sec-policy/ |
63 |
app-emulation/ eclass/ licenses/ skel.ChangeLog |
64 |
app-games/ experimental/ media-fonts/ skel.ebuild |
65 |
app-gnustep/ files/ media-gfx/ skel.metadata.xml |
66 |
app-i18n/ fresco-base/ media-libs/ snapshots/ |
67 |
app-misc/ games-action/ media-plugins/ sys-apps/ |
68 |
app-office/ games-arcade/ media-radio/ sys-build/ |
69 |
app-pda/ games-board/ media-sound/ sys-cluster/ |
70 |
app-portage/ games-emulation/ media-tv/ sys-devel/ |
71 |
app-sci/ games-engines/ media-video/ sys-fs/ |
72 |
app-shells/ games-fps/ metadata/ sys-kernel/ |
73 |
app-text/ games-kids/ net-analyzer/ sys-kmods/ |
74 |
app-vim/ games-misc/ net-apache/ sys-libs/ |
75 |
app-xemacs/ games-mud/ net-dialup/ unix2tcp/ |
76 |
berlin-base/ games-puzzle/ net-dns/ x11-base/ |
77 |
dev-ada/ games-roguelike/ net-firewall/ x11-libs/ |
78 |
dev-cpp/ games-rpg/ net-fs/ x11-misc/ |
79 |
dev-db/ games-server/ net-ftp/ x11-plugins/ |
80 |
dev-dotnet/ games-simulation/ net-im/ x11-terms/ |
81 |
dev-embedded/ games-sports/ net-irc/ x11-themes/ |
82 |
dev-games/ games-strategy/ net-libs/ x11-wm/ |
83 |
dev-haskell/ games-util/ net-mail/ xfce-base/ |
84 |
dev-java/ glep/ net-misc/ xfce-extra/ |
85 |
dev-lang/ gnome-apps/ net-nds/ |
86 |
dev-libs/ gnome-base/ net-news/ |
87 |
dev-lisp/ gnome-extra/ net-p2p/ |
88 |
</pre> |
89 |
|
90 |
<p> |
91 |
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>, |
93 |
reside. Take a look at, for instance, <path>app-office</path>: |
94 |
</p> |
95 |
|
96 |
<pre caption="Viewing a category"> |
97 |
# <i>cd app-office; ls --classify</i> |
98 |
abiword/ gnotime/ kmymoney2/ ooodi/ plan/ timestamp.x |
99 |
dia/ gnucash/ koffice/ oooqs/ qhacc/ |
100 |
dia2code/ gnumeric/ lxbank/ openoffice/ sc/ |
101 |
facturalux/ ical/ lyx/ openoffice-bin/ scribus/ |
102 |
gaby/ kbudget/ mdbtools/ openoffice-ximian/ siag/ |
103 |
gnofin/ khacc/ mrproject/ phprojekt/ texmacs/ |
104 |
</pre> |
105 |
|
106 |
<p> |
107 |
Inside a category you will find the packages belonging to that category, with a |
108 |
separate directory for each package. Let us take a look at the <c>openoffice</c> |
109 |
package: |
110 |
</p> |
111 |
|
112 |
<pre caption="Viewing a package"> |
113 |
# <i>cd openoffice; ls --classify</i> |
114 |
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 |
116 |
</pre> |
117 |
|
118 |
<p> |
119 |
Remember that we told you that a Gentoo package is called an ebuild? Well, in |
120 |
the example directory four of such ebuilds are stored. Their naming is |
121 |
almost identical: they only differ in the version name. |
122 |
You are free to view the contents of such a package: they are plain scripts. We |
123 |
will not discuss it right now as it isn't important to know if you plan on just |
124 |
using Gentoo. |
125 |
</p> |
126 |
|
127 |
<p> |
128 |
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 |
130 |
checksums and permissions of all the files in the directory) and |
131 |
<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 |
133 |
extensive description). |
134 |
</p> |
135 |
|
136 |
<p> |
137 |
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 |
139 |
version of the package), patches, example configuration files, etc. |
140 |
</p> |
141 |
|
142 |
<pre caption="Viewing the extra files"> |
143 |
# <i>cd files; ls --classify</i> |
144 |
1.0.3/ digest-openoffice-1.0.3-r1 digest-openoffice-1.1.0-r1 |
145 |
1.1.0/ digest-openoffice-1.1.0 digest-openoffice-1.1.0-r2 |
146 |
# <i>cd 1.1.0; ls --classify</i> |
147 |
fixed-gcc.patch ooffice-wrapper-1.3 |
148 |
newstlportfix.patch openoffice-1.1.0-linux-2.6-fix.patch |
149 |
no-mozab.patch openoffice-1.1.0-sparc64-fix.patch |
150 |
nptl.patch |
151 |
</pre> |
152 |
|
153 |
<p> |
154 |
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 |
156 |
those later in this chapter. |
157 |
</p> |
158 |
|
159 |
</body> |
160 |
</subsection> |
161 |
<subsection> |
162 |
<title>Search for a Package</title> |
163 |
<body> |
164 |
|
165 |
<p> |
166 |
If you are new to Linux or Gentoo, you might not know what tool you need for |
167 |
what job. To facilitate searching, <c>emerge</c> provides you with a way to |
168 |
search through the available packages on your system. There are two ways you can |
169 |
search through packages: by <e>name</e>, or by <e>name</e> and |
170 |
<e>description</e>. |
171 |
</p> |
172 |
|
173 |
<p> |
174 |
To search through the Portage tree by name, use <c>emerge search</c>. For |
175 |
instance, to find out more about <c>mozilla</c>: |
176 |
</p> |
177 |
|
178 |
<pre caption="Showing information about mozilla"> |
179 |
# <i>emerge search mozilla</i> |
180 |
Searching... |
181 |
[ Results for search key : mozilla ] |
182 |
[ Applications found : 5 ] |
183 |
<comment>(Some output removed to improve readability)</comment> |
184 |
* net-www/mozilla |
185 |
Latest version available: 1.5-r1 |
186 |
Latest version installed: 1.4-r3 |
187 |
Size of downloaded files: 29,153 kB |
188 |
Homepage: http://www.mozilla.org |
189 |
Description: The Mozilla Web Browser |
190 |
|
191 |
* net-www/mozilla-firebird |
192 |
Latest version available: 0.7 |
193 |
Latest version installed: [ Not Installed ] |
194 |
Size of downloaded files: 37,850 kB |
195 |
Homepage: http://www.mozilla.org/projects/firebird/ |
196 |
Description: The Mozilla Firebird Web Browser |
197 |
<comment>(...)</comment> |
198 |
</pre> |
199 |
|
200 |
<p> |
201 |
If you want to include a search through the descriptions too, use the |
202 |
<c>--searchdesc</c> argument: |
203 |
</p> |
204 |
|
205 |
<pre caption="Search through the descriptions too"> |
206 |
# <i>emerge --searchdesc mozilla</i> |
207 |
Searching... |
208 |
[ Results for search key : mozilla ] |
209 |
[ Applications found : 10 ] |
210 |
<comment>(Some output removed to improve readability)</comment> |
211 |
* dev-libs/nss-3.8 |
212 |
Latest version available: 3.8 |
213 |
Latest version installed: 3.8 |
214 |
Size of downloaded files: 2,782 kB |
215 |
Homepage: http://www.mozilla.org/projects/security/pki/nss/ |
216 |
Description: Mozilla's Netscape Security Services Library that implements PKI support |
217 |
</pre> |
218 |
|
219 |
<p> |
220 |
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, |
222 |
the size of the downloaded files, the homepage and the small description. |
223 |
</p> |
224 |
|
225 |
<p> |
226 |
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 |
228 |
precompiled packages) available. It therefore checks the contents of |
229 |
<path>/usr/portage/distfiles</path> (for source code) or |
230 |
<path>/usr/portage/packages/All</path> (for precompiled packages) to see if the |
231 |
necessary files are already available. If not, it downloads the necessary files |
232 |
and places them in those directories. |
233 |
</p> |
234 |
|
235 |
<!-- |
236 |
<note> |
237 |
Searching the Portage Tree, especially when using <c>- -searchdesc</c>, is very |
238 |
time consuming. There are other, more performant tools available. We will |
239 |
describe those in the chapter on <uri link="?part=2&chap=7">Gentoolkit and |
240 |
Other Tools</uri>. |
241 |
</note> |
242 |
--> |
243 |
|
244 |
</body> |
245 |
</subsection> |
246 |
<subsection> |
247 |
<title>Viewing the ChangeLog</title> |
248 |
<body> |
249 |
|
250 |
<p> |
251 |
While browsing through the Portage Tree, you saw that there was a ChangeLog for |
252 |
each package. You can view the ChangeLog entries between the available version |
253 |
and the installed version with <c>emerge</c> too. Use the |
254 |
<c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we |
255 |
will view the ChangeLog entries for <c>gnumeric</c>: |
256 |
</p> |
257 |
|
258 |
<pre caption="Viewing the ChangeLog entries for gnumeric"> |
259 |
# <i>emerge --pretend --changelog gnumeric</i> |
260 |
<comment>(Some output removed to improve readability)</comment> |
261 |
*gnumeric-1.2.2 |
262 |
|
263 |
27 Nov 2003; foser <foser@gentoo.org> gnumeric-1.2.2.ebuild : |
264 |
New release, requested in #34492 |
265 |
updated deps |
266 |
|
267 |
12 Nov 2003; Jason Wever <weeve@gentoo.org> gnumeric-1.2.0.ebuild: |
268 |
Marked stable on sparc, fixes bug #32405. |
269 |
|
270 |
14 Oct 2003; Jason Wever <weeve@gentoo.org> gnumeric-1.0.8.ebuild: |
271 |
Added ~sparc keyword. Fixes bug #31150. |
272 |
</pre> |
273 |
|
274 |
</body> |
275 |
</subsection> |
276 |
</section> |
277 |
<section> |
278 |
<title>Updating Portage</title> |
279 |
<subsection> |
280 |
<title>Introduction</title> |
281 |
<body> |
282 |
|
283 |
<p> |
284 |
Searching through Portage is nice, but if you don't update your Portage Tree |
285 |
regularly, you will be stuck with the packages and versions available on your |
286 |
system. This means that your system will get outdated pretty soon and that |
287 |
you will be missing bugfixes and remedies for possible security problems. |
288 |
</p> |
289 |
|
290 |
<p> |
291 |
There are several ways to update your Portage Tree. The most popular method is |
292 |
by using one of our <uri link="/main/en/mirrors.xml">rsync mirrors</uri>. |
293 |
Another one is by using a Portage snapshot (in case a firewall or unavailability |
294 |
of a network prohibits the use of the rsync server). |
295 |
</p> |
296 |
|
297 |
</body> |
298 |
</subsection> |
299 |
<subsection> |
300 |
<title>Selecting a Mirror for rsync</title> |
301 |
<body> |
302 |
|
303 |
<p> |
304 |
It is adviseable to first select a fast <uri |
305 |
link="/main/en/mirrors.xml">mirror</uri> close to you. You can do this manually |
306 |
(by setting the <c>SYNC</c> variable in <path>/etc/make.conf</path>) or use |
307 |
<c>mirrorselect</c> to do this for you automatically. As the <c>SYNC</c> |
308 |
variable will be discussed later on, we will focus on using <c>mirrorselect</c>. |
309 |
First install <c>mirrorselect</c> by emerging it: |
310 |
</p> |
311 |
|
312 |
<pre caption="Installing mirrorselect"> |
313 |
# <i>emerge --usepkg mirrorselect</i> |
314 |
</pre> |
315 |
|
316 |
<p> |
317 |
Now run <c>mirrorselect</c> to automatically select mirrors for you (it will |
318 |
also setup Portage to use a mirror for the source code): |
319 |
</p> |
320 |
|
321 |
<pre caption="Running mirrorselect"> |
322 |
# <i>mirrorselect -a -s3</i> |
323 |
</pre> |
324 |
|
325 |
</body> |
326 |
</subsection> |
327 |
<subsection> |
328 |
<title>Updating Portage</title> |
329 |
<body> |
330 |
|
331 |
<p> |
332 |
To update Portage using rsync, simply run <c>emerge sync</c>: |
333 |
</p> |
334 |
|
335 |
<pre caption="Updating Portage using emerge sync"> |
336 |
# <i>emerge sync</i> |
337 |
</pre> |
338 |
|
339 |
<p> |
340 |
If this fails (due to network problems, or a firewall), you can try using |
341 |
<c>emerge-webrsync</c> which will download a Portage Tree snapshot using |
342 |
<c>wget</c>. This also means that you can use proxies if you want. We discussed |
343 |
how to setup your system to use proxies during the Gentoo installation. |
344 |
</p> |
345 |
|
346 |
<pre caption="Updating Portage using emerge-webrsync"> |
347 |
# <i>emerge-webrsync</i> |
348 |
</pre> |
349 |
|
350 |
</body> |
351 |
</subsection> |
352 |
</section> |
353 |
<section> |
354 |
<title>Maintaining Software</title> |
355 |
<subsection> |
356 |
<title>Building or Prebuilt?</title> |
357 |
<body> |
358 |
|
359 |
<p> |
360 |
Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to |
361 |
install such an ebuild, you can choose between <e>building</e> the package and |
362 |
using a <e>prebuilt</e> package. But what are the advantages/disadvantages of |
363 |
both approaches, and can they be used next to each other? |
364 |
</p> |
365 |
|
366 |
<p> |
367 |
As you probably have guessed, building packages takes a lot of time (especially |
368 |
if you have little resources or want to build big packages, such as <uri |
369 |
link="http://www.kde.org">KDE</uri>, <uri |
370 |
link="http://www.openoffice.org">OpenOffice.org</uri>, etc.). By building the |
371 |
package, you can use the <c>USE</c> setting to tweak the package to your system. |
372 |
Of course, you can also define high optimization options (in the <c>CFLAGS</c> |
373 |
and <c>CXXFLAGS</c> variables) to compile the package with. |
374 |
</p> |
375 |
|
376 |
<p> |
377 |
Using prebuilt packages improves the installation time (as no more compilation |
378 |
is needed), but you will lose the advantages of the <c>USE</c> setting and the |
379 |
<c>CFLAGS</c> & <c>CXXFLAGS</c> variables. |
380 |
</p> |
381 |
|
382 |
<p> |
383 |
As previously stated, prebuilt packages are stored in the |
384 |
<path>/usr/portage/packages/All</path> directory, while the source code of the |
385 |
packages is placed in <path>/usr/portage/distfiles</path>. If you have finished |
386 |
installing a package you can remove the package or source code from the |
387 |
respective directory. However, you might want to keep the package/source code of |
388 |
the latest version, just in case you want to reinstall the package (so you don't |
389 |
have to redownload it). |
390 |
</p> |
391 |
|
392 |
</body> |
393 |
</subsection> |
394 |
<subsection> |
395 |
<title>Installing Software from Sources</title> |
396 |
<body> |
397 |
|
398 |
<p> |
399 |
Okay, enough talking, let's cut to the chase. To install a package, you will use |
400 |
the <c>emerge</c> command. If you don't want to use any prebuilt packages, you |
401 |
can just use <c>emerge <package-name></c> or <c>emerge |
402 |
<category>/<package-name></c>. As an example we'll install |
403 |
<c>gnumeric</c>: |
404 |
</p> |
405 |
|
406 |
<pre caption="Building gnumeric"> |
407 |
# <i>emerge gnumeric</i> |
408 |
</pre> |
409 |
|
410 |
<p> |
411 |
This will download the source code for you and unpacks, compiles and installs |
412 |
the package on your system. It will also do the same for all the dependencies. |
413 |
If you want to see what dependencies will be installed with it, use the |
414 |
<c>--pretend</c> option (<c>-p</c> in short): |
415 |
</p> |
416 |
|
417 |
<pre caption="Pretending to build gnumeric"> |
418 |
# <i>emerge --pretend gnumeric</i> |
419 |
</pre> |
420 |
|
421 |
<p> |
422 |
If you want to download the source code of the package and its dependencies, |
423 |
but don't want to build the package, use the <c>--fetchonly</c> option |
424 |
(<c>-f</c> in short): |
425 |
</p> |
426 |
|
427 |
<pre caption="Fetching sources for gnumeric"> |
428 |
# <i>emerge --fetchonly gnumeric</i> |
429 |
</pre> |
430 |
|
431 |
<p> |
432 |
If you want to see where <c>emerge</c> downloads the sources from, combine the |
433 |
<c>--fetchonly</c> and <c>--pretend</c> options: |
434 |
</p> |
435 |
|
436 |
<pre caption="Showing URLs of the sources for gnumeric"> |
437 |
# <i>emerge --fetchonly --pretend gnumeric</i> |
438 |
</pre> |
439 |
|
440 |
<p> |
441 |
You can also opt to install a specific version of a package. |
442 |
For instance, if you want to install a gnumeric version older than 1.2 -- for |
443 |
any reason whatsoever :) you would type: |
444 |
</p> |
445 |
|
446 |
<pre caption="Installing a specific gnumeric version"> |
447 |
# <i>emerge "<gnumeric-1.2"</i> |
448 |
</pre> |
449 |
|
450 |
<p> |
451 |
Other possibilities are of course ">" (later version) and "=" (the exact |
452 |
version). |
453 |
</p> |
454 |
|
455 |
</body> |
456 |
</subsection> |
457 |
<subsection> |
458 |
<title>Installing Prebuilt Packages</title> |
459 |
<body> |
460 |
|
461 |
<p> |
462 |
When you want to install a prebuilt package, you should use the <c>--usepkg</c> |
463 |
option (<c>-k</c> in short). This will use the binary package available in |
464 |
<path>/usr/portage/packages/All</path> <e>if</e> the package and the version of |
465 |
the application you want to install match. |
466 |
</p> |
467 |
|
468 |
<pre caption="Installing a prebuilt package for gnumeric"> |
469 |
# <i>emerge --usepkg gnumeric</i> |
470 |
</pre> |
471 |
|
472 |
<p> |
473 |
If you want to use the binary package, even if the versions don't match, use |
474 |
<c>--usepkgonly</c> (<c>-K</c> in short). |
475 |
</p> |
476 |
|
477 |
<pre caption="Installing the prebuilt package for gnumeric"> |
478 |
# <i>emerge --usepkgonly gnumeric</i> |
479 |
</pre> |
480 |
|
481 |
<p> |
482 |
If you don't have the prebuilt package on your system yet, you can have |
483 |
<c>emerge</c> download it from a mirror, defined in the <c>PORTAGE_BINHOST</c> |
484 |
variable declared in <path>/etc/make.conf</path>. |
485 |
</p> |
486 |
|
487 |
<p> |
488 |
To download the binary package in case this package doesn't exist on |
489 |
your system already, use <c>--getbinpkg</c> (<c>-g</c> in short): |
490 |
</p> |
491 |
|
492 |
<pre caption="Downloading and installing a prebuilt package for gnumeric"> |
493 |
# <i>emerge --getbinpkg gnumeric</i> |
494 |
</pre> |
495 |
|
496 |
<p> |
497 |
This will download the package and the package-related information for you and |
498 |
install it on your system, together with the dependencies. If you want to see |
499 |
what dependencies will be installed with it, use the <c>--pretend</c> option |
500 |
(<c>-p</c> in short): |
501 |
</p> |
502 |
|
503 |
<pre caption="Pretending to download the prebuilt packages for gnumeric"> |
504 |
# <i>emerge --getbinpkg --pretend gnumeric</i> |
505 |
</pre> |
506 |
|
507 |
<p> |
508 |
You can also opt to download the prebuilt package (and the package-related |
509 |
information) <e>without</e> checking the information on your local system and |
510 |
<e>without</e> using the prebuilt package already on your system (if |
511 |
applicable), use the <c>--getbinpkgonly</c> option (<c>-G</c> in short): |
512 |
</p> |
513 |
|
514 |
<pre caption="Installing a prebuilt package without using local information"> |
515 |
# <i>emerge --getbinpkgonly gnumeric</i> |
516 |
</pre> |
517 |
|
518 |
<p> |
519 |
You can also opt to install a specific version of a package. |
520 |
For instance, if you want to install a gnumeric version older than 1.2 -- for |
521 |
any reason whatsoever :) you would type: |
522 |
</p> |
523 |
|
524 |
<pre caption="Installing a specific gnumeric version"> |
525 |
# <i>emerge --usepkg "<gnumeric-1.2"</i> |
526 |
</pre> |
527 |
|
528 |
<p> |
529 |
Other possibilities are of course ">" (later version) and "=" (the exact |
530 |
version). |
531 |
</p> |
532 |
|
533 |
|
534 |
</body> |
535 |
</subsection> |
536 |
<subsection> |
537 |
<title>Working with Dependencies</title> |
538 |
<body> |
539 |
|
540 |
<p> |
541 |
Portage has an extensive support for dependency handling. Although you usually |
542 |
don't need to even think about this (as dependencies are automatically handled |
543 |
by Portage) some users might want to know how you can work with <c>emerge</c> |
544 |
and dependencies. |
545 |
</p> |
546 |
|
547 |
<p> |
548 |
For instance, if you want Portage to pretend that none of the dependencies of a |
549 |
package are installed, you can use <c>--emptytree</c> (<c>-e</c> in short). This |
550 |
is useful with <c>--pretend</c> to display a complete tree of dependencies for |
551 |
any particular package. Without <c>--pretend</c>, <c>emerge</c> will (re)compile |
552 |
all listed packages. However, <c>glibc</c> will <e>not</e> be listed as |
553 |
dependency for safety reasons. |
554 |
</p> |
555 |
|
556 |
<pre caption="Show all dependencies of gnumeric"> |
557 |
# <i>emerge --emptytree --pretend gnumeric</i> |
558 |
</pre> |
559 |
|
560 |
<p> |
561 |
Another argument is <c>--nodeps</c>, which will ask Portage to try install the |
562 |
given package without taking care of the dependencies. It is trivial that this |
563 |
can lead to failures. |
564 |
</p> |
565 |
|
566 |
<pre caption="Installing gnumeric without taking care of the dependencies"> |
567 |
# <i>emerge --nodeps gnumeric</i> |
568 |
</pre> |
569 |
|
570 |
<p> |
571 |
The opposite of <c>--nodeps</c> is <c>--onlydeps</c>, which will have Portage |
572 |
install all dependencies of a given package, but not the package itself: |
573 |
</p> |
574 |
|
575 |
<pre caption="Installing the dependencies of gnumeric"> |
576 |
# <i>emerge --onlydeps gnumeric</i> |
577 |
</pre> |
578 |
|
579 |
</body> |
580 |
</subsection> |
581 |
<subsection> |
582 |
<title>Updating your System</title> |
583 |
<body> |
584 |
|
585 |
<p> |
586 |
Portage knows two special tags to denote a set of software packages: |
587 |
<e>system</e> and <e>world</e>. You have already seen the former while |
588 |
installing Gentoo if you didn't use a <e>stage3</e> installation. To refresh |
589 |
things: <e>system</e> is the collection of <e>core</e> packages, necessary to |
590 |
have a working Gentoo system. |
591 |
</p> |
592 |
|
593 |
<p> |
594 |
The <e>world</e> tag consists of all software you have installed yourself on |
595 |
your system plus the <e>system</e> information. In other words, every time you |
596 |
emerge a package using <c>emerge <package-name></c>, the |
597 |
<c><package-name></c> is registered in the <e>world</e> file |
598 |
(<path>/var/cache/edb/world</path>). Dependencies are <e>not</e> part of the |
599 |
<e>world</e> file, but we will get to that later. |
600 |
</p> |
601 |
|
602 |
<p> |
603 |
If you want to update the system packages, use the <c>--update</c> option |
604 |
(<c>-u</c> in short): |
605 |
</p> |
606 |
|
607 |
<pre caption="Updating the system packages"> |
608 |
# <i>emerge --update system</i> |
609 |
</pre> |
610 |
|
611 |
<p> |
612 |
An identical approach can be used for the world packages: |
613 |
</p> |
614 |
|
615 |
<pre caption="Updating your entire system"> |
616 |
# <i>emerge --update world</i> |
617 |
</pre> |
618 |
|
619 |
<p> |
620 |
Again, if you want to see what <c>emerge</c> wants to update, use the |
621 |
<c>--pretend</c> option together with the <c>--update</c> option: |
622 |
</p> |
623 |
|
624 |
<pre caption="Pretending to update your entire system"> |
625 |
# <i>emerge --pretend --update world</i> |
626 |
<comment>(Some output removed to improve readability)</comment> |
627 |
[ebuild U ] net-misc/wget-1.9-r1 [1.9] |
628 |
[ebuild UD] media-video/dvdauthor-0.5.0 [0.5.3] |
629 |
[ebuild U ] net-analyzer/ethereal-0.9.16 [0.9.14] |
630 |
</pre> |
631 |
|
632 |
<p> |
633 |
Right next to the word "ebuild" you will notice a letter (or combination of |
634 |
letters) which gives you more information about the package: |
635 |
</p> |
636 |
|
637 |
<ul> |
638 |
<li> |
639 |
<e>B</e> (blocks) The package listed to the left is blocking the emerge of |
640 |
the package listed to the right |
641 |
</li> |
642 |
<li> |
643 |
<e>N</e> (new) The package is new to your system and will be emerged for the |
644 |
first time |
645 |
</li> |
646 |
<li> |
647 |
<e>R</e> (reemerge) The package isn't new, but needs to be reemerged |
648 |
</li> |
649 |
<li> |
650 |
<e>F</e> (fetch) The package requires that you download the source code |
651 |
manually (for instance due to licencing issues) |
652 |
</li> |
653 |
<li> |
654 |
<e>U</e> (update) The package already exists on your system but will be |
655 |
upgraded |
656 |
</li> |
657 |
<li> |
658 |
<e>UD</e> (downgrade) The package already exists on your system but will be |
659 |
downgraded |
660 |
</li> |
661 |
<li> |
662 |
<e>U-</e> (slot warning) The package you have installed on your system |
663 |
is listed as a package that can not coexist with a different version, but |
664 |
your update does. The update will be installed and the older version will be |
665 |
removed. |
666 |
</li> |
667 |
</ul> |
668 |
|
669 |
<p> |
670 |
In certain cases, an update may mean a downgrade (i.e. install an older version |
671 |
instead of a newer version). If you don't want this to happen, use the |
672 |
<c>--upgradeonly</c> option (<c>-U</c> in short): |
673 |
</p> |
674 |
|
675 |
<pre caption="Upgrading your entire system"> |
676 |
# <i>emerge --update --upgradeonly world</i> |
677 |
</pre> |
678 |
|
679 |
<p> |
680 |
Of course, we are talking here about <e>system</e> and <e>world</e>, but you can |
681 |
perform the same actions for individual software packages. |
682 |
</p> |
683 |
|
684 |
</body> |
685 |
</subsection> |
686 |
<subsection> |
687 |
<title>Removing Software</title> |
688 |
<body> |
689 |
|
690 |
<p> |
691 |
If you want to remove software from your system, you can use the <c>unmerge</c> |
692 |
option (<c>-C</c> - capital C - in short): |
693 |
</p> |
694 |
|
695 |
<pre caption="Uninstalling software"> |
696 |
# <i>emerge unmerge gnumeric</i> |
697 |
</pre> |
698 |
|
699 |
<p> |
700 |
If you want to test a removal (but not perform it), you can use <c>--pretend</c> |
701 |
again: |
702 |
</p> |
703 |
|
704 |
<pre caption="Pretending to uninstall software"> |
705 |
# <i>emerge --pretend unmerge gnumeric</i> |
706 |
</pre> |
707 |
|
708 |
<warn> |
709 |
Portage doesn't verify if a package is a dependency for another |
710 |
installed package. It also doesn't warn you if the package is part of |
711 |
<e>system</e>, i.e. a core application necessary for the correct functioning of |
712 |
your system! |
713 |
</warn> |
714 |
|
715 |
<p> |
716 |
Once the unmerge begins you will see a long list of filenames belonging to the |
717 |
package. Some of these filenames will have a flag displayed to the |
718 |
left of the filename. The flags <c>!mtime</c>, <c>!empty</c>, and <c>cfgpro</c> |
719 |
specify reasons why certain files are not being removed while the package is. |
720 |
Files listed without any of these three flags are removed from the |
721 |
filesystem successfully. The three flags specify the following reasons: |
722 |
</p> |
723 |
|
724 |
<ul> |
725 |
<li> |
726 |
<c>!mtime</c> : The listed file has been changed since it was installed, |
727 |
probably by you or some tool |
728 |
</li> |
729 |
<li> |
730 |
<c>!empty</c> : The listed directory is not empty |
731 |
</li> |
732 |
<li> |
733 |
<c>cfgpro</c> : This file is located inside a protected directory and will |
734 |
not be touched for safety |
735 |
</li> |
736 |
</ul> |
737 |
|
738 |
</body> |
739 |
</subsection> |
740 |
</section> |
741 |
<section> |
742 |
<title>Software Availability</title> |
743 |
<subsection> |
744 |
<title>ARCH or not?</title> |
745 |
<body> |
746 |
|
747 |
<p> |
748 |
Gentoo places its packages in two possible stadia called <e>ARCH</e> and |
749 |
<e>~ARCH</e>. Don't take this literally: the stadia depend on the architecture |
750 |
you are using. In other words, for x86-based systems you have <e>x86</e> and |
751 |
<e>~x86</e>, for ppc-based systems you have <e>ppc</e> and <e>~ppc</e> etc. |
752 |
</p> |
753 |
|
754 |
<p> |
755 |
The <e>~ARCH</e> stadium means that the package works for the developer in |
756 |
charge of the package, but that the package hasn't been tested thoroughly enough |
757 |
by the community to be placed in <e>ARCH</e>. <e>~ARCH</e> packages usually go |
758 |
to <e>ARCH</e> after being bugfree for a sufficient amount of time. |
759 |
</p> |
760 |
|
761 |
<p> |
762 |
Your system will use <e>ARCH</e> packages per default. If you want to live on |
763 |
the edge, don't mind having a broken package once in a while, and you like |
764 |
submitting bugreports to <uri |
765 |
link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use |
766 |
<e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system, |
767 |
edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that |
768 |
it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.). |
769 |
</p> |
770 |
|
771 |
<p> |
772 |
If you want to update your system now, you will notice that <e>a lot</e> of |
773 |
packages will be updated! |
774 |
</p> |
775 |
|
776 |
</body> |
777 |
</subsection> |
778 |
<subsection> |
779 |
<title>Masked Packages</title> |
780 |
<body> |
781 |
|
782 |
<p> |
783 |
When you want to install a package, you might come across the following message: |
784 |
</p> |
785 |
|
786 |
<pre caption="Message about masked packages"> |
787 |
Calculating dependencies |
788 |
!!! <comment>all ebuilds that could satisfy </comment><your package><comment> have been masked.</comment> |
789 |
</pre> |
790 |
|
791 |
<p> |
792 |
A package can be masked due to two reasons: |
793 |
</p> |
794 |
|
795 |
<ol> |
796 |
<li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li> |
797 |
<li>The package is hard-masked explicitly</li> |
798 |
</ol> |
799 |
|
800 |
<p> |
801 |
If the package is masked because of the first reason, and you <e>really</e> want |
802 |
to install it (knowing that there <e>is</e> a reason why it isn't available in |
803 |
<e>ARCH</e>), you can temporarily accept <e>~ARCH</e> packages: |
804 |
</p> |
805 |
|
806 |
<pre caption="Temporarily accepting ~ARCH packages"> |
807 |
# <i>ACCEPT_KEYWORDS="~x86" emerge gnumeric</i> |
808 |
</pre> |
809 |
|
810 |
<p> |
811 |
A package is hardmasked if it is listed in |
812 |
<path>/usr/portage/profiles/package.mask</path>. If you read this file, you |
813 |
will also read the reason why the package is hardmasked (it is usually added as |
814 |
a comment). If you want to install the package nevertheless (despite all the |
815 |
possible warnings we could ever throw at your head about "breaking your system", |
816 |
"breaks other packages", or "badly needs testing"), create the |
817 |
<path>/etc/portage/package.unmask</path> file and list the package in it (use |
818 |
the same format as is used in <path>/usr/portage/profiles/package.mask</path>). |
819 |
</p> |
820 |
|
821 |
<p> |
822 |
Do <e>not</e> alter the <path>/usr/portage/profiles/package.mask</path> file as |
823 |
all changes are undone the next time you update your Portage tree. |
824 |
</p> |
825 |
|
826 |
<p> |
827 |
Another trick to circumvent the "masked package" problem is to install the |
828 |
package using the full path. This will ignore both the <c>ACCEPT_KEYWORD</c> |
829 |
settings and the <path>package.mask</path> listing. |
830 |
</p> |
831 |
|
832 |
<pre caption="Installing a package without checking for stadium / masking"> |
833 |
# <i>emerge /usr/portage/app-office/gnumeric/gnumeric-1.2.0.ebuild</i> |
834 |
</pre> |
835 |
|
836 |
</body> |
837 |
</subsection> |
838 |
<subsection> |
839 |
<title>Blocked Packages</title> |
840 |
<body> |
841 |
|
842 |
<p> |
843 |
You have a situation when you receive the following error on your screen: |
844 |
</p> |
845 |
|
846 |
<pre caption="Blocking package"> |
847 |
[blocks B ] gnome-base/bonobo-activation (from pkg gnome-base/libbonobo-2.4.0) |
848 |
</pre> |
849 |
|
850 |
<p> |
851 |
In the above example, the package <c>bonobo-activation</c> is blocking the |
852 |
emerge of <c>libbonobo</c>. To resolve this issue, remove the |
853 |
<c>bonobo-activation</c> package and continue: |
854 |
</p> |
855 |
|
856 |
<pre caption="Resolving a blocking situation"> |
857 |
# <i>emerge unmerge bonobo-activation</i> |
858 |
</pre> |
859 |
|
860 |
</body> |
861 |
</subsection> |
862 |
</section> |
863 |
</sections> |