/[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.39 - (show annotations) (download) (as text)
Tue Sep 17 07:17:09 2013 UTC (9 months, 3 weeks ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.38: +2 -2 lines
File MIME type: application/xml
gentoolkit guide moved to https://wiki.gentoo.org/wiki/Gentoolkit

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.38 2012/12/01 07:32:16 nightmorph Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide disclaimer="obsolete" redirect="https://wiki.gentoo.org/wiki/Gentoolkit">
6 <title>Gentoolkit</title>
7
8 <author title="Author">
9 <mail link="mbutcher@aleph-null.tv">Matt Butcher</mail>
10 </author>
11 <author title="Editor">
12 <!-- zhen@gentoo.org -->John P. Davis
13 </author>
14 <author title="Editor">
15 <mail link="erwin@gentoo.org">Erwin</mail>
16 </author>
17 <author title="Editor">
18 <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
19 </author>
20 <author title="Editor">
21 <mail link="neysx@gentoo.org">Xavier Neys</mail>
22 </author>
23 <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 <author title="Editor">
30 <mail link="nightmorph@gentoo.org">Joshua Saddler</mail>
31 </author>
32 <author title="Editor">
33 <mail link="douglasjanderson@gmail.com">Douglas Anderson</mail>
34 </author>
35
36 <abstract>
37 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 </abstract>
40
41 <!-- Licensed under GFDL -->
42
43 <version>6</version>
44 <date>2012-11-30</date>
45
46 <chapter>
47 <title>Introduction</title>
48 <section>
49 <title>What is Gentoolkit?</title>
50 <body>
51
52 <p>
53 Gentoo is a unique distribution and presents some complexities that simply
54 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 the Gentoo project and are included in the package
58 <c>app-portage/gentoolkit</c>.
59 </p>
60
61 <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 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 </note>
69
70 <p>
71 Gentoolkit contains a whole bunch of useful tools to help manage your packages
72 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 </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 <pre caption="Getting gentoolkit">
88 # <i>emerge gentoolkit</i>
89 </pre>
90
91 <note>
92 Many of the tools in gentoolkit reveal important information about your system
93 or require root privilege. For that reason, some of the programs may only be
94 executed (or only function properly) if run by a user with root privileges.
95 </note>
96
97 </body>
98 </section>
99 <section>
100 <title>Finding Documentation</title>
101 <body>
102
103 <p>
104 Any documentation that a program might have (other than man pages) is stored in
105 <path>/usr/share/doc/gentoolkit-[version]/[program-name]/</path>.
106 </p>
107
108 </body>
109 </section>
110 </chapter>
111
112 <chapter>
113 <title>equery</title>
114 <section>
115 <title>Introduction</title>
116 <body>
117
118 <p>
119 <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 </p>
128
129 <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 <note>
177 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 </note>
181
182 <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
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.
207 Since no file on your system should be owned by two packages, this is a safe
208 optimization.
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
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 </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>
241 Sometimes it is useful to check a package's integrity. <c>equery</c> can
242 verify MD5 sums as well as timestamps to indicate when a package might
243 have 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>
259 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 </p>
264
265 <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 </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
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 mozilla-firefox">
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>
309 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 </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> module. 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 [...]
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>
374 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 </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
400 installed, in 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>
422 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 </p>
428
429 <p>
430 This time we are going to use local options to look for packages in the
431 Portage 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>
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 </body>
455 </section>
456 <section>
457 <title>Viewing Package Metadata with meta (m)</title>
458 <body>
459
460 <p>
461 Each package in the Portage tree provides at least some metadata about
462 its maintainer, herd, etc. Read about <uri
463 link="http://devmanual.gentoo.org/ebuild-writing/misc-files/metadata/index.html">
464 Gentoo Metadata</uri>. The amount of useful information depends on how much
465 package maintainers decide to provide. With no options, <c>meta</c> returns
466 some basic useful 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>
483 When 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>
513 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 </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>
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 </pre>
573
574 <p>
575 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 link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>
579 chapter 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
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 </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>
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 <c>equery</c> currently changes the format of the output if it
614 is sent through a pipe. The piped format is intended to be easier to parse by
615 tools, but you can also turn it off by adding the <c>--no-pipe</c> option. If
616 you write scripts that employ <c>equery</c>, you should be aware of this.
617 </warn>
618
619 </body>
620 </section>
621 </chapter>
622
623 <chapter>
624 <title>euse</title>
625 <section>
626 <title>Introduction</title>
627 <body>
628
629 <p>
630 <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 link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>.
633 Please see <c>euse -h</c> for complete help and all options.
634 </p>
635
636 </body>
637 </section>
638 <section>
639 <title>Viewing, Setting and Unsetting USE Flags</title>
640 <body>
641
642 <p>
643 The <c>euse -a</c> command reads the current active USE flags and displays
644 them.
645 </p>
646
647 <note>
648 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 </note>
653
654 <pre caption="Viewing all active USE flags">
655 # <i>euse -a</i>
656 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 firefox [+ C ]
677 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 ogg [+ CD ]
717 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 </pre>
747
748 <p>
749 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 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 </pre>
767
768 <p>
769 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 (disable a flag).
772 </p>
773
774 <warn>
775 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/portage/make.conf</c>. Although a
777 backup is kept at <path>/etc/portage/make.conf.euse_backup</path>, please be careful
778 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/portage/make.conf was modified, a backup copy has been placed at /etc/portage/make.conf.euse_backup
785
786 <comment>(/etc/portage/make.conf after the command)</comment>
787 USE="alsa acpi apache2 -arts cups cdr crypt cscope -doc fbcon \
788 firefox gd gif gimpprint gnome gpm gstreamer gtkhtml imlib \
789 innodb -java javascript jpeg libg++ libwww mad mbox md5sum \
790 mikmod mmx motif mpeg mpeg4 mysql ncurses nvidia \
791 ogg odbc offensive opengl pam pdflib perl png python \
792 quicktime readline sdl spell sse ssl svga tcltk tiff truetype usb \
793 vanilla X xosd xv xvid x86 zlib 3dfx"
794
795 <comment>(Disabling the USE Flag)</comment>
796 # <i> euse -D 3dfx</i>
797 /etc/portage/make.conf was modified, a backup copy has been placed at /etc/portage/make.conf.euse_backup
798
799 <comment>(/etc/portage/make.conf after the command)</comment>
800 USE="alsa acpi apache2 -arts cups cdr crypt cscope -doc fbcon \
801 firefox gd gif gimpprint gnome gpm gstreamer gtkhtml imlib \
802 innodb -java javascript jpeg libg++ libwww mad mbox md5sum \
803 mikmod mmx motif mpeg mpeg4 mysql ncurses nvidia \
804 ogg odbc offensive opengl pam pdflib perl png python \
805 quicktime readline sdl spell sse ssl svga tcltk tiff truetype usb \
806 vanilla X xosd xv xvid x86 zlib -3dfx"
807 </pre>
808
809 <note>
810 <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 </note>
814
815 </body>
816 </section>
817 </chapter>
818
819 <chapter>
820 <title>Other tools</title>
821 <section>
822 <title>revdep-rebuild</title>
823 <body>
824
825 <p>
826 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 happen that a given package does not work any more with the currently installed
830 dependencies, in which case you should upgrade the broken package to a more
831 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 </p>
835
836 <pre caption="Running revdep-rebuild in pretend mode">
837 # <i>revdep-rebuild -p</i>
838
839 * Configuring search environment for revdep-rebuild
840
841 * 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 </pre>
887
888 <p>
889 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 </p>
892
893 </body>
894 </section>
895 <section>
896 <title>glsa-check</title>
897 <body>
898
899 <p>
900 <c>glsa-check</c> is mainly a test tool that keeps track of the various GLSA's
901 (Gentoo Linux Security Advisory) and will eventually be integrated into
902 <c>emerge</c> and <c>equery</c>.
903 </p>
904
905 </body>
906 </section>
907 <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/portage/make.conf</path>:
915 </p>
916
917 <pre caption="Enabling elog in /etc/portage/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 This is a list of portage log items. Choose a number to view that file or type
938 q to quit.
939
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 <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 </chapter>
994 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20