1 |
swift |
1.18 |
<?xml version='1.0' encoding='UTF-8'?> |
2 |
|
|
<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
3 |
|
|
|
4 |
swift |
1.1 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
5 |
fox2mike |
1.55 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
6 |
swift |
1.1 |
|
7 |
swift |
1.76 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.75 2010/10/30 01:54:20 nightmorph Exp $ --> |
8 |
swift |
1.1 |
|
9 |
|
|
<sections> |
10 |
swift |
1.43 |
|
11 |
neysx |
1.60 |
<abstract> |
12 |
|
|
This chapter explains the "simple" steps a user definitely needs to know to |
13 |
|
|
maintain the software on his system. |
14 |
|
|
</abstract> |
15 |
|
|
|
16 |
swift |
1.76 |
<version>3</version> |
17 |
|
|
<date>2011-08-12</date> |
18 |
swift |
1.43 |
|
19 |
swift |
1.1 |
<section> |
20 |
swift |
1.39 |
<title>Welcome to Portage</title> |
21 |
swift |
1.1 |
<body> |
22 |
|
|
|
23 |
swift |
1.2 |
<p> |
24 |
swift |
1.39 |
Portage is probably Gentoo's most notable innovation in software management. |
25 |
|
|
With its high flexibility and enormous amount of features it is frequently seen |
26 |
|
|
as the best software management tool available for Linux. |
27 |
swift |
1.2 |
</p> |
28 |
|
|
|
29 |
|
|
<p> |
30 |
swift |
1.39 |
Portage is completely written in <uri link="http://www.python.org">Python</uri> |
31 |
|
|
and <uri link="http://www.gnu.org/software/bash">Bash</uri> and therefore fully |
32 |
|
|
visible to the users as both are scripting languages. |
33 |
swift |
1.2 |
</p> |
34 |
|
|
|
35 |
|
|
<p> |
36 |
swift |
1.39 |
Most users will work with Portage through the <c>emerge</c> tool. This chapter |
37 |
|
|
is not meant to duplicate the information available from the emerge man page. |
38 |
|
|
For a complete rundown of emerge's options, please consult the man page: |
39 |
swift |
1.2 |
</p> |
40 |
|
|
|
41 |
swift |
1.39 |
<pre caption="Reading the emerge man page"> |
42 |
|
|
$ <i>man emerge</i> |
43 |
swift |
1.2 |
</pre> |
44 |
|
|
|
45 |
|
|
</body> |
46 |
swift |
1.1 |
</section> |
47 |
|
|
<section> |
48 |
swift |
1.39 |
<title>The Portage Tree</title> |
49 |
swift |
1.1 |
<subsection> |
50 |
swift |
1.39 |
<title>Ebuilds</title> |
51 |
swift |
1.2 |
<body> |
52 |
|
|
|
53 |
|
|
<p> |
54 |
swift |
1.39 |
When we talk about packages, we often mean software titles that are available to |
55 |
|
|
the Gentoo users through the Portage tree. The Portage tree is a collection of |
56 |
|
|
<e>ebuilds</e>, files that contain all information Portage needs to maintain |
57 |
|
|
software (install, search, query, ...). These ebuilds reside in |
58 |
|
|
<path>/usr/portage</path> by default. |
59 |
swift |
1.2 |
</p> |
60 |
|
|
|
61 |
|
|
<p> |
62 |
swift |
1.39 |
Whenever you ask Portage to perform some action regarding software titles, it |
63 |
|
|
will use the ebuilds on your system as a base. It is therefore important that |
64 |
|
|
you regularly update the ebuilds on your system so Portage knows about new |
65 |
|
|
software, security updates, etc. |
66 |
swift |
1.2 |
</p> |
67 |
|
|
|
68 |
|
|
</body> |
69 |
|
|
</subsection> |
70 |
|
|
<subsection> |
71 |
swift |
1.39 |
<title>Updating the Portage Tree</title> |
72 |
swift |
1.1 |
<body> |
73 |
swift |
1.2 |
|
74 |
|
|
<p> |
75 |
swift |
1.39 |
The Portage tree is usually updated with <uri |
76 |
yoswink |
1.50 |
link="http://rsync.samba.org/">rsync</uri>, a fast incremental file transfer |
77 |
swift |
1.39 |
utility. Updating is fairly simple as the <c>emerge</c> command provides a |
78 |
|
|
front-end for rsync: |
79 |
swift |
1.2 |
</p> |
80 |
|
|
|
81 |
swift |
1.39 |
<pre caption="Updating the Portage tree"> |
82 |
cam |
1.38 |
# <i>emerge --sync</i> |
83 |
swift |
1.2 |
</pre> |
84 |
|
|
|
85 |
|
|
<p> |
86 |
swift |
1.39 |
If you are unable to rsync due to firewall restrictions you can still update |
87 |
swift |
1.40 |
your Portage tree by using our daily generated Portage tree snapshots. The |
88 |
swift |
1.39 |
<c>emerge-webrsync</c> tool automatically fetches and installs the latest |
89 |
|
|
snapshot on your system: |
90 |
swift |
1.2 |
</p> |
91 |
|
|
|
92 |
swift |
1.39 |
<pre caption="Running emerge-webrsync"> |
93 |
swift |
1.2 |
# <i>emerge-webrsync</i> |
94 |
|
|
</pre> |
95 |
swift |
1.1 |
|
96 |
|
|
</body> |
97 |
|
|
</subsection> |
98 |
|
|
</section> |
99 |
|
|
<section> |
100 |
|
|
<title>Maintaining Software</title> |
101 |
|
|
<subsection> |
102 |
swift |
1.39 |
<title>Searching for Software</title> |
103 |
swift |
1.1 |
<body> |
104 |
|
|
|
105 |
swift |
1.3 |
<p> |
106 |
swift |
1.39 |
To search through the Portage tree after software titles, you can use |
107 |
cam |
1.47 |
<c>emerge</c> built-in search capabilities. By default, <c>emerge --search</c> |
108 |
neysx |
1.42 |
returns the names of packages whose title matches (either fully or partially) |
109 |
swift |
1.39 |
the given search term. |
110 |
swift |
1.3 |
</p> |
111 |
|
|
|
112 |
|
|
<p> |
113 |
swift |
1.39 |
For instance, to search for all packages who have "pdf" in their name: |
114 |
swift |
1.3 |
</p> |
115 |
|
|
|
116 |
swift |
1.39 |
<pre caption="Searching for pdf-named packages"> |
117 |
cam |
1.47 |
$ <i>emerge --search pdf</i> |
118 |
swift |
1.39 |
</pre> |
119 |
|
|
|
120 |
swift |
1.3 |
<p> |
121 |
swift |
1.39 |
If you want to search through the descriptions as well you can use the |
122 |
|
|
<c>--searchdesc</c> (or <c>-S</c>) switch: |
123 |
swift |
1.3 |
</p> |
124 |
|
|
|
125 |
swift |
1.39 |
<pre caption="Searching for pdf-related packages"> |
126 |
|
|
$ <i>emerge --searchdesc pdf</i> |
127 |
|
|
</pre> |
128 |
|
|
|
129 |
swift |
1.3 |
<p> |
130 |
swift |
1.39 |
When you take a look at the output, you'll notice that it gives you a lot of |
131 |
|
|
information. The fields are clearly labelled so we won't go further into their |
132 |
|
|
meanings: |
133 |
swift |
1.3 |
</p> |
134 |
|
|
|
135 |
swift |
1.49 |
<pre caption="Example 'emerge --search' output"> |
136 |
swift |
1.39 |
* net-print/cups-pdf |
137 |
|
|
Latest version available: 1.5.2 |
138 |
|
|
Latest version installed: [ Not Installed ] |
139 |
|
|
Size of downloaded files: 15 kB |
140 |
|
|
Homepage: http://cip.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/ |
141 |
|
|
Description: Provides a virtual printer for CUPS to produce PDF files. |
142 |
|
|
License: GPL-2 |
143 |
|
|
</pre> |
144 |
|
|
|
145 |
swift |
1.3 |
</body> |
146 |
|
|
</subsection> |
147 |
|
|
<subsection> |
148 |
swift |
1.39 |
<title>Installing Software</title> |
149 |
swift |
1.3 |
<body> |
150 |
|
|
|
151 |
|
|
<p> |
152 |
swift |
1.39 |
Once you've found a software title to your liking, you can easily install it |
153 |
|
|
with <c>emerge</c>: just add the package name. For instance, to install |
154 |
swift |
1.3 |
<c>gnumeric</c>: |
155 |
|
|
</p> |
156 |
|
|
|
157 |
swift |
1.39 |
<pre caption="Installing gnumeric"> |
158 |
swift |
1.3 |
# <i>emerge gnumeric</i> |
159 |
|
|
</pre> |
160 |
|
|
|
161 |
|
|
<p> |
162 |
swift |
1.39 |
Since many applications depend on each other, any attempt to install a certain |
163 |
|
|
software package might result in the installation of several dependencies as |
164 |
|
|
well. Don't worry, Portage handles dependencies well. If you want to find out |
165 |
|
|
what Portage <e>would</e> install when you ask it to install a certain package, |
166 |
|
|
add the <c>--pretend</c> switch. For instance: |
167 |
swift |
1.3 |
</p> |
168 |
|
|
|
169 |
swift |
1.39 |
<pre caption="Pretend to install gnumeric"> |
170 |
swift |
1.3 |
# <i>emerge --pretend gnumeric</i> |
171 |
|
|
</pre> |
172 |
|
|
|
173 |
|
|
<p> |
174 |
swift |
1.39 |
When you ask Portage to install a package, it will download the necessary source |
175 |
|
|
code from the internet (if necessary) and store it by default in |
176 |
|
|
<path>/usr/portage/distfiles</path>. After this it will unpack, compile and |
177 |
|
|
install the package. If you want Portage to only download the sources without |
178 |
|
|
installing them, add the <c>--fetchonly</c> option to the <c>emerge</c> command: |
179 |
swift |
1.3 |
</p> |
180 |
|
|
|
181 |
swift |
1.39 |
<pre caption="Download the sourcecode for gnumeric"> |
182 |
swift |
1.3 |
# <i>emerge --fetchonly gnumeric</i> |
183 |
|
|
</pre> |
184 |
|
|
|
185 |
|
|
</body> |
186 |
|
|
</subsection> |
187 |
|
|
<subsection> |
188 |
neysx |
1.52 |
<title>Finding Installed Package Documentation</title> |
189 |
|
|
<body> |
190 |
|
|
|
191 |
|
|
<p> |
192 |
|
|
Many packages come with their own documentation. Sometimes, the <c>doc</c> USE |
193 |
|
|
flag determines whether the package documentation should be installed or not. |
194 |
|
|
You can check the existence of a <c>doc</c> USE flag with the <c>emerge -vp |
195 |
|
|
<package name></c> command. |
196 |
|
|
</p> |
197 |
|
|
|
198 |
|
|
<pre caption="Checking the existence of a doc USE flag"> |
199 |
|
|
<comment>(alsa-lib is just an example, of course.)</comment> |
200 |
|
|
# <i>emerge -vp alsa-lib</i> |
201 |
nightmorph |
1.62 |
[ebuild N ] media-libs/alsa-lib-1.0.14_rc1 -debug +doc 698 kB |
202 |
neysx |
1.52 |
</pre> |
203 |
|
|
|
204 |
|
|
<p> |
205 |
jkt |
1.67 |
The best way of enabling the <c>doc</c> USE flag is doing it on a per-package |
206 |
nightmorph |
1.68 |
basis via <path>/etc/portage/package.use</path>, so that you get documentation |
207 |
|
|
only for packages that you are interested in. Enabling this flag globally is |
208 |
|
|
known to cause problems with circular dependencies. For more information, please |
209 |
|
|
read the <uri link="?part=2&chap=2">USE Flags</uri> chapter. |
210 |
neysx |
1.52 |
</p> |
211 |
|
|
|
212 |
|
|
<p> |
213 |
|
|
Once the package installed, its documentation is generally found in a |
214 |
|
|
subdirectory named after the package under the <path>/usr/share/doc</path> |
215 |
|
|
directory. You can also list all installed files with the <c>equery</c> tool |
216 |
|
|
which is part of the <c>app-portage/gentoolkit</c> <uri |
217 |
|
|
link="/doc/en/gentoolkit.xml">package</uri>. |
218 |
|
|
</p> |
219 |
|
|
|
220 |
|
|
<pre caption="Locating package documentation"> |
221 |
nightmorph |
1.62 |
# <i>ls -l /usr/share/doc/alsa-lib-1.0.14_rc1</i> |
222 |
neysx |
1.52 |
total 28 |
223 |
|
|
-rw-r--r-- 1 root root 669 May 17 21:54 ChangeLog.gz |
224 |
|
|
-rw-r--r-- 1 root root 9373 May 17 21:54 COPYING.gz |
225 |
|
|
drwxr-xr-x 2 root root 8560 May 17 21:54 html |
226 |
|
|
-rw-r--r-- 1 root root 196 May 17 21:54 TODO.gz |
227 |
|
|
|
228 |
|
|
<comment>(Alternatively, use equery to locate interesting files:)</comment> |
229 |
|
|
# <i>equery files alsa-lib | less</i> |
230 |
nightmorph |
1.62 |
media-libs/alsa-lib-1.0.14_rc1 |
231 |
|
|
* Contents of media-libs/alsa-lib-1.0.14_rc1: |
232 |
neysx |
1.52 |
/usr |
233 |
|
|
/usr/bin |
234 |
|
|
/usr/bin/alsalisp |
235 |
neysx |
1.53 |
<comment>(Output truncated)</comment> |
236 |
neysx |
1.52 |
</pre> |
237 |
|
|
|
238 |
|
|
</body> |
239 |
|
|
</subsection> |
240 |
|
|
<subsection> |
241 |
swift |
1.39 |
<title>Removing Software</title> |
242 |
swift |
1.3 |
<body> |
243 |
|
|
|
244 |
|
|
<p> |
245 |
swift |
1.39 |
When you want to remove a software package from your system, use <c>emerge |
246 |
cam |
1.47 |
--unmerge</c>. This will tell Portage to remove all files installed by that |
247 |
swift |
1.39 |
package from your system <e>except</e> the configuration files of that |
248 |
|
|
application if you have altered those after the installation. Leaving the |
249 |
|
|
configuration files allows you to continue working with the package if you ever |
250 |
|
|
decide to install it again. |
251 |
swift |
1.3 |
</p> |
252 |
|
|
|
253 |
|
|
<p> |
254 |
swift |
1.39 |
However, a <brite>big warning</brite> applies: Portage will <e>not</e> check if |
255 |
|
|
the package you want to remove is required by another package. It will however |
256 |
|
|
warn you when you want to remove an important package that breaks your system |
257 |
|
|
if you unmerge it. |
258 |
swift |
1.3 |
</p> |
259 |
|
|
|
260 |
swift |
1.39 |
<pre caption="Removing gnumeric from the system"> |
261 |
cam |
1.47 |
# <i>emerge --unmerge gnumeric</i> |
262 |
swift |
1.3 |
</pre> |
263 |
|
|
|
264 |
|
|
<p> |
265 |
swift |
1.39 |
When you remove a package from your system, the dependencies of that package |
266 |
|
|
that were installed automatically when you installed the software are left. To |
267 |
|
|
have Portage locate all dependencies that can now be removed, use |
268 |
cam |
1.47 |
<c>emerge</c>'s <c>--depclean</c> functionality. We will talk about this later |
269 |
|
|
on. |
270 |
swift |
1.3 |
</p> |
271 |
|
|
|
272 |
swift |
1.39 |
</body> |
273 |
|
|
</subsection> |
274 |
|
|
<subsection> |
275 |
|
|
<title>Updating your System</title> |
276 |
|
|
<body> |
277 |
swift |
1.32 |
|
278 |
swift |
1.3 |
<p> |
279 |
swift |
1.39 |
To keep your system in perfect shape (and not to mention install the latest |
280 |
|
|
security updates) you need to update your system regularly. Since Portage only |
281 |
|
|
checks the ebuilds in your Portage tree you first have to update your Portage |
282 |
|
|
tree. When your Portage tree is updated, you can update your system with |
283 |
swift |
1.57 |
<c>emerge --update world</c>. In the next example, we'll also use the |
284 |
|
|
<c>--ask</c> switch which will tell Portage to display the list of packages it |
285 |
|
|
wants to upgrade and ask you if you want to continue: |
286 |
swift |
1.3 |
</p> |
287 |
|
|
|
288 |
swift |
1.39 |
<pre caption="Updating your system"> |
289 |
swift |
1.57 |
# <i>emerge --update --ask world</i> |
290 |
swift |
1.3 |
</pre> |
291 |
|
|
|
292 |
|
|
<p> |
293 |
swift |
1.39 |
Portage will then search for newer version of the applications you have |
294 |
|
|
installed. However, it will only verify the versions for the applications you |
295 |
nightmorph |
1.61 |
have <e>explicitly</e> installed (the applications listed in |
296 |
|
|
<path>/var/lib/portage/world</path>) - it does not thoroughly check their |
297 |
|
|
dependencies. If you want to update <e>every single package</e> on your system, |
298 |
|
|
add the <c>--deep</c> argument: |
299 |
swift |
1.3 |
</p> |
300 |
|
|
|
301 |
swift |
1.39 |
<pre caption="Updating your entire system"> |
302 |
|
|
# <i>emerge --update --deep world</i> |
303 |
swift |
1.3 |
</pre> |
304 |
|
|
|
305 |
|
|
<p> |
306 |
swift |
1.54 |
Since security updates also happen in packages you have not explicitly installed |
307 |
|
|
on your system (but that are pulled in as dependencies of other programs), it |
308 |
|
|
is recommended to run this command once in a while. |
309 |
|
|
</p> |
310 |
|
|
|
311 |
|
|
<p> |
312 |
swift |
1.39 |
If you have altered any of your <uri link="?part=2&chap=2">USE flags</uri> |
313 |
|
|
lately you might want to add <c>--newuse</c> as well. Portage will then verify |
314 |
|
|
if the change requires the installation of new packages or recompilation of |
315 |
|
|
existing ones: |
316 |
swift |
1.3 |
</p> |
317 |
|
|
|
318 |
swift |
1.39 |
<pre caption="Performing a full update"> |
319 |
|
|
# <i>emerge --update --deep --newuse world</i> |
320 |
swift |
1.3 |
</pre> |
321 |
|
|
|
322 |
swift |
1.1 |
</body> |
323 |
|
|
</subsection> |
324 |
|
|
<subsection> |
325 |
neysx |
1.51 |
<title>Metapackages</title> |
326 |
swift |
1.11 |
<body> |
327 |
|
|
|
328 |
|
|
<p> |
329 |
swift |
1.39 |
Some packages in the Portage tree don't have any real content but are used to |
330 |
nightmorph |
1.73 |
install a collection of packages. For instance, the <c>kde-meta</c> package will |
331 |
swift |
1.39 |
install a complete KDE environment on your system by pulling in various |
332 |
|
|
KDE-related packages as dependencies. |
333 |
swift |
1.11 |
</p> |
334 |
|
|
|
335 |
|
|
<p> |
336 |
swift |
1.39 |
If you ever want to remove such a package from your system, running <c>emerge |
337 |
cam |
1.47 |
--unmerge</c> on the package won't have much effect as the dependencies remain |
338 |
|
|
on the system. |
339 |
swift |
1.11 |
</p> |
340 |
|
|
|
341 |
|
|
<p> |
342 |
swift |
1.39 |
Portage has the functionality to remove orphaned dependencies as well, but since |
343 |
|
|
the availability of software is dynamically dependent you first need to update |
344 |
|
|
your entire system fully, including the new changes you applied when changing |
345 |
cam |
1.47 |
USE flags. After this you can run <c>emerge --depclean</c> to remove the |
346 |
|
|
orphaned dependencies. When this is done, you need to rebuild the applications |
347 |
|
|
that were dynamically linked to the now-removed software titles but don't |
348 |
|
|
require them anymore. |
349 |
swift |
1.11 |
</p> |
350 |
|
|
|
351 |
|
|
<p> |
352 |
swift |
1.39 |
All this is handled with the following three commands: |
353 |
swift |
1.11 |
</p> |
354 |
|
|
|
355 |
swift |
1.39 |
<pre caption="Removing orphaned dependencies"> |
356 |
|
|
# <i>emerge --update --deep --newuse world</i> |
357 |
cam |
1.47 |
# <i>emerge --depclean</i> |
358 |
swift |
1.39 |
# <i>revdep-rebuild</i> |
359 |
swift |
1.11 |
</pre> |
360 |
|
|
|
361 |
swift |
1.34 |
<p> |
362 |
swift |
1.39 |
<c>revdep-rebuild</c> is provided by the <c>gentoolkit</c> package; don't forget |
363 |
|
|
to emerge it first: |
364 |
swift |
1.34 |
</p> |
365 |
|
|
|
366 |
swift |
1.39 |
<pre caption="Installing the gentoolkit package"> |
367 |
|
|
# <i>emerge gentoolkit</i> |
368 |
swift |
1.34 |
</pre> |
369 |
|
|
|
370 |
swift |
1.11 |
</body> |
371 |
|
|
</subsection> |
372 |
swift |
1.39 |
</section> |
373 |
nightmorph |
1.74 |
<section id="license"> |
374 |
|
|
<title>Licenses</title> |
375 |
|
|
<subsection> |
376 |
|
|
<body> |
377 |
|
|
|
378 |
|
|
<p> |
379 |
|
|
Beginning with Portage version 2.1.7, you can accept or reject software |
380 |
|
|
installation based on its license. All packages in the tree contain a |
381 |
|
|
<c>LICENSE</c> entry in their ebuilds. Running <c>emerge --search |
382 |
|
|
packagename</c> will tell you the package's license. |
383 |
|
|
</p> |
384 |
|
|
|
385 |
|
|
<p> |
386 |
|
|
By default, Portage permits all licenses, except End User License Agreements |
387 |
|
|
(EULAs) that require reading and signing an acceptance agreement. |
388 |
|
|
</p> |
389 |
|
|
|
390 |
|
|
<p> |
391 |
|
|
The variable that controls permitted licenses is <c>ACCEPT_LICENSE</c>, which |
392 |
|
|
can be set in <path>/etc/make.conf</path>: |
393 |
|
|
</p> |
394 |
|
|
|
395 |
|
|
<pre caption="Default ACCEPT_LICENSE in /etc/make.conf"> |
396 |
|
|
ACCEPT_LICENSE="* -@EULA" |
397 |
|
|
</pre> |
398 |
|
|
|
399 |
|
|
<p> |
400 |
|
|
With this configuration, packages that require interaction during installation |
401 |
|
|
to approve their EULA <e>will not</e> be installed. Packages without an EULA |
402 |
|
|
<e>will</e> be installed. |
403 |
|
|
</p> |
404 |
|
|
|
405 |
|
|
<p> |
406 |
|
|
You can set <c>ACCEPT_LICENSE</c> globally in <path>/etc/make.conf</path>, or |
407 |
|
|
you can specify it on a per-package basis in |
408 |
|
|
<path>/etc/portage/package.license</path>. |
409 |
|
|
</p> |
410 |
|
|
|
411 |
|
|
<p> |
412 |
|
|
For example, if you want to allow the <c>truecrypt-2.7</c> license for |
413 |
|
|
<c>app-crypt/truecrypt</c>, add the following to |
414 |
|
|
<path>/etc/portage/package.license</path>: |
415 |
|
|
</p> |
416 |
|
|
|
417 |
|
|
<pre caption="Specifying a truecrypt license in package.license"> |
418 |
|
|
app-crypt/truecrypt truecrypt-2.7 |
419 |
|
|
</pre> |
420 |
|
|
|
421 |
|
|
<p> |
422 |
|
|
This permits installation of truecrypt versions that have the |
423 |
|
|
<c>truecrypt-2.7</c> license, but not versions with the <c>truecrypt-2.8</c> |
424 |
|
|
license. |
425 |
|
|
</p> |
426 |
|
|
|
427 |
|
|
<impo> |
428 |
|
|
Licenses are stored in <path>/usr/portage/licenses</path>, and license groups |
429 |
nightmorph |
1.75 |
are kept in <path>/usr/portage/profiles/license_groups</path>. The first entry |
430 |
|
|
of each line in CAPITAL letters is the name of the license group, and every |
431 |
|
|
entry after that is an individual license. |
432 |
nightmorph |
1.74 |
</impo> |
433 |
|
|
|
434 |
|
|
<p> |
435 |
|
|
License groups defined in <c>ACCEPT_LICENSE</c> are prefixed with an <b>@</b> |
436 |
|
|
sign. Here's an example of a system that globally permits the GPL-compatible |
437 |
|
|
license group, as well as a few other groups and individual licenses: |
438 |
|
|
</p> |
439 |
|
|
|
440 |
|
|
<pre caption="ACCEPT_LICENSE in /etc/make.conf"> |
441 |
|
|
ACCEPT_LICENSE="@GPL-COMPATIBLE @OSI-APPROVED @EULA atheros-hal BitstreamVera" |
442 |
|
|
</pre> |
443 |
|
|
|
444 |
|
|
<p> |
445 |
|
|
If you want only free software and documentation on your system, you might use |
446 |
|
|
the following setup: |
447 |
|
|
</p> |
448 |
|
|
|
449 |
|
|
<pre caption="Use only free licenses"> |
450 |
|
|
ACCEPT_LICENSE="-* @FREE" |
451 |
|
|
</pre> |
452 |
|
|
|
453 |
|
|
<p> |
454 |
|
|
In this case, "free" is mostly defined by the <uri |
455 |
|
|
link="http://www.gnu.org/philosophy/free-sw.html">FSF</uri> and <uri |
456 |
|
|
link="http://www.opensource.org/docs/osd">OSI</uri>. Any package whose license |
457 |
|
|
does not meet these requirements will not be installed on your system. |
458 |
|
|
</p> |
459 |
|
|
|
460 |
|
|
</body> |
461 |
|
|
</subsection> |
462 |
|
|
</section> |
463 |
swift |
1.39 |
<section> |
464 |
|
|
<title>When Portage is Complaining...</title> |
465 |
swift |
1.11 |
<subsection> |
466 |
swift |
1.39 |
<title>About SLOTs, Virtuals, Branches, Architectures and Profiles</title> |
467 |
swift |
1.1 |
<body> |
468 |
|
|
|
469 |
swift |
1.3 |
<p> |
470 |
swift |
1.39 |
As we stated before, Portage is extremely powerful and supports many features |
471 |
|
|
that other software management tools lack. To understand this, we explain a few |
472 |
neysx |
1.46 |
aspects of Portage without going into too much detail. |
473 |
swift |
1.3 |
</p> |
474 |
|
|
|
475 |
|
|
<p> |
476 |
swift |
1.39 |
With Portage different versions of a single package can coexist on a system. |
477 |
|
|
While other distributions tend to name their package to those versions (like |
478 |
|
|
<c>freetype</c> and <c>freetype2</c>) Portage uses a technology called |
479 |
|
|
<e>SLOT</e>s. An ebuild declares a certain SLOT for its version. Ebuilds with |
480 |
|
|
different SLOTs can coexist on the same system. For instance, the |
481 |
|
|
<c>freetype</c> package has ebuilds with <c>SLOT="1"</c> and <c>SLOT="2"</c>. |
482 |
swift |
1.3 |
</p> |
483 |
|
|
|
484 |
|
|
<p> |
485 |
swift |
1.39 |
There are also packages that provide the same functionality but are implemented |
486 |
|
|
differently. For instance, <c>metalogd</c>, <c>sysklogd</c> and <c>syslog-ng</c> |
487 |
|
|
are all system loggers. Applications that rely on the availability of "a system |
488 |
|
|
logger" cannot depend on, for instance, <c>metalogd</c>, as the other system |
489 |
|
|
loggers are as good a choice as any. Portage allows for <e>virtuals</e>: each |
490 |
|
|
system logger provides <c>virtual/syslog</c> so that applications can depend on |
491 |
|
|
<c>virtual/syslog</c>. |
492 |
swift |
1.3 |
</p> |
493 |
|
|
|
494 |
|
|
<p> |
495 |
swift |
1.39 |
Software in the Portage tree can reside in different branches. By default your |
496 |
|
|
system only accepts packages that Gentoo deems stable. Most new software titles, |
497 |
|
|
when committed, are added to the testing branch, meaning more testing needs to |
498 |
|
|
be done before it is marked as stable. Although you will see the ebuilds for |
499 |
|
|
those software in the Portage tree, Portage will not update them before they are |
500 |
|
|
placed in the stable branch. |
501 |
swift |
1.3 |
</p> |
502 |
|
|
|
503 |
|
|
<p> |
504 |
swift |
1.39 |
Some software is only available for a few architectures. Or the software doesn't |
505 |
|
|
work on the other architectures, or it needs more testing, or the developer that |
506 |
|
|
committed the software to the Portage tree is unable to verify if the package |
507 |
|
|
works on different architectures. |
508 |
swift |
1.25 |
</p> |
509 |
|
|
|
510 |
|
|
<p> |
511 |
swift |
1.39 |
Each Gentoo installation adheres to a certain <c>profile</c> which contains, |
512 |
|
|
amongst other information, the list of packages that are required for a system |
513 |
|
|
to function normally. |
514 |
swift |
1.3 |
</p> |
515 |
|
|
|
516 |
swift |
1.1 |
</body> |
517 |
|
|
</subsection> |
518 |
swift |
1.39 |
<subsection id="blocked"> |
519 |
|
|
<title>Blocked Packages</title> |
520 |
swift |
1.1 |
<body> |
521 |
|
|
|
522 |
swift |
1.39 |
<pre caption="Portage warning about blocked packages (with --pretend)"> |
523 |
fox2mike |
1.55 |
[blocks B ] mail-mta/ssmtp (is blocking mail-mta/postfix-2.2.2-r1) |
524 |
swift |
1.39 |
</pre> |
525 |
swift |
1.3 |
|
526 |
swift |
1.39 |
<pre caption="Portage warning about blocked packages (without --pretend)"> |
527 |
fox2mike |
1.55 |
!!! Error: the mail-mta/postfix package conflicts with another package. |
528 |
swift |
1.39 |
!!! both can't be installed on the same system together. |
529 |
|
|
!!! Please use 'emerge --pretend' to determine blockers. |
530 |
swift |
1.3 |
</pre> |
531 |
|
|
|
532 |
|
|
<p> |
533 |
swift |
1.41 |
Ebuilds contain specific fields that inform Portage about its dependencies. |
534 |
swift |
1.39 |
There are two possible dependencies: build dependencies, declared in |
535 |
|
|
<c>DEPEND</c> and run-time dependencies, declared in <c>RDEPEND</c>. When one of |
536 |
|
|
these dependencies explicitly marks a package or virtual as being <e>not</e> |
537 |
|
|
compatible, it triggers a blockage. |
538 |
swift |
1.3 |
</p> |
539 |
|
|
|
540 |
swift |
1.11 |
<p> |
541 |
nightmorph |
1.73 |
While recent versions of Portage are smart enough to work around minor blockages |
542 |
|
|
without user intervention, occasionally you will need to fix it yourself, as |
543 |
|
|
explained below. |
544 |
|
|
</p> |
545 |
|
|
|
546 |
|
|
<p> |
547 |
swift |
1.39 |
To fix a blockage, you can choose to not install the package or unmerge the |
548 |
|
|
conflicting package first. In the given example, you can opt not to install |
549 |
fox2mike |
1.55 |
<c>postfix</c> or to remove <c>ssmtp</c> first. |
550 |
swift |
1.11 |
</p> |
551 |
|
|
|
552 |
swift |
1.56 |
<p> |
553 |
nightmorph |
1.63 |
You may also see blocking packages with specific atoms, such as |
554 |
nightmorph |
1.73 |
<b><</b>media-video/mplayer-1.0_rc1-r2. In this case, updating to a more |
555 |
nightmorph |
1.63 |
recent version of the blocking package would remove the block. |
556 |
|
|
</p> |
557 |
|
|
|
558 |
|
|
<p> |
559 |
swift |
1.56 |
It is also possible that two packages that are yet to be installed are blocking |
560 |
|
|
each other. In this rare case, you should find out why you need to install both. |
561 |
|
|
In most cases you can do with one of the packages alone. If not, please file a |
562 |
|
|
bug on <uri link="http://bugs.gentoo.org">Gentoo's bugtracking system</uri>. |
563 |
|
|
</p> |
564 |
|
|
|
565 |
swift |
1.1 |
</body> |
566 |
|
|
</subsection> |
567 |
swift |
1.39 |
<subsection id="masked"> |
568 |
|
|
<title>Masked Packages</title> |
569 |
swift |
1.1 |
<body> |
570 |
|
|
|
571 |
swift |
1.39 |
<pre caption="Portage warning about masked packages"> |
572 |
|
|
!!! all ebuilds that could satisfy "bootsplash" have been masked. |
573 |
|
|
</pre> |
574 |
|
|
|
575 |
|
|
<pre caption="Portage warning about masked packages - reason"> |
576 |
|
|
!!! possible candidates are: |
577 |
swift |
1.3 |
|
578 |
swift |
1.39 |
- gnome-base/gnome-2.8.0_pre1 (masked by: <i>~x86 keyword</i>) |
579 |
|
|
- lm-sensors/lm-sensors-2.8.7 (masked by: <i>-sparc keyword</i>) |
580 |
|
|
- sys-libs/glibc-2.3.4.20040808 (masked by: <i>-* keyword</i>) |
581 |
|
|
- dev-util/cvsd-1.0.2 (masked by: <i>missing keyword</i>) |
582 |
nightmorph |
1.64 |
- games-fps/unreal-tournament-451 (masked by: <i>package.mask</i>) |
583 |
swift |
1.39 |
- sys-libs/glibc-2.3.2-r11 (masked by: <i>profile</i>) |
584 |
nightmorph |
1.74 |
- net-im/skype-2.1.0.81 (masked by: skype-eula <i>license</i>(s)) |
585 |
swift |
1.35 |
</pre> |
586 |
|
|
|
587 |
swift |
1.3 |
<p> |
588 |
swift |
1.39 |
When you want to install a package that isn't available for your system, you |
589 |
|
|
will receive this masking error. You should try installing a different |
590 |
|
|
application that is available for your system or wait until the package is put |
591 |
|
|
available. There is always a reason why a package is masked: |
592 |
swift |
1.3 |
</p> |
593 |
|
|
|
594 |
swift |
1.35 |
<ul> |
595 |
|
|
<li> |
596 |
swift |
1.39 |
<b>~arch keyword</b> means that the application is not tested sufficiently |
597 |
|
|
to be put in the stable branch. Wait a few days or weeks and try again. |
598 |
swift |
1.35 |
</li> |
599 |
|
|
<li> |
600 |
swift |
1.39 |
<b>-arch keyword</b> or <b>-* keyword</b> means that the application does |
601 |
|
|
not work on your architecture. If you believe the package does work file |
602 |
|
|
a bug at our <uri link="http://bugs.gentoo.org">bugzilla</uri> website. |
603 |
swift |
1.35 |
</li> |
604 |
|
|
<li> |
605 |
swift |
1.39 |
<b>missing keyword</b> means that the application has not been tested on |
606 |
|
|
your architecture yet. Ask the architecture porting team to test the package |
607 |
|
|
or test it for them and report your findings on our <uri |
608 |
|
|
link="http://bugs.gentoo.org">bugzilla</uri> website. |
609 |
swift |
1.35 |
</li> |
610 |
|
|
<li> |
611 |
swift |
1.39 |
<b>package.mask</b> means that the package has been found corrupt, unstable |
612 |
|
|
or worse and has been deliberately marked as do-not-use. |
613 |
swift |
1.35 |
</li> |
614 |
|
|
<li> |
615 |
swift |
1.39 |
<b>profile</b> means that the package has been found not suitable for your |
616 |
|
|
profile. The application might break your system if you installed it or is |
617 |
|
|
just not compatible with the profile you use. |
618 |
swift |
1.35 |
</li> |
619 |
nightmorph |
1.74 |
<li> |
620 |
|
|
<b>license</b> means that the package's license is not compatible with your |
621 |
|
|
<c>ACCEPT_LICENSE</c> setting. You must explicitly permit its license or |
622 |
|
|
license group by setting it in <path>/etc/make.conf</path> or in |
623 |
|
|
<path>/etc/portage/package.license</path>. Refer to <uri |
624 |
|
|
link="#license">Licenses</uri> to learn how licenses work. |
625 |
|
|
</li> |
626 |
swift |
1.35 |
</ul> |
627 |
|
|
|
628 |
swift |
1.1 |
</body> |
629 |
|
|
</subsection> |
630 |
swift |
1.76 |
<subsection id="USEdependency"> |
631 |
|
|
<title>Necessary USE Flag Changes</title> |
632 |
|
|
<body> |
633 |
|
|
|
634 |
|
|
<pre caption="Portage warning about USE flag change requirement"> |
635 |
|
|
The following USE changes are necessary to proceed: |
636 |
|
|
#required by app-text/happypackage-2.0, required by happypackage (argument) |
637 |
|
|
>=app-text/feelings-1.0.0 test |
638 |
|
|
</pre> |
639 |
|
|
|
640 |
|
|
<p> |
641 |
|
|
The error message might also be displayed as follows, if <c>--autounmask</c> |
642 |
|
|
isn't set: |
643 |
|
|
</p> |
644 |
|
|
|
645 |
|
|
<pre caption="Portage error about USE flag change requirement"> |
646 |
|
|
emerge: there are no ebuilds built with USE flags to satisfy "app-text/feelings[test]". |
647 |
|
|
!!! One of the following packages is required to complete your request: |
648 |
|
|
- app-text/feelings-1.0.0 (Change USE: +test) |
649 |
|
|
(dependency required by "app-text/happypackage-2.0" [ebuild]) |
650 |
|
|
(dependency required by "happypackage" [argument]) |
651 |
|
|
</pre> |
652 |
|
|
|
653 |
|
|
<p> |
654 |
|
|
Such warning or error occurs when you want to install a package which not only |
655 |
|
|
depends on another package, but also requires that that package is built with a |
656 |
|
|
particular USE flag (or set of USE flags). In the given example, the package |
657 |
|
|
<c>app-text/feelings</c> needs to be built with <c>USE="test"</c>, but this USE |
658 |
|
|
flag is not set on the system. |
659 |
|
|
</p> |
660 |
|
|
|
661 |
|
|
<p> |
662 |
|
|
To resolve this, either add the requested USE flag to your global USE flags in |
663 |
|
|
<path>/etc/make.conf</path>, or set it for the specific package in |
664 |
|
|
<path>/etc/portage/package.use</path>. |
665 |
|
|
</p> |
666 |
|
|
|
667 |
|
|
</body> |
668 |
|
|
</subsection> |
669 |
swift |
1.39 |
<subsection id="missingdependencies"> |
670 |
|
|
<title>Missing Dependencies</title> |
671 |
swift |
1.1 |
<body> |
672 |
|
|
|
673 |
swift |
1.39 |
<pre caption="Portage warning about missing dependency"> |
674 |
neysx |
1.48 |
emerge: there are no ebuilds to satisfy ">=sys-devel/gcc-3.4.2-r4". |
675 |
swift |
1.3 |
|
676 |
swift |
1.39 |
!!! Problem with ebuild sys-devel/gcc-3.4.2-r2 |
677 |
|
|
!!! Possibly a DEPEND/*DEPEND problem. |
678 |
swift |
1.3 |
</pre> |
679 |
|
|
|
680 |
|
|
<p> |
681 |
swift |
1.39 |
The application you are trying to install depends on another package that is not |
682 |
|
|
available for your system. Please check <uri |
683 |
|
|
link="http://bugs.gentoo.org">bugzilla</uri> if the issue is known and if not, |
684 |
|
|
please report it. Unless you are mixing branches this should not occur and is |
685 |
|
|
therefore a bug. |
686 |
swift |
1.3 |
</p> |
687 |
|
|
|
688 |
swift |
1.39 |
</body> |
689 |
|
|
</subsection> |
690 |
|
|
<subsection id="ambiguousebuild"> |
691 |
|
|
<title>Ambiguous Ebuild Name</title> |
692 |
|
|
<body> |
693 |
swift |
1.3 |
|
694 |
swift |
1.39 |
<pre caption="Portage warning about ambiguous ebuild names"> |
695 |
nightmorph |
1.73 |
[ Results for search key : listen ] |
696 |
|
|
[ Applications found : 2 ] |
697 |
|
|
|
698 |
|
|
* dev-tinyos/listen [ Masked ] |
699 |
|
|
Latest version available: 1.1.15 |
700 |
|
|
Latest version installed: [ Not Installed ] |
701 |
|
|
Size of files: 10,032 kB |
702 |
|
|
Homepage: http://www.tinyos.net/ |
703 |
|
|
Description: Raw listen for TinyOS |
704 |
|
|
License: BSD |
705 |
|
|
|
706 |
|
|
* media-sound/listen [ Masked ] |
707 |
|
|
Latest version available: 0.6.3 |
708 |
|
|
Latest version installed: [ Not Installed ] |
709 |
|
|
Size of files: 859 kB |
710 |
|
|
Homepage: http://www.listen-project.org |
711 |
|
|
Description: A Music player and management for GNOME |
712 |
|
|
License: GPL-2 |
713 |
swift |
1.35 |
|
714 |
nightmorph |
1.73 |
!!! The short ebuild name "listen" is ambiguous. Please specify |
715 |
|
|
!!! one of the above fully-qualified ebuild names instead. |
716 |
swift |
1.3 |
</pre> |
717 |
|
|
|
718 |
|
|
<p> |
719 |
swift |
1.39 |
The application you want to install has a name that corresponds with more than |
720 |
|
|
one package. You need to supply the category name as well. Portage will inform |
721 |
|
|
you of possible matches to choose from. |
722 |
swift |
1.35 |
</p> |
723 |
|
|
|
724 |
swift |
1.39 |
</body> |
725 |
|
|
</subsection> |
726 |
|
|
<subsection id="circulardependencies"> |
727 |
|
|
<title>Circular Dependencies</title> |
728 |
|
|
<body> |
729 |
swift |
1.35 |
|
730 |
swift |
1.39 |
<pre caption="Portage warning about circular dependencies"> |
731 |
|
|
!!! Error: circular dependencies: |
732 |
swift |
1.35 |
|
733 |
swift |
1.39 |
ebuild / net-print/cups-1.1.15-r2 depends on ebuild / app-text/ghostscript-7.05.3-r1 |
734 |
|
|
ebuild / app-text/ghostscript-7.05.3-r1 depends on ebuild / net-print/cups-1.1.15-r2 |
735 |
swift |
1.35 |
</pre> |
736 |
|
|
|
737 |
|
|
<p> |
738 |
swift |
1.39 |
Two (or more) packages you want to install depend on each other and can |
739 |
|
|
therefore not be installed. This is most likely a bug in the Portage tree. |
740 |
|
|
Please resync after a while and try again. You can also check <uri |
741 |
|
|
link="http://bugs.gentoo.org">bugzilla</uri> if the issue is known and if not, |
742 |
|
|
report it. |
743 |
swift |
1.3 |
</p> |
744 |
|
|
|
745 |
swift |
1.39 |
</body> |
746 |
|
|
</subsection> |
747 |
|
|
<subsection id="fetchfailed"> |
748 |
|
|
<title>Fetch failed</title> |
749 |
|
|
<body> |
750 |
swift |
1.29 |
|
751 |
swift |
1.39 |
<pre caption="Portage warning about fetch failed"> |
752 |
|
|
!!! Fetch failed for sys-libs/ncurses-5.4-r5, continuing... |
753 |
|
|
<comment>(...)</comment> |
754 |
|
|
!!! Some fetch errors were encountered. Please see above for details. |
755 |
swift |
1.3 |
</pre> |
756 |
|
|
|
757 |
swift |
1.35 |
<p> |
758 |
swift |
1.39 |
Portage was unable to download the sources for the given application and will |
759 |
|
|
try to continue installing the other applications (if applicable). This failure |
760 |
|
|
can be due to a mirror that has not synchronised correctly or because the ebuild |
761 |
|
|
points to an incorrect location. The server where the sources reside can also be |
762 |
|
|
down for some reason. |
763 |
swift |
1.35 |
</p> |
764 |
|
|
|
765 |
|
|
<p> |
766 |
swift |
1.39 |
Retry after one hour to see if the issue still persists. |
767 |
swift |
1.35 |
</p> |
768 |
|
|
|
769 |
swift |
1.1 |
</body> |
770 |
|
|
</subsection> |
771 |
swift |
1.39 |
<subsection id="profileprotect"> |
772 |
|
|
<title>System Profile Protection</title> |
773 |
swift |
1.1 |
<body> |
774 |
swift |
1.3 |
|
775 |
swift |
1.39 |
<pre caption="Portage warning about profile-protected package"> |
776 |
|
|
!!! Trying to unmerge package(s) in system profile. 'sys-apps/portage' |
777 |
|
|
!!! This could be damaging to your system. |
778 |
swift |
1.3 |
</pre> |
779 |
|
|
|
780 |
|
|
<p> |
781 |
swift |
1.39 |
You have asked to remove a package that is part of your system's core packages. |
782 |
|
|
It is listed in your profile as required and should therefore not be removed |
783 |
|
|
from the system. |
784 |
swift |
1.3 |
</p> |
785 |
|
|
|
786 |
swift |
1.1 |
</body> |
787 |
|
|
</subsection> |
788 |
nightmorph |
1.59 |
<subsection id="digesterror"> |
789 |
nightmorph |
1.71 |
<title>Digest Verification Failures</title> |
790 |
nightmorph |
1.59 |
<body> |
791 |
|
|
|
792 |
|
|
<p> |
793 |
|
|
Sometimes, when you attempt to emerge a package, it will fail with the message: |
794 |
|
|
</p> |
795 |
|
|
|
796 |
|
|
<pre caption="Digest verification failure"> |
797 |
nightmorph |
1.71 |
>>> checking ebuild checksums |
798 |
nightmorph |
1.59 |
!!! Digest verification failed: |
799 |
|
|
</pre> |
800 |
|
|
|
801 |
|
|
<p> |
802 |
|
|
This is a sign that something is wrong with the Portage tree -- often, it is |
803 |
|
|
because a developer may have made a mistake when committing a package to the |
804 |
|
|
tree. |
805 |
|
|
</p> |
806 |
|
|
|
807 |
|
|
<p> |
808 |
|
|
When the digest verification fails, do <e>not</e> try to re-digest the package |
809 |
nightmorph |
1.72 |
yourself. Running <c>ebuild foo manifest</c> will not fix the problem; it will |
810 |
nightmorph |
1.59 |
almost certainly make it worse! |
811 |
|
|
</p> |
812 |
|
|
|
813 |
|
|
<p> |
814 |
|
|
Instead, wait an hour or two for the tree to settle down. It's likely that the |
815 |
|
|
error was noticed right away, but it can take a little time for the fix to |
816 |
|
|
trickle down the Portage tree. While you're waiting, check <uri |
817 |
|
|
link="http://bugs.gentoo.org">Bugzilla</uri> and see if anyone has reported |
818 |
|
|
the problem yet. If not, go ahead and file a bug for the broken package. |
819 |
|
|
</p> |
820 |
|
|
|
821 |
|
|
<p> |
822 |
|
|
Once you see that the bug has been fixed, you may want to re-sync to pick up |
823 |
|
|
the fixed digest. |
824 |
|
|
</p> |
825 |
|
|
|
826 |
|
|
<impo> |
827 |
|
|
This does <e>not</e> mean that you can re-sync your tree multiple times! As |
828 |
|
|
stated in the rsync policy (when you run <c>emerge --sync</c>), users who sync |
829 |
|
|
too often will be banned! In fact, it's better to just wait until your next |
830 |
|
|
scheduled sync, so that you don't overload the rsync servers. |
831 |
|
|
</impo> |
832 |
|
|
|
833 |
|
|
</body> |
834 |
|
|
</subsection> |
835 |
swift |
1.1 |
</section> |
836 |
|
|
</sections> |