… | |
… | |
2 | <!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
2 | <!DOCTYPE sections SYSTEM "/dtd/book.dtd"> |
3 | |
3 | |
4 | <!-- 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 --> |
5 | <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
5 | <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
6 | |
6 | |
7 | <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.42 2004/10/24 18:28:09 neysx Exp $ --> |
7 | <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.54 2005/06/11 12:16:14 swift Exp $ --> |
8 | |
8 | |
9 | <sections> |
9 | <sections> |
|
|
10 | |
|
|
11 | <version>1.49</version> |
|
|
12 | <date>2005-06-11</date> |
|
|
13 | |
10 | <section> |
14 | <section> |
11 | <title>Welcome to Portage</title> |
15 | <title>Welcome to Portage</title> |
12 | <body> |
16 | <body> |
13 | |
17 | |
14 | <p> |
18 | <p> |
… | |
… | |
62 | <title>Updating the Portage Tree</title> |
66 | <title>Updating the Portage Tree</title> |
63 | <body> |
67 | <body> |
64 | |
68 | |
65 | <p> |
69 | <p> |
66 | The Portage tree is usually updated with <uri |
70 | The Portage tree is usually updated with <uri |
67 | link="http://rsync.gentoo.org">rsync</uri>, a fast incremental file transfer |
71 | link="http://rsync.samba.org/">rsync</uri>, a fast incremental file transfer |
68 | utility. Updating is fairly simple as the <c>emerge</c> command provides a |
72 | utility. Updating is fairly simple as the <c>emerge</c> command provides a |
69 | front-end for rsync: |
73 | front-end for rsync: |
70 | </p> |
74 | </p> |
71 | |
75 | |
72 | <pre caption="Updating the Portage tree"> |
76 | <pre caption="Updating the Portage tree"> |
… | |
… | |
93 | <title>Searching for Software</title> |
97 | <title>Searching for Software</title> |
94 | <body> |
98 | <body> |
95 | |
99 | |
96 | <p> |
100 | <p> |
97 | To search through the Portage tree after software titles, you can use |
101 | To search through the Portage tree after software titles, you can use |
98 | <c>emerge</c> built-in search capabilities. By default, <c>emerge search</c> |
102 | <c>emerge</c> built-in search capabilities. By default, <c>emerge --search</c> |
99 | returns the names of packages whose title matches (either fully or partially) |
103 | returns the names of packages whose title matches (either fully or partially) |
100 | the given search term. |
104 | the given search term. |
101 | </p> |
105 | </p> |
102 | |
106 | |
103 | <p> |
107 | <p> |
104 | For instance, to search for all packages who have "pdf" in their name: |
108 | For instance, to search for all packages who have "pdf" in their name: |
105 | </p> |
109 | </p> |
106 | |
110 | |
107 | <pre caption="Searching for pdf-named packages"> |
111 | <pre caption="Searching for pdf-named packages"> |
108 | $ <i>emerge search pdf</i> |
112 | $ <i>emerge --search pdf</i> |
109 | </pre> |
113 | </pre> |
110 | |
114 | |
111 | <p> |
115 | <p> |
112 | If you want to search through the descriptions as well you can use the |
116 | If you want to search through the descriptions as well you can use the |
113 | <c>--searchdesc</c> (or <c>-S</c>) switch: |
117 | <c>--searchdesc</c> (or <c>-S</c>) switch: |
… | |
… | |
121 | When you take a look at the output, you'll notice that it gives you a lot of |
125 | When you take a look at the output, you'll notice that it gives you a lot of |
122 | information. The fields are clearly labelled so we won't go further into their |
126 | information. The fields are clearly labelled so we won't go further into their |
123 | meanings: |
127 | meanings: |
124 | </p> |
128 | </p> |
125 | |
129 | |
126 | <pre caption="Example emerge search output"> |
130 | <pre caption="Example 'emerge --search' output"> |
127 | * net-print/cups-pdf |
131 | * net-print/cups-pdf |
128 | Latest version available: 1.5.2 |
132 | Latest version available: 1.5.2 |
129 | Latest version installed: [ Not Installed ] |
133 | Latest version installed: [ Not Installed ] |
130 | Size of downloaded files: 15 kB |
134 | Size of downloaded files: 15 kB |
131 | Homepage: http://cip.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/ |
135 | Homepage: http://cip.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/ |
… | |
… | |
174 | </pre> |
178 | </pre> |
175 | |
179 | |
176 | </body> |
180 | </body> |
177 | </subsection> |
181 | </subsection> |
178 | <subsection> |
182 | <subsection> |
|
|
183 | <title>Finding Installed Package Documentation</title> |
|
|
184 | <body> |
|
|
185 | |
|
|
186 | <p> |
|
|
187 | Many packages come with their own documentation. Sometimes, the <c>doc</c> USE |
|
|
188 | flag determines whether the package documentation should be installed or not. |
|
|
189 | You can check the existence of a <c>doc</c> USE flag with the <c>emerge -vp |
|
|
190 | <package name></c> command. |
|
|
191 | </p> |
|
|
192 | |
|
|
193 | <pre caption="Checking the existence of a doc USE flag"> |
|
|
194 | <comment>(alsa-lib is just an example, of course.)</comment> |
|
|
195 | # <i>emerge -vp alsa-lib</i> |
|
|
196 | [ebuild N ] media-libs/alsa-lib-1.0.9_rc3 +doc -jack 674 kB |
|
|
197 | </pre> |
|
|
198 | |
|
|
199 | <p> |
|
|
200 | You can enable or disable the <c>doc</c> USE flag either globally in the |
|
|
201 | <path>/etc/make.conf</path> file or per package in the |
|
|
202 | <path>/etc/portage/package.use</path> file. The <uri |
|
|
203 | link="?part=2&chap=2">USE Flags</uri> chapter covers this aspect in detail. |
|
|
204 | </p> |
|
|
205 | |
|
|
206 | <p> |
|
|
207 | Once the package installed, its documentation is generally found in a |
|
|
208 | subdirectory named after the package under the <path>/usr/share/doc</path> |
|
|
209 | directory. You can also list all installed files with the <c>equery</c> tool |
|
|
210 | which is part of the <c>app-portage/gentoolkit</c> <uri |
|
|
211 | link="/doc/en/gentoolkit.xml">package</uri>. |
|
|
212 | </p> |
|
|
213 | |
|
|
214 | <pre caption="Locating package documentation"> |
|
|
215 | # <i>ls -l /usr/share/doc/alsa-lib-1.0.9_rc3</i> |
|
|
216 | total 28 |
|
|
217 | -rw-r--r-- 1 root root 669 May 17 21:54 ChangeLog.gz |
|
|
218 | -rw-r--r-- 1 root root 9373 May 17 21:54 COPYING.gz |
|
|
219 | drwxr-xr-x 2 root root 8560 May 17 21:54 html |
|
|
220 | -rw-r--r-- 1 root root 196 May 17 21:54 TODO.gz |
|
|
221 | |
|
|
222 | <comment>(Alternatively, use equery to locate interesting files:)</comment> |
|
|
223 | # <i>equery files alsa-lib | less</i> |
|
|
224 | media-libs/alsa-lib-1.0.9_rc3 |
|
|
225 | * Contents of media-libs/alsa-lib-1.0.9_rc3: |
|
|
226 | /usr |
|
|
227 | /usr/bin |
|
|
228 | /usr/bin/alsalisp |
|
|
229 | <comment>(Output truncated)</comment> |
|
|
230 | </pre> |
|
|
231 | |
|
|
232 | </body> |
|
|
233 | </subsection> |
|
|
234 | <subsection> |
179 | <title>Removing Software</title> |
235 | <title>Removing Software</title> |
180 | <body> |
236 | <body> |
181 | |
237 | |
182 | <p> |
238 | <p> |
183 | When you want to remove a software package from your system, use <c>emerge |
239 | When you want to remove a software package from your system, use <c>emerge |
184 | unmerge</c>. This will tell Portage to remove all files installed by that |
240 | --unmerge</c>. This will tell Portage to remove all files installed by that |
185 | package from your system <e>except</e> the configuration files of that |
241 | package from your system <e>except</e> the configuration files of that |
186 | application if you have altered those after the installation. Leaving the |
242 | application if you have altered those after the installation. Leaving the |
187 | configuration files allows you to continue working with the package if you ever |
243 | configuration files allows you to continue working with the package if you ever |
188 | decide to install it again. |
244 | decide to install it again. |
189 | </p> |
245 | </p> |
… | |
… | |
194 | warn you when you want to remove an important package that breaks your system |
250 | warn you when you want to remove an important package that breaks your system |
195 | if you unmerge it. |
251 | if you unmerge it. |
196 | </p> |
252 | </p> |
197 | |
253 | |
198 | <pre caption="Removing gnumeric from the system"> |
254 | <pre caption="Removing gnumeric from the system"> |
199 | # <i>emerge unmerge gnumeric</i> |
255 | # <i>emerge --unmerge gnumeric</i> |
200 | </pre> |
256 | </pre> |
201 | |
257 | |
202 | <p> |
258 | <p> |
203 | When you remove a package from your system, the dependencies of that package |
259 | When you remove a package from your system, the dependencies of that package |
204 | that were installed automatically when you installed the software are left. To |
260 | that were installed automatically when you installed the software are left. To |
205 | have Portage locate all dependencies that can now be removed, use |
261 | have Portage locate all dependencies that can now be removed, use |
206 | <c>emerge</c>'s <c>depclean</c> functionality. We will talk about this later on. |
262 | <c>emerge</c>'s <c>--depclean</c> functionality. We will talk about this later |
|
|
263 | on. |
207 | </p> |
264 | </p> |
208 | |
265 | |
209 | </body> |
266 | </body> |
210 | </subsection> |
267 | </subsection> |
211 | <subsection> |
268 | <subsection> |
… | |
… | |
234 | <pre caption="Updating your entire system"> |
291 | <pre caption="Updating your entire system"> |
235 | # <i>emerge --update --deep world</i> |
292 | # <i>emerge --update --deep world</i> |
236 | </pre> |
293 | </pre> |
237 | |
294 | |
238 | <p> |
295 | <p> |
|
|
296 | Since security updates also happen in packages you have not explicitly installed |
|
|
297 | on your system (but that are pulled in as dependencies of other programs), it |
|
|
298 | is recommended to run this command once in a while. |
|
|
299 | </p> |
|
|
300 | |
|
|
301 | <p> |
239 | If you have altered any of your <uri link="?part=2&chap=2">USE flags</uri> |
302 | If you have altered any of your <uri link="?part=2&chap=2">USE flags</uri> |
240 | lately you might want to add <c>--newuse</c> as well. Portage will then verify |
303 | lately you might want to add <c>--newuse</c> as well. Portage will then verify |
241 | if the change requires the installation of new packages or recompilation of |
304 | if the change requires the installation of new packages or recompilation of |
242 | existing ones: |
305 | existing ones: |
243 | </p> |
306 | </p> |
… | |
… | |
247 | </pre> |
310 | </pre> |
248 | |
311 | |
249 | </body> |
312 | </body> |
250 | </subsection> |
313 | </subsection> |
251 | <subsection> |
314 | <subsection> |
252 | <title>Stub Packages</title> |
315 | <title>Metapackages</title> |
253 | <body> |
316 | <body> |
254 | |
317 | |
255 | <p> |
318 | <p> |
256 | Some packages in the Portage tree don't have any real content but are used to |
319 | Some packages in the Portage tree don't have any real content but are used to |
257 | install a collection of packages. For instance, the <c>kde</c> package will |
320 | install a collection of packages. For instance, the <c>kde</c> package will |
… | |
… | |
259 | KDE-related packages as dependencies. |
322 | KDE-related packages as dependencies. |
260 | </p> |
323 | </p> |
261 | |
324 | |
262 | <p> |
325 | <p> |
263 | If you ever want to remove such a package from your system, running <c>emerge |
326 | If you ever want to remove such a package from your system, running <c>emerge |
264 | unmerge</c> on the package won't have much effect as the dependencies remain on |
327 | --unmerge</c> on the package won't have much effect as the dependencies remain |
265 | the system. |
328 | on the system. |
266 | </p> |
329 | </p> |
267 | |
330 | |
268 | <p> |
331 | <p> |
269 | Portage has the functionality to remove orphaned dependencies as well, but since |
332 | Portage has the functionality to remove orphaned dependencies as well, but since |
270 | the availability of software is dynamically dependent you first need to update |
333 | the availability of software is dynamically dependent you first need to update |
271 | your entire system fully, including the new changes you applied when changing |
334 | your entire system fully, including the new changes you applied when changing |
272 | USE flags. After this you can run <c>emerge depclean</c> to remove the orphaned |
335 | USE flags. After this you can run <c>emerge --depclean</c> to remove the |
273 | dependencies. When this is done, you need to rebuild the applications that were |
336 | orphaned dependencies. When this is done, you need to rebuild the applications |
274 | dynamically linked to the now-removed software titles but don't require them |
337 | that were dynamically linked to the now-removed software titles but don't |
275 | anymore. |
338 | require them anymore. |
276 | </p> |
339 | </p> |
277 | |
340 | |
278 | <p> |
341 | <p> |
279 | All this is handled with the following three commands: |
342 | All this is handled with the following three commands: |
280 | </p> |
343 | </p> |
281 | |
344 | |
282 | <pre caption="Removing orphaned dependencies"> |
345 | <pre caption="Removing orphaned dependencies"> |
283 | # <i>emerge --update --deep --newuse world</i> |
346 | # <i>emerge --update --deep --newuse world</i> |
284 | # <i>emerge depclean</i> |
347 | # <i>emerge --depclean</i> |
285 | # <i>revdep-rebuild</i> |
348 | # <i>revdep-rebuild</i> |
286 | </pre> |
349 | </pre> |
287 | |
350 | |
288 | <p> |
351 | <p> |
289 | <c>revdep-rebuild</c> is provided by the <c>gentoolkit</c> package; don't forget |
352 | <c>revdep-rebuild</c> is provided by the <c>gentoolkit</c> package; don't forget |
… | |
… | |
304 | <body> |
367 | <body> |
305 | |
368 | |
306 | <p> |
369 | <p> |
307 | As we stated before, Portage is extremely powerful and supports many features |
370 | As we stated before, Portage is extremely powerful and supports many features |
308 | that other software management tools lack. To understand this, we explain a few |
371 | that other software management tools lack. To understand this, we explain a few |
309 | aspects of Portage without going in too much detail. |
372 | aspects of Portage without going into too much detail. |
310 | </p> |
373 | </p> |
311 | |
374 | |
312 | <p> |
375 | <p> |
313 | With Portage different versions of a single package can coexist on a system. |
376 | With Portage different versions of a single package can coexist on a system. |
314 | While other distributions tend to name their package to those versions (like |
377 | While other distributions tend to name their package to those versions (like |
… | |
… | |
440 | <subsection id="missingdependencies"> |
503 | <subsection id="missingdependencies"> |
441 | <title>Missing Dependencies</title> |
504 | <title>Missing Dependencies</title> |
442 | <body> |
505 | <body> |
443 | |
506 | |
444 | <pre caption="Portage warning about missing dependency"> |
507 | <pre caption="Portage warning about missing dependency"> |
445 | emerge: there are no ebuilds to satisfy ">=sys-devel/gcc-4.2-r4". |
508 | emerge: there are no ebuilds to satisfy ">=sys-devel/gcc-3.4.2-r4". |
446 | |
509 | |
447 | !!! Problem with ebuild sys-devel/gcc-3.4.2-r2 |
510 | !!! Problem with ebuild sys-devel/gcc-3.4.2-r2 |
448 | !!! Possibly a DEPEND/*DEPEND problem. |
511 | !!! Possibly a DEPEND/*DEPEND problem. |
449 | </pre> |
512 | </pre> |
450 | |
513 | |