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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.33 Revision 1.34
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.33 2010/10/03 18:47:51 nightmorph Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.34 2011/08/14 17:02:52 swift Exp $ -->
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 4
5<guide> 5<guide>
6<title>Gentoolkit</title> 6<title>Gentoolkit</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="mbutcher@aleph-null.tv">Matt Butcher</mail> 9 <mail link="mbutcher@aleph-null.tv">Matt Butcher</mail>
10</author> 10</author>
11<author title="Editor"> 11<author title="Editor">
12 <!-- zhen@gentoo.org -->John P. Davis 12 <!-- zhen@gentoo.org -->John P. Davis
13</author> 13</author>
14<author title="Editor"> 14<author title="Editor">
15 <mail link="erwin@gentoo.org">Erwin</mail> 15 <mail link="erwin@gentoo.org">Erwin</mail>
16</author> 16</author>
17<author title="Editor"> 17<author title="Editor">
18 <mail link="fox2mike@gentoo.org">Shyam Mani</mail> 18 <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
19</author> 19</author>
20<author title="Editor"> 20<author title="Editor">
21 <mail link="neysx@gentoo.org">Xavier Neys</mail> 21 <mail link="neysx@gentoo.org">Xavier Neys</mail>
22</author> 22</author>
23<author title="Editor"> 23<author title="Editor">
24 <mail link="karltk@gentoo.org">Karl Trygve</mail> 24 <mail link="karltk@gentoo.org">Karl Trygve</mail>
25</author> 25</author>
26<author title="Editor"> 26<author title="Editor">
27 <mail link="yoswink@gentoo.org">José Luis Rivero</mail> 27 <mail link="yoswink@gentoo.org">José Luis Rivero</mail>
28</author> 28</author>
29<author title="Editor"> 29<author title="Editor">
30 <mail link="nightmorph@gentoo.org">Joshua Saddler</mail> 30 <mail link="nightmorph@gentoo.org">Joshua Saddler</mail>
31</author> 31</author>
32<author title="Editor">
33 <mail link="douglasjanderson@gmail.com">Douglas Anderson</mail>
34</author>
32 35
33<abstract> 36<abstract>
34Gentoolkit is a suite of tools to ease the administration of a Gentoo system. 37Gentoolkit is a suite of tools to ease the administration of a Gentoo system.
35This document covers the basics of some of the tools present in Gentoolkit. 38This document covers the basics of some of the tools present in Gentoolkit.
36</abstract> 39</abstract>
37 40
38<!-- Licensed under GFDL --> 41<!-- Licensed under GFDL -->
39 42
40<version>2</version> 43<version>3</version>
41<date>2010-10-03</date> 44<date>2011-06-24</date>
42 45
43<chapter> 46<chapter>
44<title>Introduction</title> 47<title>Introduction</title>
45<section> 48<section>
46<title>What is Gentoolkit?</title> 49<title>What is Gentoolkit?</title>
47<body> 50<body>
48 51
49<p> 52<p>
50Gentoo is a unique distribution and presents some complexities that simply 53Gentoo is a unique distribution and presents some complexities that simply
51don't exist for other distributions. As Gentoo developers and contributors 54don't exist for other distributions. As Gentoo developers and contributors
52discovered some of these complexities, they also wrote tools to help users and 55discovered some of these complexities, they also wrote tools to help users and
53administrators work around them. Many of these tools have been contributed to 56administrators work around them. Many of these tools have been contributed to
54the Gentoo project and are included in the package 57the Gentoo project and are included in the package
55<c>app-portage/gentoolkit</c>. 58<c>app-portage/gentoolkit</c>.
56</p> 59</p>
76<section> 79<section>
77<title>Installation</title> 80<title>Installation</title>
78<body> 81<body>
79 82
80<p> 83<p>
81Just as with any Gentoo package, installation is just a simple emerge. 84Just as with any Gentoo package, installation is just a simple emerge.
82</p> 85</p>
83 86
84<pre caption="Getting gentoolkit"> 87<pre caption="Getting gentoolkit">
85# <i>emerge gentoolkit</i> 88# <i>emerge gentoolkit</i>
86</pre> 89</pre>
87 90
88<note> 91<note>
89Many of the tools in gentoolkit reveal important information about your system 92Many of the tools in gentoolkit reveal important information about your system
90or require root privilege. For that reason, some of the programs may only be 93or require root privilege. For that reason, some of the programs may only be
91executed (or only function properly) if run by a user with root permission. 94executed (or only function properly) if run by a user with root privileges.
92</note> 95</note>
93 96
94</body> 97</body>
95</section> 98</section>
96<section> 99<section>
97<title>Finding Documentation</title> 100<title>Finding Documentation</title>
98<body> 101<body>
99 102
100<p> 103<p>
101Any documentation that a program might have (other than man pages) is stored in 104Any documentation that a program might have (other than man pages) is stored in
102<path>/usr/share/doc/gentoolkit-[version]/[program-name]/</path>. 105<path>/usr/share/doc/gentoolkit-[version]/[program-name]/</path>.
103</p> 106</p>
104 107
105</body> 108</body>
106</section> 109</section>
107</chapter> 110</chapter>
108 111
109<chapter> 112<chapter>
110<title>equery</title> 113<title>equery</title>
111<section> 114<section>
112<title>Introduction</title> 115<title>Introduction</title>
113<body> 116<body>
114 117
115<p> 118<p>
116<c>equery</c> is a tool that displays a great deal of useful information about 119<c>equery</c> is a tool that displays useful information about the packages on
117the packages on your system and much more. <c>equery --help</c> gives you the 120your system. <c>equery</c> is based on a system of modules.
118full set of options. 121Every module has a shorthand name. For example, <c>equery l gcc</c> is the same
122as <c>equery list gcc</c>. <c>equery --help</c> explains global options
123and lists all available modules and their shorthand names.
124<c>equery --help module</c> will display the help screen for a specific
125module. Lastly, <c>man equery</c> provides a detailed explanation of all
126available modules and options, and provides useful examples.
127</p>
128
119</p> 129<p>
130Below 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>
136sys-devel/gcc-4.3.2-r3
137$ <i>equery --quiet list sys-devel/gcc</i> # <comment>category/package</comment>
138sys-devel/gcc-4.3.2-r3
139$ <i>equery --quiet list '>=sys-devel/gcc-4'</i> # <comment>atom syntax</comment>
140sys-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>
168dev-dotnet/flickrnet-bin-2.2
169dev-ruby/flickr-1.0.2-r1
170dev-ruby/flickr-1.0.2-r2
171dev-ruby/rflickr-20060201
172media-gfx/kflickr-0.6
173[...]
174</pre>
120 175
121<note> 176<note>
122Not all features listed by <c>equery --help</c> have been implemented yet. 177Globbing support replaced a number of older options in <c>equery</c>.
123Those that have not been, are mentioned clearly. You will also see that 178For example, to act on all packages in a certain set, use <c>'*'</c>.
124every command has a short option, e.g. <c>b</c> instead of <c>belongs</c>. 179To act on all packages in a category, use <c>'category-name/*'</c>.
125</note> 180</note>
126 181
127<note> 182<warn>
183Don't forget to quote input when using special shell characters
184like asterisks or greater than/less than signs.
185</warn>
186
187<p>
188The next few sections in this document give a quick introduction to the
189different <c>equery</c> modules.
190</p>
191
192</body>
193</section>
194<section>
195<title>Finding the Package That a File Came From with belongs (b)</title>
196<body>
197
198<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<p>
205<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.
207Since no file on your system should be owned by two packages, this is a safe
208optimization.
209</p>
210
211</body>
212</section>
213<section>
214<title>Viewing ChangeLog Entries with changes (c)</title>
215<body>
216
217<p>
218<c>changes</c> lets you view ChangeLog entries for a package version or range
219of versions. Imagine after an <c>emerge --sync</c>, you
220notice Portage is going to be upgraded and want to check what has changed:
221</p>
222
223<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</body>
235</section>
236<section>
237<title>Verifying Package Integrity with check (k)</title>
238<body>
239
240<p>
241Sometimes it is useful to check a package's integrity. <c>equery</c> can
242verify MD5 sums as well as timestamps to indicate when a package might
243have been corrupted, replaced, or removed.
244</p>
245
246<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</pre>
251
252</body>
253</section>
254<section>
255<title>Listing All Packages Depending on Package X with depends (d)</title>
256<body>
257
258<p>
259Ever 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>
262option.
263</p>
264
265<pre caption="Looking for Packages Depending on pygtk">
266$ <i>equery depends pygtk</i>
267 * Searching for pygtk ...
268app-admin/pessulus-2.24.0 (>=dev-python/pygtk-2.6.0)
269app-editors/gedit-2.24.3 (python ? >=dev-python/pygtk-2.12)
270dev-libs/libgweather-2.24.3 (python ? >=dev-python/pygtk-2)
271dev-python/gnome-python-base-2.22.3 (>=dev-python/pygtk-2.10.3)
272dev-python/gnome-python-desktop-base-2.24.1 (>=dev-python/pygtk-2.10.3)
273[...]
274</pre>
275
276</body>
277</section>
278<section>
279<title>Getting Dependency Graphs with depgraph (g)</title>
280<body>
281
282<p>
283<c>depgraph</c> is the opposite of <c>depends</c>. You pass it a package, and
284it will find the packages <e>it</e> depends on (not that depend on it).
285When 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
287the <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</pre>
307
308<p>
309Notice how <c>jre</c> is a direct dependency and <c>jdk</c> is an indirect
310dependency if the <c>java</c> USE flag is set.
311</p>
312
313</body>
314</section>
315<section>
316<title>Listing Files Installed by a Package with files (f)</title>
317<body>
318
319<p>
320<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
322layout. Use <c>--filter</c> to only find a certain type of file. For example,
323to find where executables were installed, use <c>--filter=cmd</c>, and to
324quickly 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[...]
365</pre>
366
367</body>
368</section>
369<section>
370<title>Looking for Packages that Have a Specific USE Flag with hasuse (h)</title>
371<body>
372
373<p>
374You 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
376it 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</p>
379
380<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</pre>
391
392</body>
393</section>
394<section>
395<title>Listing Packages with list (l)</title>
396<body>
397
398<p>
399<c>list</c> is a simple, yet powerful module to list packages that are installed,
400in the Portage tree or in an overlay.
401</p>
402
403<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</pre>
420
421<p>
422The standard query will search installed packages for the given package name.
423Passing in '*' displays all packages in the set. In the leftmost field, we
424see that all the above packages are <c>I</c>nstalled and from the <c>P</c>ortage
425tree. They're not masked (the second field is blank), and they're all installed
426in the default slot (0).
427</p>
428
429<p>
430This time we are going to use local options to look for packages in the
431Portage tree and overlays.
432</p>
433
434<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</pre>
447
448<p>
449In this example you can see version 7.2.182 is installed and there are no
450versions available from an overlay. You can see which versions are keyword
451masked by the <c>~</c> in the second field.
452</p>
453
454</body>
455</section>
456<section>
457<title>Viewing Package Metadata with meta (m)</title>
458<body>
459
460<p>
461Each package in the Portage tree provides at least some metadata about
462its maintainer, herd, etc. Read about <uri
463link="http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&amp;chap=4">Gentoo
464Metadata</uri>. The amount of useful information depends on how much package
465maintainers decide to provide. With no options, <c>meta</c> returns some basic
466useful information.
467</p>
468
469<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</pre>
481
482<p>
483When the maintainer provides extra information, it can be very useful:
484</p>
485
486<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</body>
507</section>
508<section>
509<title>Finding Package Sizes with size (s)</title>
510<body>
511
512<p>
513Have you ever been curious to find out how much space a specific package is
514occupying? Since a package could have its files over a number of directories,
515the usual <c>du -hc</c> might not give you the correct figure. Not to worry,
516here comes <c>equery</c> to the rescue!
517</p>
518
519<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
526<p>
527As you can see, <c>size</c> prints the total space used in human-readable
528units and lists the total number of files the package has. To get the
529total 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
540flags are available for a specific package, and which of those flags is
541currently 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</pre>
573
574<p>
575Here, a number of USE flags are enabled in <c>gstreamer</c>'s plugin
576meta-package, but you can see that there are other USE flags available.
577For more information on USE flags, please refer to the <uri
578link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>
579chapter of the <uri link="/doc/en/handbook/">Gentoo Handbook</uri>.
580</p>
581
582</body>
583</section>
584<section>
585<title>Finding the Ebuild Path with which (w)</title>
586<body>
587
588<p>
589<c>which</c> is a simple script to help you quickly find the file path to an
590ebuild. If you pass an unversioned package name, <c>which</c> will return the
591path to the newest installable ebuild version, in other words, the ebuild
592Portage would use if you typed <c>emerge package</c>. Pass in a versioned
593package to get the path to that ebuild.
594</p>
595
596<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</pre>
600
601<p>
602Lastly, if none of the above features of <c>equery</c> have answered your
603question, try using <c>which</c> to manually search an ebuild with programs
604like <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>
609HOMEPAGE="http://www.gentoo.org/proj/en/portage/tools/index.xml"
610</pre>
611
612<warn>
128Be aware that equery currently changes the format of the output if it is sent 613Be aware that equery currently changes the format of the output if it is sent
129through a pipe. The piped format is intended to be easier to parse by tools, but 614through a pipe. The piped format is intended to be easier to parse by tools, but
130you can also turn it off by adding the <c>--no-pipe</c> option. If you write 615you can also turn it off by adding the <c>--no-pipe</c> option. If you write
131scripts that employ equery, you should be aware of this. 616scripts that employ equery, you should be aware of this.
132</note> 617</warn>
133
134</body>
135</section>
136<section>
137<title>Finding the Package That a File Came From</title>
138<body>
139
140<p>
141<c>equery</c> also provides the functionality of finding the package that a
142file came from, using <c>belongs</c> command (or just <c>b</c>).
143</p>
144
145<pre caption="Finding the ebuild that installed a given file">
146# <i>equery belongs /usr/bin/audacious</i>
147[ Searching for file(s) /usr/bin/audacious in *... ]
148media-sound/audacious-1.1.2 (/usr/bin/audacious)
149</pre>
150
151<p>
152By using the <c>-f</c> option, you may search for packages with files
153matching any regular expression. The <c>-e</c> option is useful for
154terminating your search immediately when a match is found.
155</p>
156
157</body>
158</section>
159<section>
160<title>Verifying Package Integrity</title>
161<body>
162
163<p>
164Sometimes it is useful to check a package's integrity. <c>equery</c> can
165verify md5 sums as well as timestamps to indicate when a package might
166have been corrupted, replaced, or removed.
167</p>
168
169<pre caption="OK package integrity">
170# <i>equery check gentoolkit</i>
171[ Checking app-portage/gentoolkit-0.2.0 ]
172 * 54 out of 54 files good
173</pre>
174
175<p>
176Please note that if you change configuration files after installation,
177these may be reported as "not good".
178</p>
179
180</body>
181</section>
182<section>
183<title>List of all packages depending on ...</title>
184<body>
185
186<p>
187<c>equery</c> is able to list all direct dependencies matching a package.
188The function we should use to do this is <c>depends</c> and it's as easy as:
189</p>
190
191<pre caption="Looking for packages depending on pygtk">
192# <i>equery depends pygtk</i>
193[ Searching for packages depending on pygtk... ]
194app-office/dia-0.93
195dev-python/gnome-python-2.0.0-r1
196gnome-extra/gdesklets-core-0.26.2
197media-gfx/gimp-2.0.4
198x11-libs/vte-0.11.11-r1
199</pre>
200
201</body>
202</section>
203<section>
204<title>Dependency Graphs</title>
205<body>
206
207<p>
208<c>equery</c> is capable of giving us a dependency graph for a specified
209package. The dependency graph gives a listing of all the packages that have
210direct and indirect dependencies on the package in question.
211</p>
212
213<pre caption="Dependency Graph for cdrtools">
214# <i>equery depgraph cdrtools</i>
215Displaying dependencies for app-cdr/cdrtools-2.01_alpha37
216`-- app-cdr/cdrtools-2.01_alpha37
217 `-- sys-libs/glibc-2.3.4.20040808 (virtual/libc)
218 `-- sys-kernel/linux-headers-2.4.22 (virtual/os-headers)
219 `-- sys-apps/baselayout-1.10.4
220 `-- sys-apps/sysvinit-2.85-r1
221 `-- sys-apps/gawk-3.1.3-r1
222 `-- sys-apps/util-linux-2.12-r4
223 `-- sys-apps/sed-4.0.9
224 `-- sys-libs/ncurses-5.4-r4
225 `-- sys-apps/pam-login-3.14
226 `-- sys-libs/pam-0.77-r1
227 `-- sys-libs/cracklib-2.7-r10
228 `-- sys-apps/miscfiles-1.3-r1
229 `-- app-arch/gzip-1.3.5-r1
230 `-- sys-apps/portage-2.0.50-r10
231</pre>
232
233<p>
234For example, while glibc is a direct dependency for cdrtools,linux-headers
235are an indirect dependency. Note that the output also includes information
236about virtual packages. In the example above, <c>cdrtools</c> is actually
237written to require virtual/libc, not sys-libs/glibc, but on the given
238system in the example sys-libs/glibc provides virtual/libc.
239</p>
240
241</body>
242</section>
243<section>
244<title>Listing Files Belonging to an Ebuild</title>
245<body>
246
247<p>
248<c>equery</c> can list the files that belong to an installed ebuild. If I
249don't know the files that Gentoolkit has installed on the system, I will
250use <c>equery</c> to show them.
251</p>
252
253<pre caption="Listing files">
254# <i>equery files gentoolkit</i>
255[ Searching for packages matching gentoolkit... ]
256app-portage/gentoolkit-0.2.0
257* Contents of app-portage/gentoolkit-0.2.0:
258/usr
259/usr/bin
260/usr/bin/equery
261/usr/bin/etcat
262/usr/bin/euse
263/usr/bin/glsa-check
264/usr/bin/qpkg
265/usr/bin/revdep-rebuild
266/usr/lib
267/usr/lib/gentoolkit
268/usr/lib/gentoolkit/pym
269/usr/lib/gentoolkit/pym/gentoolkit
270/usr/lib/gentoolkit/pym/gentoolkit/__init__.py
271/usr/lib/gentoolkit/pym/gentoolkit/gentoolkit.py
272/usr/lib/gentoolkit/pym/gentoolkit/pprinter.py
273/usr/lib/gentoolkit/pym/glsa.py
274/usr/sbin
275/usr/share
276/usr/share/doc
277/usr/share/doc/gentoolkit-0.2.0_pre10
278
279[...]
280</pre>
281
282<p>
283The command <c>files</c> of <c>equery</c> provide some options to modify
284the output. You can look them all up in the <c>equery</c> man page.
285</p>
286
287</body>
288</section>
289<section>
290<title>Looking for packages that use a specific USE flag</title>
291<body>
292
293<p>
294If you want to find which packages on your system that make use of a specific
295USE flag, <c>equery</c> has the function <c>hasuse</c>:
296</p>
297
298<pre caption="Searching packages which use the firefox USE flag">
299# <i>equery hasuse firefox</i>
300[ Searching for USE flag firefox in all categories among: ]
301 * installed packages
302[I--] [ ] dev-python/gnome-python-extras-2.14.0-r1 (0)
303[I--] [ ] media-video/totem-2.16.4 (0)
304</pre>
305
306</body>
307</section>
308<section>
309<title>Listing Packages</title>
310<body>
311
312<p>
313<c>equery</c> has a power feature to list packages belonging to our system,
314portage or even an overlay. Let's try this:
315</p>
316
317<pre caption="Listing packages with equery">
318# <i>equery list gentoolkit</i>
319[ Searching for package 'gentoolkit' in all categories among: ]
320 * installed packages
321[I--] [ ] app-portage/gentoolkit-0.2.0 (0)
322</pre>
323
324<p>
325The standard query will search our installed packages for the name given.
326If found, the following info will be displayed: the package location between
327the first square brackets (I for Installed packages, P for Portage, O for
328Overlay), the possible masks between the second (~ by keyword, - by arch or
329M hard masked), then the category and complete name and last of all, the slot
330in which the package is stored.
331</p>
332
333<p>
334Another example, this time we are going to use the local options in order
335to look for packages in our portage tree and overlay.
336</p>
337
338<pre caption="Using local options with equery">
339# <i>equery list -p -o vim</i>
340[ Searching for package 'vim' in all categories among: ]
341 * installed packages
342[I--] [ ] app-editors/vim-6.3-r4 (0)
343 * Portage tree (/usr/portage)
344[-P-] [M~] app-editors/vim-7.0_alpha20050126 (0)
345[-P-] [M~] app-editors/vim-7.0_alpha20050201 (0)
346[-P-] [ ] app-editors/vim-6.3-r2 (0)
347[-P-] [M~] app-editors/vim-7.0_alpha20050122 (0)
348[-P-] [M~] app-editors/vim-core-7.0_alpha20050126 (0)
349[-P-] [ ] app-editors/vim-core-6.3-r3 (0)
350[-P-] [M~] app-editors/vim-core-7.0_alpha20050122 (0)
351[-P-] [M~] app-editors/vim-core-7.0_alpha20050201 (0)
352[-P-] [ ] app-editors/vim-core-6.3-r4 (0)
353 * overlay tree (/opt/ebuilds)
354</pre>
355
356</body>
357</section>
358<section>
359<title>Finding Package Sizes</title>
360<body>
361
362<p>
363Ever been curious to find out how much space a specific package is occupying?
364Since a package could have its files over a number of directories, the usual
365<c>du -hc</c> might not give you the correct figure. Not to worry, here comes
366<c>equery</c> to the rescue!
367</p>
368
369<pre caption="Package Size">
370# <i>equery size openoffice-bin</i>
371* app-office/openoffice-bin-1.1.2
372 Total Files : 2908
373 Total Size : 223353.31 KiB
374</pre>
375
376<p>
377As you can see, <c>equery</c> prints the total space used in kilobytes and
378also lists the total number of files the package has.
379</p>
380
381</body>
382</section>
383<section>
384<title>Package-wise list of USE Flags</title>
385<body>
386
387<p>
388<c>equery</c> can be used to give us information about what USE flags
389are being used by a specific package. It also tells us what our current USE
390flags are for a package and also what USE flags are available for the package.
391</p>
392
393<pre caption="Set and Unset USE Flags">
394# <i>equery uses wireshark</i>
395[ Colour Code : set unset ]
396[ Legend : (U) Col 1 - Current USE flags ]
397[ : (I) Col 2 - Installed With USE flags ]
398
399 U I [ Found these USE variables in : net-analyzer/wireshark-0.99.4 ]
400 - - adns : Adds support for the adns DNS client library
401 + + gtk : Adds support for x11-libs/gtk+ (The GIMP Toolkit)
402 - - ipv6 : Adds support for IP version 6
403 - - kerberos : Adds kerberos support
404 - - portaudio : Adds support for the crossplatform portaudio audio API
405 - - selinux : !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
406 - - snmp : Adds support for the Simple Network Management Protocol if available
407 + + ssl : Adds support for Secure Socket Layer connections
408 - - threads : Adds threads support for various packages. Usually pthreads
409</pre>
410
411<p>
412I have installed wireshark with only the gtk and ssl flags set, but there are
413several other USE flags for wireshark still available. For more information on
414USE flags, please refer to the <uri
415link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>
416chapter of the <uri link="/doc/en/handbook/">Gentoo Handbook</uri>.
417</p>
418
419</body>
420</section>
421<section>
422<title>Where's the ebuild?</title>
423<body>
424
425<p>
426We can also find out which ebuild is being used for a specific package using
427<c>equery</c>. This is done by using the <c>equery which</c> command which
428displays the full path to the ebuild.
429</p>
430
431<pre caption="Displaying the ebuild path">
432# <i>equery which cdrtools</i>
433/usr/portage/app-cdr/cdrtools/cdrtools-2.01_alpha37.ebuild
434</pre>
435 618
436</body> 619</body>
437</section> 620</section>
438</chapter> 621</chapter>
439 622
440<chapter> 623<chapter>
441<title>euse</title> 624<title>euse</title>
442<section> 625<section>
443<title>Introduction</title> 626<title>Introduction</title>
444<body> 627<body>
445 628
446<p> 629<p>
447<c>euse</c> is a tool to see, set and unset USE flags at various places. For 630<c>euse</c> is a tool to see, set and unset USE flags at various places. For
448more information on USE flags, please refer to the <uri 631more information on USE flags, please refer to the <uri
449link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>. 632link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>.
631 814
632</body> 815</body>
633</section> 816</section>
634</chapter> 817</chapter>
635 818
636<chapter> 819<chapter>
637<title>Other tools</title> 820<title>Other tools</title>
638<section> 821<section>
639<title>revdep-rebuild</title> 822<title>revdep-rebuild</title>
640<body> 823<body>
641 824
642<p> 825<p>
643This tool is Gentoo's Reverse Dependency rebuilder. It will scan your installed 826This tool is Gentoo's Reverse Dependency rebuilder. It will scan your installed
644ebuilds to find packages that have become broken as a result of an upgrade of a 827ebuilds to find packages that have become broken as a result of an upgrade of a
645package they depend on. It can emerge those packages for you but it can also 828package they depend on. It can emerge those packages for you but it can also
646happen that a given package does not work anymore with the currently installed 829happen that a given package does not work any more with the currently installed
647dependencies, in which case you should upgrade the broken package to a more 830dependencies, in which case you should upgrade the broken package to a more
648recent version. revdep-rebuild will pass flags to emerge which lets you use the 831recent version. revdep-rebuild will pass flags to emerge which lets you use the
649<c>--pretend</c> flag to see what is going to be emerged again before you go any 832<c>--pretend</c> flag to see what is going to be emerged again before you go any
650further. 833further.
651</p> 834</p>
652 835
653<pre caption="Running revdep-rebuild in pretend mode"> 836<pre caption="Running revdep-rebuild in pretend mode">
654# <i>revdep-rebuild -p</i> 837# <i>revdep-rebuild -p</i>
655 838
839 * Configuring search environment for revdep-rebuild
840
656Checking reverse dependencies... 841 * Checking reverse dependencies
657Packages containing binaries and libraries broken by any package update, 842 * Packages containing binaries and libraries broken by a package update
658will be recompiled. 843 * will be emerged.
659 844
660Collecting system binaries and libraries... done. 845 * Collecting system binaries and libraries
661 (/root/.revdep-rebuild.1_files) 846 * Generated new 1_files.rr
662
663Collecting complete LD_LIBRARY_PATH... done. 847 * Collecting complete LD_LIBRARY_PATH
664 (/root/.revdep-rebuild.2_ldpath) 848 * Generated new 2_ldpath.rr
665
666Checking dynamic linking consistency... 849 * Checking dynamic linking consistency
667 broken /usr/lib/ao/plugins-2/libarts.so (requires libartsc.so.0) 850[ 48% ] * broken /usr/lib/gstreamer-0.10/libgsttaglib.la (requires /usr/lib/libtag.la)
668 broken /usr/lib/kde3/libkpresenterpart.so (requires libartskde.so.1 libqtmcop.so.1 851[ 64% ] * broken /usr/lib/libgdkglext-x11-1.0.la (requires /usr/lib/libGLU.la)
669 libsoundserver_idl.so.1 libkmedia2_idl.so.1 libartsflow.so.1 libartsflow_idl.so.1 libmcop.so.1) 852[ 67% ] * broken /usr/lib/libgtkglext-x11-1.0.la (requires /usr/lib/libGLU.la)
670 broken /usr/lib/ruby/site_ruby/1.8/i686-linux/fox.so (requires libFOX-1.0.so.0) 853[ 85% ] * broken /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gdkgl/_gdkgl.la (requires /usr/lib/libGLU.la)
671 broken /usr/lib/xine/plugins/1.0.0/xineplug_ao_out_arts.so (requires libartsc.so.0) 854 * broken /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gtkgl/_gtkgl.la (requires /usr/lib/libGLU.la)
672 broken /usr/lib/perl5/vendor_perl/5.8.0/i686-linux/auto/SDL_perl/SDL_perl.so (requires libSDL_gfx.so.0) 855[ 97% ] * broken /usr/qt/3/lib/libqt-mt.la (requires -lpng)
673 broken /usr/lib/libloudmouth-1.so.0.0.0 (requires libgnutls.so.10) 856[ 100% ]
674 broken /usr/bin/k3b (requires libartskde.so.1 libqtmcop.so.1 libsoundserver_idl.so.1 libkmedia2_idl.so.1 857 * Generated new 3_broken.rr
675 libartsflow.so.1 libartsflow_idl.so.1 libmcop.so.1) 858 * Assigning files to packages
676 broken /usr/bin/lua (requires libhistory.so.4) 859 * /usr/lib/gstreamer-0.10/libgsttaglib.la -> media-plugins/gst-plugins-taglib
677 broken /usr/bin/lyx (requires libAiksaurus-1.0.so.0) 860 * /usr/lib/libgdkglext-x11-1.0.la -> x11-libs/gtkglext
678 broken /usr/bin/luac (requires libhistory.so.4) 861 * /usr/lib/libgtkglext-x11-1.0.la -> x11-libs/gtkglext
679 broken /usr/bin/avidemux2 (requires libartsc.so.0) 862 * /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gdkgl/_gdkgl.la -> dev-python/pygtkglext
680 broken /usr/bin/pptout (requires libxml++-0.1.so.11) 863 * /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gtkgl/_gtkgl.la -> dev-python/pygtkglext
681 broken /usr/bin/xml2ps (requires libxml++-0.1.so.11) 864 * /usr/qt/3/lib/libqt-mt.la -> x11-libs/qt
682 done. 865 * Generated new 4_raw.rr and 4_owners.rr
683 (/root/.revdep-rebuild.3_rebuild) 866 * Cleaning list of packages to rebuild
684 867 * Generated new 4_pkgs.rr
685Assigning files to ebuilds... done. 868 * Assigning packages to ebuilds
686 (/root/.revdep-rebuild.4_ebuilds) 869 * Generated new 4_ebuilds.rr
687
688Evaluating package order... done. 870 * Evaluating package order
689 (/root/.revdep-rebuild.5_order) 871 * Generated new 5_order.rr
690
691All prepared. Starting rebuild... 872 * All prepared. Starting rebuild
692emerge --oneshot --nodeps -p =app-cdr/k3b-0.11.14 =app-office/koffice-1.3.2 =app-office/lyx-1.3.4 \ 873emerge --oneshot --pretend dev-python/pygtkglext:0
693 =app-office/passepartout-0.2 =dev-lang/lua-5.0.2 =dev-ruby/fxruby-1.0.29 =media-libs/libao-0.8.5 \ 874media-plugins/gst-plugins-taglib:0.10
694 =media-libs/xine-lib-1_rc5-r3 =media-video/avidemux-2.0.26 =net-libs/loudmouth-0.16 875x11-libs/gtkglext:0
876x11-libs/qt:3
695 877
696These are the packages that I would merge, in order: 878These are the packages that would be merged, in order:
697 879
698Calculating dependencies ...done! 880Calculating dependencies... done!
699[ebuild R ] app-cdr/k3b-0.11.14 881[ebuild R ] media-plugins/gst-plugins-taglib-0.10.17
700[ebuild R ] app-office/koffice-1.3.2 882[ebuild R ] x11-libs/gtkglext-1.2.0
701[ebuild R ] app-office/lyx-1.3.4 883[ebuild R ] x11-libs/qt-3.3.8b-r2
702[ebuild R ] app-office/passepartout-0.2 884[ebuild R ] dev-python/pygtkglext-1.1.0
703[ebuild R ] dev-lang/lua-5.0.2
704[ebuild R ] dev-ruby/fxruby-1.0.29
705[ebuild R ] media-libs/libao-0.8.5
706[ebuild R ] media-libs/xine-lib-1_rc5-r3
707[ebuild R ] media-video/avidemux-2.0.26
708[ebuild R ] net-libs/loudmouth-0.16
709
710Now you can remove -p (or --pretend) from arguments and re-run revdep-rebuild. 885 * Now you can remove -p (or --pretend) from arguments and re-run revdep-rebuild.
711</pre> 886</pre>
712 887
713<p> 888<p>
714If you need to rebuild some packages, you may run <c>revdep-rebuild</c> without 889If you need to rebuild some packages, you may run <c>revdep-rebuild</c> without
715the <c>-p</c> flag and the listed packages will be emerged again. 890the <c>-p</c> flag and the listed packages will be emerged again.
716</p> 891</p>
717 892
718</body> 893</body>
719</section> 894</section>
720<section> 895<section>
721<title>glsa-check</title> 896<title>glsa-check</title>
722<body> 897<body>
723 898
724<p> 899<p>
725<c>glsa-check</c> is mainly a test tool that keeps track of the various GLSAs 900<c>glsa-check</c> is mainly a test tool that keeps track of the various GLSA's
726(Gentoo Linux Security Advisory) and will eventually be integrated into 901(Gentoo Linux Security Advisory) and will eventually be integrated into
727<c>emerge</c> and <c>equery</c>. 902<c>emerge</c> and <c>equery</c>.
728</p> 903</p>
729 904
730</body> 905</body>
731</section> 906</section>
732<section> 907<section>
733<title>eread</title> 908<title>eread</title>
734<body> 909<body>
735 910
736<p> 911<p>
737<c>eread</c> is a simple utility to display elog files produced by 912<c>eread</c> is a simple utility to display elog files produced by
738>=<c>portage-2.1</c>. You can set the saving of elog files by setting a couple 913>=<c>portage-2.1</c>. You can set the saving of elog files by setting a couple
739of variables in <path>/etc/make.conf</path>: 914of variables in <path>/etc/make.conf</path>:
740</p> 915</p>

Legend:
Removed from v.1.33  
changed lines
  Added in v.1.34

  ViewVC Help
Powered by ViewVC 1.1.20