/[gentoo]/xml/htdocs/doc/en/gentoolkit.xml
Gentoo

Contents of /xml/htdocs/doc/en/gentoolkit.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.34 - (hide annotations) (download) (as text)
Sun Aug 14 17:02:52 2011 UTC (2 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.33: +428 -253 lines
File MIME type: application/xml
Bug #269071 - Many updates on gentoolkit.xml documentation, thanks to fuzzyray

1 vapier 1.11 <?xml version="1.0" encoding="UTF-8"?>
2 swift 1.34 <!-- $Header: $ -->
3 drobbins 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 nightmorph 1.32 <guide>
6 drobbins 1.1 <title>Gentoolkit</title>
7 cam 1.9
8     <author title="Author">
9     <mail link="mbutcher@aleph-null.tv">Matt Butcher</mail>
10 drobbins 1.1 </author>
11 cam 1.9 <author title="Editor">
12     <!-- zhen@gentoo.org -->John P. Davis
13 swift 1.5 </author>
14 erwin 1.7 <author title="Editor">
15     <mail link="erwin@gentoo.org">Erwin</mail>
16     </author>
17 neysx 1.13 <author title="Editor">
18 fox2mike 1.21 <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
19 neysx 1.13 </author>
20     <author title="Editor">
21     <mail link="neysx@gentoo.org">Xavier Neys</mail>
22     </author>
23 yoswink 1.20 <author title="Editor">
24     <mail link="karltk@gentoo.org">Karl Trygve</mail>
25     </author>
26     <author title="Editor">
27     <mail link="yoswink@gentoo.org">José Luis Rivero</mail>
28     </author>
29 nightmorph 1.24 <author title="Editor">
30     <mail link="nightmorph@gentoo.org">Joshua Saddler</mail>
31     </author>
32 swift 1.34 <author title="Editor">
33     <mail link="douglasjanderson@gmail.com">Douglas Anderson</mail>
34     </author>
35 drobbins 1.1
36     <abstract>
37 cam 1.9 Gentoolkit is a suite of tools to ease the administration of a Gentoo system.
38     This document covers the basics of some of the tools present in Gentoolkit.
39 drobbins 1.1 </abstract>
40    
41 yoswink 1.20 <!-- Licensed under GFDL -->
42    
43 swift 1.34 <version>3</version>
44     <date>2011-06-24</date>
45 drobbins 1.1
46     <chapter>
47 cam 1.9 <title>Introduction</title>
48     <section>
49     <title>What is Gentoolkit?</title>
50     <body>
51    
52     <p>
53 neysx 1.13 Gentoo is a unique distribution and presents some complexities that simply
54 cam 1.9 don't exist for other distributions. As Gentoo developers and contributors
55     discovered some of these complexities, they also wrote tools to help users and
56     administrators work around them. Many of these tools have been contributed to
57 neysx 1.13 the Gentoo project and are included in the package
58 cam 1.9 <c>app-portage/gentoolkit</c>.
59     </p>
60    
61 neysx 1.13 <note>
62     As of now, there are two versions of gentoolkit: <c>app-portage/gentoolkit</c>
63     and <c>app-portage/gentoolkit-dev</c>. While the former contains administration
64     scripts, the latter contains scripts specific to help development on Gentoo.
65 swift 1.31 If you are a developer, you can have your scripts included into
66     <c>gentoolkit-dev</c> by contacting the Gentoolkit maintainer. This document
67     discusses gentoolkit only.
68 neysx 1.13 </note>
69    
70 cam 1.9 <p>
71 neysx 1.13 Gentoolkit contains a whole bunch of useful tools to help manage your packages
72 swift 1.31 and keep track of what is going on in your system. Most users
73     --&nbsp;particularly those who update systems often&nbsp;-- will benefit from
74     having gentoolkit installed.
75 cam 1.9 </p>
76    
77     </body>
78     </section>
79     <section>
80     <title>Installation</title>
81     <body>
82    
83     <p>
84     Just as with any Gentoo package, installation is just a simple emerge.
85     </p>
86    
87 neysx 1.13 <pre caption="Getting gentoolkit">
88 cam 1.10 # <i>emerge gentoolkit</i>
89 cam 1.9 </pre>
90    
91     <note>
92     Many of the tools in gentoolkit reveal important information about your system
93 neysx 1.13 or require root privilege. For that reason, some of the programs may only be
94 swift 1.34 executed (or only function properly) if run by a user with root privileges.
95 cam 1.9 </note>
96    
97     </body>
98     </section>
99     <section>
100     <title>Finding Documentation</title>
101     <body>
102    
103     <p>
104 neysx 1.13 Any documentation that a program might have (other than man pages) is stored in
105 nightmorph 1.26 <path>/usr/share/doc/gentoolkit-[version]/[program-name]/</path>.
106 cam 1.9 </p>
107 cam 1.10
108 cam 1.9 </body>
109     </section>
110 drobbins 1.1 </chapter>
111 cam 1.10
112 drobbins 1.1 <chapter>
113 neysx 1.13 <title>equery</title>
114 cam 1.9 <section>
115     <title>Introduction</title>
116     <body>
117 cam 1.10
118 cam 1.9 <p>
119 swift 1.34 <c>equery</c> is a tool that displays useful information about the packages on
120     your system. <c>equery</c> is based on a system of modules.
121     Every module has a shorthand name. For example, <c>equery l gcc</c> is the same
122     as <c>equery list gcc</c>. <c>equery --help</c> explains global options
123     and lists all available modules and their shorthand names.
124     <c>equery --help module</c> will display the help screen for a specific
125     module. Lastly, <c>man equery</c> provides a detailed explanation of all
126     available modules and options, and provides useful examples.
127 neysx 1.13 </p>
128    
129 swift 1.34 <p>
130     Below is a list of features that work over the majority of modules.
131     </p>
132    
133     <pre caption="Examples of Acceptable Input">
134     <comment>(Many modules require a package argument. equery accepts all emerge-like input):</comment>
135     $ <i>equery --quiet list gcc</i> # <comment>package</comment>
136     sys-devel/gcc-4.3.2-r3
137     $ <i>equery --quiet list sys-devel/gcc</i> # <comment>category/package</comment>
138     sys-devel/gcc-4.3.2-r3
139     $ <i>equery --quiet list '>=sys-devel/gcc-4'</i> # <comment>atom syntax</comment>
140     sys-devel/gcc-4.3.2-r3
141    
142     <comment>(Like emerge, equery doesn't understand partial package names):</comment>
143     $ <i>equery check zilla</i>
144     !!! No package found matching zilla
145    
146     <comment>(Unlike emerge, equery can accept shell-like globbing in the category and/or package name):</comment>
147     $ <i>equery check '*zilla*'</i>
148     * Checking www-client/mozilla-firefox-3.0.14 ...
149     90 out of 90 files passed
150     $ <i>equery check www-c*/*</i>
151     * Checking www-client/links-2.2 ...
152     30 out of 30 files passed
153     * Checking www-client/mozilla-firefox-3.0.14 ...
154     90 out of 90 files passed
155    
156     <comment>(Most equery modules take multiple input):</comment>
157     $ <i>equery hasuse sse sse2</i>
158     * Searching for USE flag sse ...
159     [IP-] [ ] media-libs/flac-1.2.1-r3 (0)
160     [IP-] [ ] media-libs/speex-1.2_beta3_p2 (0)
161    
162     * Searching for USE flag sse2 ...
163     [IP-] [ ] dev-libs/openssl-0.9.8k (0)
164     [IP-] [ ] x11-libs/pixman-0.16.0 (0)
165    
166     <comment>(A few modules also allow full regular expressions):</comment>
167     $ <i>equery -q list --portage-tree --full-regex '[kr]?flickr.*'</i>
168     dev-dotnet/flickrnet-bin-2.2
169     dev-ruby/flickr-1.0.2-r1
170     dev-ruby/flickr-1.0.2-r2
171     dev-ruby/rflickr-20060201
172     media-gfx/kflickr-0.6
173     [...]
174     </pre>
175    
176 neysx 1.13 <note>
177 swift 1.34 Globbing support replaced a number of older options in <c>equery</c>.
178     For example, to act on all packages in a certain set, use <c>'*'</c>.
179     To act on all packages in a category, use <c>'category-name/*'</c>.
180 yoswink 1.20 </note>
181    
182 swift 1.34 <warn>
183     Don't forget to quote input when using special shell characters
184     like asterisks or greater than/less than signs.
185     </warn>
186    
187     <p>
188     The next few sections in this document give a quick introduction to the
189     different <c>equery</c> modules.
190     </p>
191 cam 1.9
192 neysx 1.13 </body>
193     </section>
194     <section>
195 swift 1.34 <title>Finding the Package That a File Came From with belongs (b)</title>
196 yoswink 1.20 <body>
197    
198 swift 1.34 <pre caption="Finding the Package that Installed a Given File">
199     $ <i>equery belongs -e /usr/bin/glxgears</i>
200     * Searching for /usr/bin/glxgears ...
201     x11-apps/mesa-progs-7.5.1 (/usr/bin/glxgears)
202     </pre>
203    
204 yoswink 1.20 <p>
205 swift 1.34 <c>belongs</c> can search for files matching a regular expression with the
206     <c>-f</c> option. The <c>-e</c> option stops searching after it finds a match.
207     Since no file on your system should be owned by two packages, this is a safe
208     optimization.
209 yoswink 1.20 </p>
210    
211 swift 1.34 </body>
212     </section>
213     <section>
214     <title>Viewing ChangeLog Entries with changes (c)</title>
215     <body>
216 yoswink 1.20
217     <p>
218 swift 1.34 <c>changes</c> lets you view ChangeLog entries for a package version or range
219     of versions. Imagine after an <c>emerge --sync</c>, you
220     notice Portage is going to be upgraded and want to check what has changed:
221 yoswink 1.20 </p>
222    
223 swift 1.34 <pre caption="Viewing Gentoo ChangeLog Entries">
224     <comment>(Show the latest installable version's entry):</comment>
225     $ <i>equery changes portage</i>
226     *portage-2.1.6.13 (03 May 2009)
227    
228     03 May 2009; Zac Medico &lt;zmedico@gentoo.org&gt; +portage-2.1.6.13.ebuild:
229     2.1.6.13 bump. This fixes bug #268398 (document econf automatic die)
230     and bug #267104 (handle insufficient space interaction with userfetch).
231     Bug #268228 tracks all bugs fixed since 2.1.6.11.
232     </pre>
233    
234 yoswink 1.20 </body>
235     </section>
236     <section>
237 swift 1.34 <title>Verifying Package Integrity with check (k)</title>
238 yoswink 1.20 <body>
239    
240     <p>
241 swift 1.31 Sometimes it is useful to check a package's integrity. <c>equery</c> can
242 swift 1.34 verify MD5 sums as well as timestamps to indicate when a package might
243 yoswink 1.20 have been corrupted, replaced, or removed.
244     </p>
245    
246 swift 1.34 <pre caption="Checking Package Integrity">
247     $ <i>equery check gentoolkit</i>
248     * Checking app-portage/gentoolkit-0.3.0_rc7 ...
249     71 out of 71 files passed
250 yoswink 1.20 </pre>
251    
252     </body>
253     </section>
254     <section>
255 swift 1.34 <title>Listing All Packages Depending on Package X with depends (d)</title>
256 yoswink 1.20 <body>
257    
258     <p>
259 swift 1.34 Ever wonder why a certain package has been installed on your system?
260     <c>equery</c> can tell which packages list it as a dependency with
261     <c>depends</c>. Include indirect dependencies with the <c>-D</c>
262     option.
263 yoswink 1.20 </p>
264    
265 swift 1.34 <pre caption="Looking for Packages Depending on pygtk">
266     $ <i>equery depends pygtk</i>
267     * Searching for pygtk ...
268     app-admin/pessulus-2.24.0 (>=dev-python/pygtk-2.6.0)
269     app-editors/gedit-2.24.3 (python ? >=dev-python/pygtk-2.12)
270     dev-libs/libgweather-2.24.3 (python ? >=dev-python/pygtk-2)
271     dev-python/gnome-python-base-2.22.3 (>=dev-python/pygtk-2.10.3)
272     dev-python/gnome-python-desktop-base-2.24.1 (>=dev-python/pygtk-2.10.3)
273     [...]
274 yoswink 1.20 </pre>
275    
276     </body>
277     </section>
278     <section>
279 swift 1.34 <title>Getting Dependency Graphs with depgraph (g)</title>
280 yoswink 1.20 <body>
281    
282     <p>
283 swift 1.34 <c>depgraph</c> is the opposite of <c>depends</c>. You pass it a package, and
284     it will find the packages <e>it</e> depends on (not that depend on it).
285     When it finds a dependency, it will recursively search for all of
286     <e>that</e> package's dependencies. Control how deep the tree gets with
287     the <c>--depth</c> option.
288     </p>
289    
290     <pre caption="Viewing Dependency Graph for cdrtools">
291     $ <i>equery depgraph mozilla-firefox</i>
292     * Searching for mozilla-firefox ...
293     * dependency graph for www-client/mozilla-firefox-2.0.0.19:
294     `-- www-client/mozilla-firefox-2.0.0.19
295     `-- virtual/jre-1.6.0 (virtual/jre) [java]
296     `-- virtual/jdk-1.6.0 (virtual/jdk-1.6.0*)
297     `-- dev-java/icedtea6-bin (unable to resolve: package masked or removed)
298     `-- dev-java/sun-jdk-1.6.0.15
299     `-- dev-java/java-sdk-docs-1.6.0.10 [doc]
300     `-- app-arch/unzip-6.0-r1
301     `-- app-arch/bzip2-1.0.5-r1 [bzip2]
302     `-- sys-libs/glibc-2.9_p20081201-r2
303     `-- sys-devel/gettext-0.17 [nls]
304     `-- virtual/libiconv-0 (virtual/libiconv)
305     [...]
306 yoswink 1.20 </pre>
307    
308     <p>
309 swift 1.34 Notice how <c>jre</c> is a direct dependency and <c>jdk</c> is an indirect
310     dependency if the <c>java</c> USE flag is set.
311 yoswink 1.20 </p>
312    
313     </body>
314     </section>
315     <section>
316 swift 1.34 <title>Listing Files Installed by a Package with files (f)</title>
317 yoswink 1.20 <body>
318    
319     <p>
320 swift 1.34 <c>equery</c> can list all the files installed by an ebuild with the
321     <c>files</c> command. Try <c>--tree</c> to get an easy to read directory
322     layout. Use <c>--filter</c> to only find a certain type of file. For example,
323     to find where executables were installed, use <c>--filter=cmd</c>, and to
324     quickly find the configuration file location, try <c>--filter=conf</c>.
325     </p>
326    
327     <pre caption="Listing Installed Files in Tree Format">
328     $ <i>equery files --tree gentoolkit</i>
329     * Searching for gentoolkit ...
330     * Contents of app-portage/gentoolkit-0.3.0_rc7:
331     /etc
332     > /eclean
333     + distfiles.exclude
334     + packages.exclude
335     > /env.d
336     + 99gentoolkit-env
337     > /revdep-rebuild
338     + 99revdep-rebuild
339     /usr
340     > /bin
341     + eclean
342     + eclean-dist -> eclean
343     + eclean-pkg -> eclean
344     + epkginfo
345     + equery
346     + eread
347     + euse
348     + glsa-check
349     + revdep-rebuild
350     > /lib
351     > /python2.6
352     > /site-packages
353     > /gentoolkit
354     + gentoolkit-0.3.0_rc7-py2.6.egg-info
355     + __init__.py
356     > /equery
357     + __init__.py
358     + belongs.py
359     + changes.py
360     + check.py
361     + depends.py
362     + depgraph.py
363     + files.py
364 yoswink 1.20 [...]
365     </pre>
366    
367     </body>
368     </section>
369     <section>
370 swift 1.34 <title>Looking for Packages that Have a Specific USE Flag with hasuse (h)</title>
371 yoswink 1.20 <body>
372    
373     <p>
374 swift 1.34 You can use <c>hasuse</c> to find out which packages have a given USE flag.
375     <c>hasuse</c> won't tell you if the flag is enabled, only if the ebuild lists
376     it as an option. See the EXAMPLES section of <c>hasuse</c> in the
377     <c>equery</c> man page for more tip on getting that information.
378 yoswink 1.20 </p>
379    
380 swift 1.34 <pre caption="Searching For Installed Packages that Use the qt3 or qt4 USE Flags">
381     $ <i>equery hasuse qt3 qt4</i>
382     * Searching for USE flag qt3 ...
383     [IP-] [ ] app-crypt/pinentry-0.7.5 (0)
384     [IP-] [ ] net-dns/avahi-0.6.24-r2 (0)
385     [IP-] [ ] net-wireless/wpa_supplicant-0.6.9 (0)
386    
387     * Searching for USE flag qt4 ...
388     [IP-] [ ] net-dns/avahi-0.6.24-r2 (0)
389     [IP-] [ ] net-wireless/wpa_supplicant-0.6.9 (0)
390 yoswink 1.20 </pre>
391    
392     </body>
393     </section>
394     <section>
395 swift 1.34 <title>Listing Packages with list (l)</title>
396 yoswink 1.20 <body>
397    
398     <p>
399 swift 1.34 <c>list</c> is a simple, yet powerful module to list packages that are installed,
400     in the Portage tree or in an overlay.
401 yoswink 1.20 </p>
402    
403 swift 1.34 <pre caption="Listing Installed Packages with list">
404     $ <i>equery list '*'</i>
405     * Searching for * ...
406     [IP-] [ ] app-admin/eselect-1.2.3 (0)
407     [IP-] [ ] app-admin/eselect-ctags-1.10 (0)
408     [IP-] [ ] app-admin/eselect-esd-20060719 (0)
409     [IP-] [ ] app-admin/eselect-fontconfig-1.0 (0)
410     [IP-] [ ] app-admin/eselect-opengl-1.0.8-r1 (0)
411     [IP-] [ ] app-admin/eselect-python-20090824 (0)
412     [IP-] [ ] app-admin/eselect-ruby-20081227 (0)
413     [IP-] [ ] app-admin/eselect-vi-1.1.5 (0)
414     [IP-] [ ] app-admin/perl-cleaner-1.05 (0)
415     [IP-] [ ] app-admin/pessulus-2.24.0 (0)
416     [IP-] [ ] app-admin/python-updater-0.7 (0)
417     [IP-] [ ] app-admin/sudo-1.7.2_p1 (0)
418     [...]
419 yoswink 1.20 </pre>
420    
421     <p>
422 swift 1.34 The standard query will search installed packages for the given package name.
423     Passing in '*' displays all packages in the set. In the leftmost field, we
424     see that all the above packages are <c>I</c>nstalled and from the <c>P</c>ortage
425     tree. They're not masked (the second field is blank), and they're all installed
426     in the default slot (0).
427 yoswink 1.20 </p>
428    
429     <p>
430 swift 1.34 This time we are going to use local options to look for packages in the
431     Portage tree and overlays.
432 yoswink 1.20 </p>
433    
434 swift 1.34 <pre caption="Using Local Options with list">
435     $ <i>equery list -po vim</i>
436     * Searching for vim ...
437     [-P-] [ ] app-editors/vim-7.0.235 (0)
438     [-P-] [ ~] app-editors/vim-7.0.243 (0)
439     [-P-] [ ] app-editors/vim-7.1.123 (0)
440     [-P-] [ ~] app-editors/vim-7.1.330 (0)
441     [-P-] [ ] app-editors/vim-7.2 (0)
442     [-P-] [ ~] app-editors/vim-7.2.108 (0)
443     [IP-] [ ] app-editors/vim-7.2.182 (0)
444     [-P-] [ ~] app-editors/vim-7.2.238 (0)
445     [-P-] [ ~] app-editors/vim-7.2.264 (0)
446 yoswink 1.20 </pre>
447    
448 swift 1.34 <p>
449     In this example you can see version 7.2.182 is installed and there are no
450     versions available from an overlay. You can see which versions are keyword
451     masked by the <c>~</c> in the second field.
452     </p>
453    
454 yoswink 1.20 </body>
455     </section>
456     <section>
457 swift 1.34 <title>Viewing Package Metadata with meta (m)</title>
458 neysx 1.13 <body>
459    
460     <p>
461 swift 1.34 Each package in the Portage tree provides at least some metadata about
462     its maintainer, herd, etc. Read about <uri
463     link="http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&amp;chap=4">Gentoo
464     Metadata</uri>. The amount of useful information depends on how much package
465     maintainers decide to provide. With no options, <c>meta</c> returns some basic
466     useful information.
467 neysx 1.13 </p>
468    
469 swift 1.34 <pre caption="Getting Package Metadata with meta">
470     $ <i>equery meta gnucash</i>
471     * app-office/gnucash [gentoo]
472     Herd: gnome-office (gnome-office@gentoo.org)
473     Maintainer: tove@gentoo.org (Torsten Veller)
474     Upstream: None specified
475     Location: /usr/portage/app-office/gnucash
476     Keywords: 2.2.9-r1:0: alpha amd64 ppc sparc x86
477     Keywords: 2.2.9-r2:0:
478     Keywords: 2.3.8:0:
479     Keywords: 2.3.10:0: ~alpha ~amd64 ~ppc ~sparc ~x86
480 neysx 1.13 </pre>
481    
482     <p>
483 swift 1.34 When the maintainer provides extra information, it can be very useful:
484 cam 1.9 </p>
485 cam 1.10
486 swift 1.34 <pre caption="Getting Long Package Descriptions with meta">
487     $ <i>equery meta --description emacs</i>
488     * app-editors/emacs
489     GNU Emacs is an extensible, customizable text editor - and more. At its core
490     is an interpreter for Emacs Lisp, a dialect of the Lisp programming language
491     with extensions to support text editing. The features of GNU Emacs include:
492     * Content-sensitive editing modes, including syntax coloring, for a wide
493     variety of file types including plain text, source code, and HTML.
494     * Complete built-in documentation, including a tutorial for new users.
495     * Support for many languages and their scripts, including all the European
496     "Latin" scripts, Russian, Greek, Japanese, Chinese, Korean, Thai,
497     Vietnamese, Lao, Ethiopian, and some Indian scripts.
498     * Highly customizable, using Emacs Lisp code or a graphical customization
499     interface.
500     * A large number of extensions that add other functionality, including a
501     project planner, mail and news reader, debugger interface, calendar, and
502     more. Many of these extensions are distributed with GNU Emacs; others are
503     available separately.
504     </pre>
505    
506 cam 1.9 </body>
507     </section>
508     <section>
509 swift 1.34 <title>Finding Package Sizes with size (s)</title>
510 cam 1.10 <body>
511 cam 1.9
512     <p>
513 swift 1.34 Have you ever been curious to find out how much space a specific package is
514     occupying? Since a package could have its files over a number of directories,
515     the usual <c>du -hc</c> might not give you the correct figure. Not to worry,
516     here comes <c>equery</c> to the rescue!
517 cam 1.9 </p>
518 cam 1.10
519 swift 1.34 <pre caption="Displaying Package Size">
520     $ <i>equery size openoffice-bin</i>
521     * app-office/openoffice-bin-3.1.1
522     Total files : 4624
523     Total size : 361.38 MiB
524     </pre>
525 drobbins 1.1
526 swift 1.34 <p>
527     As you can see, <c>size</c> prints the total space used in human-readable
528     units and lists the total number of files the package has. To get the
529     total size in bytes, use <c>--bytes</c>.
530     </p>
531    
532     </body>
533     </section>
534     <section>
535     <title>Listing Per-Package USE Flags with uses (u)</title>
536     <body>
537    
538     <p>
539     <c>equery</c>'s <c>uses</c> module can provide information about what USE
540     flags are available for a specific package, and which of those flags is
541     currently enabled.
542     </p>
543    
544     <pre caption="Showing Set and Unset USE Flags">
545     $ <i>equery uses gst-plugins-meta</i>
546     * Searching for gst-plugins-meta ...
547     [ Legend : U - flag is set in make.conf ]
548     [ : I - package is installed with flag ]
549     [ Colors : set, unset ]
550     * Found these USE flags for media-plugins/gst-plugins-meta-0.10-r2:
551     U I
552     + + X : Adds support for X11
553     - - a52 : Enables support for decoding ATSC A/52 streams used in DVD
554     + + alsa : Adds support for media-libs/alsa-lib (Advanced Linux Sound
555     Architecture)
556     - - dvb : Adds support for DVB (Digital Video Broadcasting)
557     + + dvd : Adds support for DVDs
558     + + esd : Adds support for media-sound/esound (Enlightened Sound Daemon)
559     + + ffmpeg : Enable ffmpeg-based audio/video codec support
560     + + flac : Adds support for FLAC: Free Lossless Audio Codec
561     - - mad : Adds support for mad (high-quality mp3 decoder library and cli
562     frontend)
563     + + mpeg : Adds libmpeg3 support to various packages
564     - - mythtv : Support for retrieval from media-tv/mythtv backend
565     + + ogg : Adds support for the Ogg container format (commonly used by
566     Vorbis, Theora and flac)
567     - - oss : Adds support for OSS (Open Sound System)
568     + + theora : Adds support for the Theora Video Compression Codec
569     + + vorbis : Adds support for the OggVorbis audio codec
570     - - xv : Adds in optional support for the Xvideo extension (an X API for
571     video playback)
572 cam 1.10 </pre>
573    
574 cam 1.9 <p>
575 swift 1.34 Here, a number of USE flags are enabled in <c>gstreamer</c>'s plugin
576     meta-package, but you can see that there are other USE flags available.
577     For more information on USE flags, please refer to the <uri
578 neysx 1.17 link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>
579 neysx 1.15 chapter of the <uri link="/doc/en/handbook/">Gentoo Handbook</uri>.
580 cam 1.9 </p>
581    
582 neysx 1.13 </body>
583     </section>
584     <section>
585 swift 1.34 <title>Finding the Ebuild Path with which (w)</title>
586 neysx 1.13 <body>
587    
588 cam 1.9 <p>
589 swift 1.34 <c>which</c> is a simple script to help you quickly find the file path to an
590     ebuild. If you pass an unversioned package name, <c>which</c> will return the
591     path to the newest installable ebuild version, in other words, the ebuild
592     Portage would use if you typed <c>emerge package</c>. Pass in a versioned
593     package to get the path to that ebuild.
594 cam 1.9 </p>
595 cam 1.10
596 swift 1.34 <pre caption="Displaying the Latest Installable Ebuild Path">
597     $ <i>equery which gnome</i>
598     /usr/portage/gnome-base/gnome/gnome-2.26.3.ebuild
599 neysx 1.13 </pre>
600 cam 1.10
601 swift 1.34 <p>
602     Lastly, if none of the above features of <c>equery</c> have answered your
603     question, try using <c>which</c> to manually search an ebuild with programs
604     like <c>cat</c>, <c>less</c> or <c>grep</c>:
605     </p>
606    
607     <pre caption="Other Useful Ways to Use which">
608     $ <i>grep HOMEPAGE $(equery which gentoolkit)</i>
609     HOMEPAGE="http://www.gentoo.org/proj/en/portage/tools/index.xml"
610     </pre>
611    
612     <warn>
613     Be aware that equery currently changes the format of the output if it is sent
614     through a pipe. The piped format is intended to be easier to parse by tools, but
615     you can also turn it off by adding the <c>--no-pipe</c> option. If you write
616     scripts that employ equery, you should be aware of this.
617     </warn>
618    
619 neysx 1.13 </body>
620     </section>
621 drobbins 1.1 </chapter>
622 cam 1.10
623 drobbins 1.1 <chapter>
624 neysx 1.13 <title>euse</title>
625 cam 1.9 <section>
626     <title>Introduction</title>
627     <body>
628 cam 1.10
629 cam 1.9 <p>
630 neysx 1.13 <c>euse</c> is a tool to see, set and unset USE flags at various places. For
631     more information on USE flags, please refer to the <uri
632 swift 1.31 link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>.
633 swift 1.19 Please see <c>euse -h</c> for complete help and all options.
634 cam 1.9 </p>
635 cam 1.10
636 cam 1.9 </body>
637     </section>
638     <section>
639 swift 1.19 <title>Viewing, Setting and Unsetting USE Flags</title>
640 neysx 1.13 <body>
641    
642     <p>
643 swift 1.31 The <c>euse -a</c> command reads the current active USE flags and displays
644 swift 1.19 them.
645 neysx 1.13 </p>
646    
647 swift 1.19 <note>
648 swift 1.31 There are 5 &quot;columns&quot; that <c>euse</c> now uses to show whether a
649     flag is set/unset and where all the flag has been set. The columns are as
650     follows -- +/-, set in the Environment, set in make.Conf, set in make.Defaults,
651     and set in make.Globals. The output looks like [+ECDG].
652 swift 1.19 </note>
653    
654     <pre caption="Viewing all active USE flags">
655 nightmorph 1.25 # <i>euse -a</i>
656 swift 1.19 X [+ CD ]
657     aalib [+ ]
658     acpi [+ C ]
659     alsa [+ C ]
660     apache2 [+ C ]
661     apm [+ D ]
662     avi [+ D ]
663     berkdb [+ D ]
664     bitmap-fonts [+ D ]
665     bonobo [+ ]
666     cdr [+ C ]
667     crypt [+ CD ]
668     cscope [+ C ]
669     cups [+ CD ]
670     curl [+ ]
671     emboss [+ D ]
672     encode [+ D ]
673     esd [+ ]
674     fam [+ ]
675     fbcon [+ C ]
676 nightmorph 1.25 firefox [+ C ]
677 swift 1.19 font-server [+ D ]
678     foomaticdb [+ D ]
679     fortran [+ D ]
680     gd [+ C ]
681     gdbm [+ D ]
682     gif [+ CD ]
683     gimpprint [+ C ]
684     gnome [+ CD ]
685     gphoto2 [+ ]
686     gpm [+ CD ]
687     gstreamer [+ C ]
688     gtk [+ D ]
689     gtkhtml [+ C ]
690     guile [+ ]
691     imagemagick [+ ]
692     imlib [+ CD ]
693     innodb [+ ]
694     ipv6 [+ D ]
695     javascript [+ C ]
696     jpeg [+ CD ]
697     kde [+ D ]
698     ldap [+ ]
699     libg++ [+ CD ]
700     libwww [+ CD ]
701     mad [+ CD ]
702     mbox [+ C ]
703     md5sum [+ C ]
704     mikmod [+ CD ]
705     mmx [+ C ]
706     motif [+ CD ]
707     mp3 [+ ]
708     mpeg [+ CD ]
709     mpeg4 [+ C ]
710     mysql [+ C ]
711     ncurses [+ CD ]
712     nls [+ D ]
713     nvidia [+ C ]
714     odbc [+ ]
715     offensive [+ ]
716 nightmorph 1.24 ogg [+ CD ]
717 swift 1.19 opengl [+ CD ]
718     oss [+ D ]
719     pam [+ CD ]
720     pdflib [+ CD ]
721     perl [+ CD ]
722     png [+ CD ]
723     python [+ CD ]
724     qt [+ D ]
725     quicktime [+ CD ]
726     readline [+ CD ]
727     ruby [+ ]
728     sdl [+ CD ]
729     slang [+ D ]
730     spell [+ CD ]
731     sse [+ C ]
732     ssl [+ CD ]
733     svga [+ CD ]
734     tcltk [+ C ]
735     tcpd [+ D ]
736     tiff [+ C ]
737     truetype [+ CD ]
738     usb [+ C ]
739     vanilla [+ C ]
740     x86 [+ C ]
741     xml [+ ]
742     xosd [+ C ]
743     xv [+ CD ]
744     xvid [+ C ]
745     zlib [+ CD ]
746 neysx 1.13 </pre>
747    
748     <p>
749 swift 1.31 Similarly you can use the <c>euse -a -g</c> command to only view active global
750     USE flags. The <c>euse -a -l</c> command does the same for active local USE
751     flags.<c>-g</c> &amp; <c>-l</c> are suboptions to <c>euse</c> and need an
752 swift 1.19 option before them (like <c>-a</c>) to function correctly.
753     </p>
754    
755     <pre caption="Viewing active local USE flags">
756     # <i>euse -a -l</i>
757     bitmap-fonts [+ D ]
758     font-server [+ D ]
759     fortran [+ D ]
760     gimpprint [+ C ]
761     md5sum [+ C ]
762     mpeg4 [+ C ]
763     nvidia [+ C ]
764     offensive [+ ]
765     truetype [+ CD ]
766 neysx 1.13 </pre>
767 cam 1.9
768 swift 1.19 <p>
769 swift 1.31 We can also use <c>euse</c> to set or unset use flags. The commands used for
770     this are <c>euse -E flagname</c> (enable a flag) and <c>euse -D flagname</c>
771 swift 1.19 (disable a flag).
772     </p>
773    
774     <warn>
775 swift 1.31 Do not use the <c>euse -E</c> or <c>euse -D</c> commands by themselves (without
776     a flag). It will set/unset ALL USE flags in <c>/etc/make.conf</c>. Although a
777     backup is kept at <path>/etc/make.conf.euse_backup</path>, please be careful
778 swift 1.19 while using <c>euse -E</c> or <c>euse -D</c>.
779     </warn>
780    
781     <pre caption="Setting and Unsetting USE flags">
782     <comment>(Enabling a USE Flag)</comment>
783     # <i> euse -E 3dfx</i>
784     /etc/make.conf was modified, a backup copy has been placed at /etc/make.conf.euse_backup
785    
786     <comment>(/etc/make.conf after the command)</comment>
787 nightmorph 1.25 USE="alsa acpi apache2 -arts cups cdr crypt cscope -doc fbcon \
788     firefox gd gif gimpprint gnome gpm gstreamer gtkhtml imlib \
789 swift 1.19 innodb -java javascript jpeg libg++ libwww mad mbox md5sum \
790 nightmorph 1.25 mikmod mmx motif mpeg mpeg4 mysql ncurses nvidia \
791 nightmorph 1.24 ogg odbc offensive opengl pam pdflib perl png python \
792 swift 1.19 quicktime readline sdl spell sse ssl svga tcltk tiff truetype usb \
793 nightmorph 1.24 vanilla X xosd xv xvid x86 zlib 3dfx"
794 swift 1.19
795     <comment>(Disabling the USE Flag)</comment>
796     # <i> euse -D 3dfx</i>
797     /etc/make.conf was modified, a backup copy has been placed at /etc/make.conf.euse_backup
798    
799     <comment>(/etc/make.conf after the command)</comment>
800 nightmorph 1.25 USE="alsa acpi apache2 -arts cups cdr crypt cscope -doc fbcon \
801     firefox gd gif gimpprint gnome gpm gstreamer gtkhtml imlib \
802 swift 1.19 innodb -java javascript jpeg libg++ libwww mad mbox md5sum \
803 nightmorph 1.25 mikmod mmx motif mpeg mpeg4 mysql ncurses nvidia \
804 nightmorph 1.24 ogg odbc offensive opengl pam pdflib perl png python \
805 swift 1.19 quicktime readline sdl spell sse ssl svga tcltk tiff truetype usb \
806 nightmorph 1.24 vanilla X xosd xv xvid x86 zlib -3dfx"
807 cam 1.10 </pre>
808    
809 cam 1.9 <note>
810 neysx 1.13 <c>euse</c> does not physically remove the flag from make.conf. It just adds a
811     - (minus) before the flag to unset it. You may have to manually clean up your
812     make.conf to avoid unwanted variables.
813 cam 1.9 </note>
814 cam 1.10
815 cam 1.9 </body>
816     </section>
817 drobbins 1.1 </chapter>
818    
819     <chapter>
820 neysx 1.13 <title>Other tools</title>
821 cam 1.9 <section>
822 neysx 1.13 <title>revdep-rebuild</title>
823 cam 1.9 <body>
824 cam 1.10
825 cam 1.9 <p>
826 neysx 1.13 This tool is Gentoo's Reverse Dependency rebuilder. It will scan your installed
827     ebuilds to find packages that have become broken as a result of an upgrade of a
828     package they depend on. It can emerge those packages for you but it can also
829 swift 1.34 happen that a given package does not work any more with the currently installed
830 neysx 1.16 dependencies, in which case you should upgrade the broken package to a more
831 neysx 1.13 recent version. revdep-rebuild will pass flags to emerge which lets you use the
832     <c>--pretend</c> flag to see what is going to be emerged again before you go any
833     further.
834 cam 1.9 </p>
835    
836 neysx 1.13 <pre caption="Running revdep-rebuild in pretend mode">
837     # <i>revdep-rebuild -p</i>
838    
839 swift 1.34 * Configuring search environment for revdep-rebuild
840 cam 1.10
841 swift 1.34 * Checking reverse dependencies
842     * Packages containing binaries and libraries broken by a package update
843     * will be emerged.
844    
845     * Collecting system binaries and libraries
846     * Generated new 1_files.rr
847     * Collecting complete LD_LIBRARY_PATH
848     * Generated new 2_ldpath.rr
849     * Checking dynamic linking consistency
850     [ 48% ] * broken /usr/lib/gstreamer-0.10/libgsttaglib.la (requires /usr/lib/libtag.la)
851     [ 64% ] * broken /usr/lib/libgdkglext-x11-1.0.la (requires /usr/lib/libGLU.la)
852     [ 67% ] * broken /usr/lib/libgtkglext-x11-1.0.la (requires /usr/lib/libGLU.la)
853     [ 85% ] * broken /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gdkgl/_gdkgl.la (requires /usr/lib/libGLU.la)
854     * broken /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gtkgl/_gtkgl.la (requires /usr/lib/libGLU.la)
855     [ 97% ] * broken /usr/qt/3/lib/libqt-mt.la (requires -lpng)
856     [ 100% ]
857     * Generated new 3_broken.rr
858     * Assigning files to packages
859     * /usr/lib/gstreamer-0.10/libgsttaglib.la -> media-plugins/gst-plugins-taglib
860     * /usr/lib/libgdkglext-x11-1.0.la -> x11-libs/gtkglext
861     * /usr/lib/libgtkglext-x11-1.0.la -> x11-libs/gtkglext
862     * /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gdkgl/_gdkgl.la -> dev-python/pygtkglext
863     * /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gtkgl/_gtkgl.la -> dev-python/pygtkglext
864     * /usr/qt/3/lib/libqt-mt.la -> x11-libs/qt
865     * Generated new 4_raw.rr and 4_owners.rr
866     * Cleaning list of packages to rebuild
867     * Generated new 4_pkgs.rr
868     * Assigning packages to ebuilds
869     * Generated new 4_ebuilds.rr
870     * Evaluating package order
871     * Generated new 5_order.rr
872     * All prepared. Starting rebuild
873     emerge --oneshot --pretend dev-python/pygtkglext:0
874     media-plugins/gst-plugins-taglib:0.10
875     x11-libs/gtkglext:0
876     x11-libs/qt:3
877    
878     These are the packages that would be merged, in order:
879    
880     Calculating dependencies... done!
881     [ebuild R ] media-plugins/gst-plugins-taglib-0.10.17
882     [ebuild R ] x11-libs/gtkglext-1.2.0
883     [ebuild R ] x11-libs/qt-3.3.8b-r2
884     [ebuild R ] dev-python/pygtkglext-1.1.0
885     * Now you can remove -p (or --pretend) from arguments and re-run revdep-rebuild.
886 neysx 1.13 </pre>
887 cam 1.10
888     <p>
889 neysx 1.13 If you need to rebuild some packages, you may run <c>revdep-rebuild</c> without
890     the <c>-p</c> flag and the listed packages will be emerged again.
891 cam 1.9 </p>
892    
893     </body>
894     </section>
895     <section>
896 neysx 1.13 <title>glsa-check</title>
897 cam 1.9 <body>
898 cam 1.10
899     <p>
900 swift 1.34 <c>glsa-check</c> is mainly a test tool that keeps track of the various GLSA's
901 neysx 1.13 (Gentoo Linux Security Advisory) and will eventually be integrated into
902 nightmorph 1.32 <c>emerge</c> and <c>equery</c>.
903 swift 1.19 </p>
904 cam 1.10
905 cam 1.9 </body>
906     </section>
907 nightmorph 1.30 <section>
908     <title>eread</title>
909     <body>
910    
911     <p>
912     <c>eread</c> is a simple utility to display elog files produced by
913     >=<c>portage-2.1</c>. You can set the saving of elog files by setting a couple
914     of variables in <path>/etc/make.conf</path>:
915     </p>
916    
917     <pre caption="Enabling elog in /etc/make.conf">
918     PORTAGE_ELOG_CLASSES="log"
919     PORTAGE_ELOG_SYSTEM="save"
920     </pre>
921    
922     <note>
923     This is just one way of saving elog messages. For more information on how
924     Portage's elog system works, please refer to the appropriate page in the <uri
925     link="/doc/en/handbook/handbook-x86.xml?part=3&amp;chap=1#doc_chap4">Portage
926     Handbook</uri>.
927     </note>
928    
929     <p>
930     Once you've set up elog to your satisfaction, just run <c>eread</c> to view your
931     log files.
932     </p>
933    
934     <pre caption="Using eread">
935     $ <i>eread</i>
936    
937 swift 1.31 This is a list of portage log items. Choose a number to view that file or type
938     q to quit.
939 nightmorph 1.30
940     1) app-portage:gentoolkit-0.2.4_pre2:20070320-000256.log
941     2) app-portage:gentoolkit-0.2.4_pre2:20070320-000258.log
942     3) app-portage:gentoolkit-0.2.4_pre2:20070320-000319.log
943     4) app-portage:gentoolkit-0.2.3:20070320-000408.log
944     Choice?
945     </pre>
946    
947     <p>
948     Select a number and the file will be displayed using the paging program
949     specified in the PAGER environment variable. If PAGER is not set, it will use
950     <c>less</c>.
951     </p>
952    
953     <p>
954     After displaying the elog item, you will be prompted if you want to delete the
955     file.
956     </p>
957    
958     </body>
959     </section>
960 nightmorph 1.33 <section>
961     <title>eclean</title>
962     <body>
963    
964     <p>
965     <c>eclean</c> is a tool to remove old source files and old binary packages from
966     your system.
967     </p>
968    
969     <p>
970     When you build and install packages, the source files are downloaded and
971     preserved in DISTDIR, usually <path>/usr/portage/distfiles</path>. This can
972     accumulate several gigs of material over time if you don't clean it
973     periodically. You can run <c>eclean-dist</c> to clean only source files from
974     DISTDIR.
975     </p>
976    
977     <p>
978     You can create archives of installed packages by using <c>quickpg</c> or
979     FEATURES="buildpkg". These archived packages are kept in PKGDIR, usually
980     <path>/usr/portage/packages</path>. When you no longer need to keep them around,
981     or if they're too old, you can run <c>eclean-pkg</c> to remove them from PKGDIR.
982     It's a good way to ensure that any binary packages you have are only the latest
983     versions.
984     </p>
985    
986     <p>
987     For more information on <c>eclean</c> and tips on maintaining a cruft-free
988     system, please read <c>man eclean</c>.
989     </p>
990    
991     </body>
992     </section>
993 drobbins 1.1 </chapter>
994 vapier 1.11 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20