Gentoo Archives: gentoo-doc-cvs

From: "Sven Vermeulen (swift)" <swift@g.o>
To: gentoo-doc-cvs@l.g.o
Subject: [gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en: gentoolkit.xml
Date: Sun, 14 Aug 2011 17:03:11
Message-Id: 20110814170253.08C0020051@flycatcher.gentoo.org
1 swift 11/08/14 17:02:53
2
3 Modified: gentoolkit.xml
4 Log:
5 Bug #269071 - Many updates on gentoolkit.xml documentation, thanks to fuzzyray
6
7 Revision Changes Path
8 1.34 xml/htdocs/doc/en/gentoolkit.xml
9
10 file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/gentoolkit.xml?rev=1.34&view=markup
11 plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/gentoolkit.xml?rev=1.34&content-type=text/plain
12 diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/gentoolkit.xml?r1=1.33&r2=1.34
13
14 Index: gentoolkit.xml
15 ===================================================================
16 RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v
17 retrieving revision 1.33
18 retrieving revision 1.34
19 diff -u -r1.33 -r1.34
20 --- gentoolkit.xml 3 Oct 2010 18:47:51 -0000 1.33
21 +++ gentoolkit.xml 14 Aug 2011 17:02:52 -0000 1.34
22 @@ -1,5 +1,5 @@
23 <?xml version="1.0" encoding="UTF-8"?>
24 -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.33 2010/10/03 18:47:51 nightmorph Exp $ -->
25 +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.34 2011/08/14 17:02:52 swift Exp $ -->
26 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
27
28 <guide>
29 @@ -29,6 +29,9 @@
30 <author title="Editor">
31 <mail link="nightmorph@g.o">Joshua Saddler</mail>
32 </author>
33 +<author title="Editor">
34 + <mail link="douglasjanderson@×××××.com">Douglas Anderson</mail>
35 +</author>
36
37 <abstract>
38 Gentoolkit is a suite of tools to ease the administration of a Gentoo system.
39 @@ -37,8 +40,8 @@
40
41 <!-- Licensed under GFDL -->
42
43 -<version>2</version>
44 -<date>2010-10-03</date>
45 +<version>3</version>
46 +<date>2011-06-24</date>
47
48 <chapter>
49 <title>Introduction</title>
50 @@ -88,7 +91,7 @@
51 <note>
52 Many of the tools in gentoolkit reveal important information about your system
53 or require root privilege. For that reason, some of the programs may only be
54 -executed (or only function properly) if run by a user with root permission.
55 +executed (or only function properly) if run by a user with root privileges.
56 </note>
57
58 </body>
59 @@ -113,305 +116,465 @@
60 <body>
61
62 <p>
63 -<c>equery</c> is a tool that displays a great deal of useful information about
64 -the packages on your system and much more. <c>equery --help</c> gives you the
65 -full set of options.
66 +<c>equery</c> is a tool that displays useful information about the packages on
67 +your system. <c>equery</c> is based on a system of modules.
68 +Every module has a shorthand name. For example, <c>equery l gcc</c> is the same
69 +as <c>equery list gcc</c>. <c>equery --help</c> explains global options
70 +and lists all available modules and their shorthand names.
71 +<c>equery --help module</c> will display the help screen for a specific
72 +module. Lastly, <c>man equery</c> provides a detailed explanation of all
73 +available modules and options, and provides useful examples.
74 </p>
75
76 -<note>
77 -Not all features listed by <c>equery --help</c> have been implemented yet.
78 -Those that have not been, are mentioned clearly. You will also see that
79 -every command has a short option, e.g. <c>b</c> instead of <c>belongs</c>.
80 -</note>
81 +<p>
82 +Below is a list of features that work over the majority of modules.
83 +</p>
84 +
85 +<pre caption="Examples of Acceptable Input">
86 +<comment>(Many modules require a package argument. equery accepts all emerge-like input):</comment>
87 +$ <i>equery --quiet list gcc</i> # <comment>package</comment>
88 +sys-devel/gcc-4.3.2-r3
89 +$ <i>equery --quiet list sys-devel/gcc</i> # <comment>category/package</comment>
90 +sys-devel/gcc-4.3.2-r3
91 +$ <i>equery --quiet list '>=sys-devel/gcc-4'</i> # <comment>atom syntax</comment>
92 +sys-devel/gcc-4.3.2-r3
93 +
94 +<comment>(Like emerge, equery doesn't understand partial package names):</comment>
95 +$ <i>equery check zilla</i>
96 +!!! No package found matching zilla
97 +
98 +<comment>(Unlike emerge, equery can accept shell-like globbing in the category and/or package name):</comment>
99 +$ <i>equery check '*zilla*'</i>
100 + * Checking www-client/mozilla-firefox-3.0.14 ...
101 + 90 out of 90 files passed
102 +$ <i>equery check www-c*/*</i>
103 + * Checking www-client/links-2.2 ...
104 + 30 out of 30 files passed
105 + * Checking www-client/mozilla-firefox-3.0.14 ...
106 + 90 out of 90 files passed
107 +
108 +<comment>(Most equery modules take multiple input):</comment>
109 +$ <i>equery hasuse sse sse2</i>
110 + * Searching for USE flag sse ...
111 +[IP-] [ ] media-libs/flac-1.2.1-r3 (0)
112 +[IP-] [ ] media-libs/speex-1.2_beta3_p2 (0)
113 +
114 + * Searching for USE flag sse2 ...
115 +[IP-] [ ] dev-libs/openssl-0.9.8k (0)
116 +[IP-] [ ] x11-libs/pixman-0.16.0 (0)
117 +
118 +<comment>(A few modules also allow full regular expressions):</comment>
119 +$ <i>equery -q list --portage-tree --full-regex '[kr]?flickr.*'</i>
120 +dev-dotnet/flickrnet-bin-2.2
121 +dev-ruby/flickr-1.0.2-r1
122 +dev-ruby/flickr-1.0.2-r2
123 +dev-ruby/rflickr-20060201
124 +media-gfx/kflickr-0.6
125 +[...]
126 +</pre>
127
128 <note>
129 -Be aware that equery currently changes the format of the output if it is sent
130 -through a pipe. The piped format is intended to be easier to parse by tools, but
131 -you can also turn it off by adding the <c>--no-pipe</c> option. If you write
132 -scripts that employ equery, you should be aware of this.
133 +Globbing support replaced a number of older options in <c>equery</c>.
134 +For example, to act on all packages in a certain set, use <c>'*'</c>.
135 +To act on all packages in a category, use <c>'category-name/*'</c>.
136 </note>
137
138 +<warn>
139 +Don't forget to quote input when using special shell characters
140 +like asterisks or greater than/less than signs.
141 +</warn>
142 +
143 +<p>
144 +The next few sections in this document give a quick introduction to the
145 +different <c>equery</c> modules.
146 +</p>
147 +
148 </body>
149 </section>
150 <section>
151 -<title>Finding the Package That a File Came From</title>
152 +<title>Finding the Package That a File Came From with belongs (b)</title>
153 <body>
154
155 +<pre caption="Finding the Package that Installed a Given File">
156 +$ <i>equery belongs -e /usr/bin/glxgears</i>
157 + * Searching for /usr/bin/glxgears ...
158 + x11-apps/mesa-progs-7.5.1 (/usr/bin/glxgears)
159 +</pre>
160 +
161 <p>
162 -<c>equery</c> also provides the functionality of finding the package that a
163 -file came from, using <c>belongs</c> command (or just <c>b</c>).
164 +<c>belongs</c> can search for files matching a regular expression with the
165 +<c>-f</c> option. The <c>-e</c> option stops searching after it finds a match.
166 +Since no file on your system should be owned by two packages, this is a safe
167 +optimization.
168 </p>
169
170 -<pre caption="Finding the ebuild that installed a given file">
171 -# <i>equery belongs /usr/bin/audacious</i>
172 -[ Searching for file(s) /usr/bin/audacious in *... ]
173 -media-sound/audacious-1.1.2 (/usr/bin/audacious)
174 -</pre>
175 +</body>
176 +</section>
177 +<section>
178 +<title>Viewing ChangeLog Entries with changes (c)</title>
179 +<body>
180
181 <p>
182 -By using the <c>-f</c> option, you may search for packages with files
183 -matching any regular expression. The <c>-e</c> option is useful for
184 -terminating your search immediately when a match is found.
185 +<c>changes</c> lets you view ChangeLog entries for a package version or range
186 +of versions. Imagine after an <c>emerge --sync</c>, you
187 +notice Portage is going to be upgraded and want to check what has changed:
188 </p>
189
190 +<pre caption="Viewing Gentoo ChangeLog Entries">
191 +<comment>(Show the latest installable version's entry):</comment>
192 +$ <i>equery changes portage</i>
193 +*portage-2.1.6.13 (03 May 2009)
194 +
195 + 03 May 2009; Zac Medico &lt;zmedico@g.o&gt; +portage-2.1.6.13.ebuild:
196 + 2.1.6.13 bump. This fixes bug #268398 (document econf automatic die)
197 + and bug #267104 (handle insufficient space interaction with userfetch).
198 + Bug #268228 tracks all bugs fixed since 2.1.6.11.
199 +</pre>
200 +
201 </body>
202 </section>
203 <section>
204 -<title>Verifying Package Integrity</title>
205 +<title>Verifying Package Integrity with check (k)</title>
206 <body>
207
208 <p>
209 Sometimes it is useful to check a package's integrity. <c>equery</c> can
210 -verify md5 sums as well as timestamps to indicate when a package might
211 +verify MD5 sums as well as timestamps to indicate when a package might
212 have been corrupted, replaced, or removed.
213 </p>
214
215 -<pre caption="OK package integrity">
216 -# <i>equery check gentoolkit</i>
217 -[ Checking app-portage/gentoolkit-0.2.0 ]
218 - * 54 out of 54 files good
219 +<pre caption="Checking Package Integrity">
220 +$ <i>equery check gentoolkit</i>
221 + * Checking app-portage/gentoolkit-0.3.0_rc7 ...
222 + 71 out of 71 files passed
223 </pre>
224
225 -<p>
226 -Please note that if you change configuration files after installation,
227 -these may be reported as "not good".
228 -</p>
229 -
230 </body>
231 </section>
232 <section>
233 -<title>List of all packages depending on ...</title>
234 +<title>Listing All Packages Depending on Package X with depends (d)</title>
235 <body>
236
237 <p>
238 -<c>equery</c> is able to list all direct dependencies matching a package.
239 -The function we should use to do this is <c>depends</c> and it's as easy as:
240 +Ever wonder why a certain package has been installed on your system?
241 +<c>equery</c> can tell which packages list it as a dependency with
242 +<c>depends</c>. Include indirect dependencies with the <c>-D</c>
243 +option.
244 </p>
245
246 -<pre caption="Looking for packages depending on pygtk">
247 -# <i>equery depends pygtk</i>
248 -[ Searching for packages depending on pygtk... ]
249 -app-office/dia-0.93
250 -dev-python/gnome-python-2.0.0-r1
251 -gnome-extra/gdesklets-core-0.26.2
252 -media-gfx/gimp-2.0.4
253 -x11-libs/vte-0.11.11-r1
254 +<pre caption="Looking for Packages Depending on pygtk">
255 +$ <i>equery depends pygtk</i>
256 + * Searching for pygtk ...
257 +app-admin/pessulus-2.24.0 (>=dev-python/pygtk-2.6.0)
258 +app-editors/gedit-2.24.3 (python ? >=dev-python/pygtk-2.12)
259 +dev-libs/libgweather-2.24.3 (python ? >=dev-python/pygtk-2)
260 +dev-python/gnome-python-base-2.22.3 (>=dev-python/pygtk-2.10.3)
261 +dev-python/gnome-python-desktop-base-2.24.1 (>=dev-python/pygtk-2.10.3)
262 +[...]
263 </pre>
264
265 </body>
266 </section>
267 <section>
268 -<title>Dependency Graphs</title>
269 +<title>Getting Dependency Graphs with depgraph (g)</title>
270 <body>
271
272 <p>
273 -<c>equery</c> is capable of giving us a dependency graph for a specified
274 -package. The dependency graph gives a listing of all the packages that have
275 -direct and indirect dependencies on the package in question.
276 -</p>
277 -
278 -<pre caption="Dependency Graph for cdrtools">
279 -# <i>equery depgraph cdrtools</i>
280 -Displaying dependencies for app-cdr/cdrtools-2.01_alpha37
281 -`-- app-cdr/cdrtools-2.01_alpha37
282 - `-- sys-libs/glibc-2.3.4.20040808 (virtual/libc)
283 - `-- sys-kernel/linux-headers-2.4.22 (virtual/os-headers)
284 - `-- sys-apps/baselayout-1.10.4
285 - `-- sys-apps/sysvinit-2.85-r1
286 - `-- sys-apps/gawk-3.1.3-r1
287 - `-- sys-apps/util-linux-2.12-r4
288 - `-- sys-apps/sed-4.0.9
289 - `-- sys-libs/ncurses-5.4-r4
290 - `-- sys-apps/pam-login-3.14
291 - `-- sys-libs/pam-0.77-r1
292 - `-- sys-libs/cracklib-2.7-r10
293 - `-- sys-apps/miscfiles-1.3-r1
294 - `-- app-arch/gzip-1.3.5-r1
295 - `-- sys-apps/portage-2.0.50-r10
296 +<c>depgraph</c> is the opposite of <c>depends</c>. You pass it a package, and
297 +it will find the packages <e>it</e> depends on (not that depend on it).
298 +When it finds a dependency, it will recursively search for all of
299 +<e>that</e> package's dependencies. Control how deep the tree gets with
300 +the <c>--depth</c> option.
301 +</p>
302 +
303 +<pre caption="Viewing Dependency Graph for cdrtools">
304 +$ <i>equery depgraph mozilla-firefox</i>
305 + * Searching for mozilla-firefox ...
306 + * dependency graph for www-client/mozilla-firefox-2.0.0.19:
307 +`-- www-client/mozilla-firefox-2.0.0.19
308 + `-- virtual/jre-1.6.0 (virtual/jre) [java]
309 + `-- virtual/jdk-1.6.0 (virtual/jdk-1.6.0*)
310 + `-- dev-java/icedtea6-bin (unable to resolve: package masked or removed)
311 + `-- dev-java/sun-jdk-1.6.0.15
312 + `-- dev-java/java-sdk-docs-1.6.0.10 [doc]
313 + `-- app-arch/unzip-6.0-r1
314 + `-- app-arch/bzip2-1.0.5-r1 [bzip2]
315 + `-- sys-libs/glibc-2.9_p20081201-r2
316 + `-- sys-devel/gettext-0.17 [nls]
317 + `-- virtual/libiconv-0 (virtual/libiconv)
318 +[...]
319 </pre>
320
321 <p>
322 -For example, while glibc is a direct dependency for cdrtools,linux-headers
323 -are an indirect dependency. Note that the output also includes information
324 -about virtual packages. In the example above, <c>cdrtools</c> is actually
325 -written to require virtual/libc, not sys-libs/glibc, but on the given
326 -system in the example sys-libs/glibc provides virtual/libc.
327 +Notice how <c>jre</c> is a direct dependency and <c>jdk</c> is an indirect
328 +dependency if the <c>java</c> USE flag is set.
329 </p>
330
331 </body>
332 </section>
333 <section>
334 -<title>Listing Files Belonging to an Ebuild</title>
335 +<title>Listing Files Installed by a Package with files (f)</title>
336 <body>
337
338 <p>
339 -<c>equery</c> can list the files that belong to an installed ebuild. If I
340 -don't know the files that Gentoolkit has installed on the system, I will
341 -use <c>equery</c> to show them.
342 -</p>
343 -
344 -<pre caption="Listing files">
345 -# <i>equery files gentoolkit</i>
346 -[ Searching for packages matching gentoolkit... ]
347 -app-portage/gentoolkit-0.2.0
348 -* Contents of app-portage/gentoolkit-0.2.0:
349 -/usr
350 -/usr/bin
351 -/usr/bin/equery
352 -/usr/bin/etcat
353 -/usr/bin/euse
354 -/usr/bin/glsa-check
355 -/usr/bin/qpkg
356 -/usr/bin/revdep-rebuild
357 -/usr/lib
358 -/usr/lib/gentoolkit
359 -/usr/lib/gentoolkit/pym
360 -/usr/lib/gentoolkit/pym/gentoolkit
361 -/usr/lib/gentoolkit/pym/gentoolkit/__init__.py
362 -/usr/lib/gentoolkit/pym/gentoolkit/gentoolkit.py
363 -/usr/lib/gentoolkit/pym/gentoolkit/pprinter.py
364 -/usr/lib/gentoolkit/pym/glsa.py
365 -/usr/sbin
366 -/usr/share
367 -/usr/share/doc
368 -/usr/share/doc/gentoolkit-0.2.0_pre10
369 -
370 +<c>equery</c> can list all the files installed by an ebuild with the
371 +<c>files</c> command. Try <c>--tree</c> to get an easy to read directory
372 +layout. Use <c>--filter</c> to only find a certain type of file. For example,
373 +to find where executables were installed, use <c>--filter=cmd</c>, and to
374 +quickly find the configuration file location, try <c>--filter=conf</c>.
375 +</p>
376 +
377 +<pre caption="Listing Installed Files in Tree Format">
378 +$ <i>equery files --tree gentoolkit</i>
379 + * Searching for gentoolkit ...
380 + * Contents of app-portage/gentoolkit-0.3.0_rc7:
381 + /etc
382 + > /eclean
383 + + distfiles.exclude
384 + + packages.exclude
385 + > /env.d
386 + + 99gentoolkit-env
387 + > /revdep-rebuild
388 + + 99revdep-rebuild
389 + /usr
390 + > /bin
391 + + eclean
392 + + eclean-dist -> eclean
393 + + eclean-pkg -> eclean
394 + + epkginfo
395 + + equery
396 + + eread
397 + + euse
398 + + glsa-check
399 + + revdep-rebuild
400 + > /lib
401 + > /python2.6
402 + > /site-packages
403 + > /gentoolkit
404 + + gentoolkit-0.3.0_rc7-py2.6.egg-info
405 + + __init__.py
406 + > /equery
407 + + __init__.py
408 + + belongs.py
409 + + changes.py
410 + + check.py
411 + + depends.py
412 + + depgraph.py
413 + + files.py
414 [...]
415 </pre>
416
417 -<p>
418 -The command <c>files</c> of <c>equery</c> provide some options to modify
419 -the output. You can look them all up in the <c>equery</c> man page.
420 -</p>
421 -
422 </body>
423 </section>
424 <section>
425 -<title>Looking for packages that use a specific USE flag</title>
426 +<title>Looking for Packages that Have a Specific USE Flag with hasuse (h)</title>
427 <body>
428
429 <p>
430 -If you want to find which packages on your system that make use of a specific
431 -USE flag, <c>equery</c> has the function <c>hasuse</c>:
432 +You can use <c>hasuse</c> to find out which packages have a given USE flag.
433 +<c>hasuse</c> won't tell you if the flag is enabled, only if the ebuild lists
434 +it as an option. See the EXAMPLES section of <c>hasuse</c> in the
435 +<c>equery</c> man page for more tip on getting that information.
436 </p>
437
438 -<pre caption="Searching packages which use the firefox USE flag">
439 -# <i>equery hasuse firefox</i>
440 -[ Searching for USE flag firefox in all categories among: ]
441 - * installed packages
442 -[I--] [ ] dev-python/gnome-python-extras-2.14.0-r1 (0)
443 -[I--] [ ] media-video/totem-2.16.4 (0)
444 +<pre caption="Searching For Installed Packages that Use the qt3 or qt4 USE Flags">
445 +$ <i>equery hasuse qt3 qt4</i>
446 + * Searching for USE flag qt3 ...
447 +[IP-] [ ] app-crypt/pinentry-0.7.5 (0)
448 +[IP-] [ ] net-dns/avahi-0.6.24-r2 (0)
449 +[IP-] [ ] net-wireless/wpa_supplicant-0.6.9 (0)
450 +
451 + * Searching for USE flag qt4 ...
452 +[IP-] [ ] net-dns/avahi-0.6.24-r2 (0)
453 +[IP-] [ ] net-wireless/wpa_supplicant-0.6.9 (0)
454 </pre>
455
456 </body>
457 </section>
458 <section>
459 -<title>Listing Packages</title>
460 +<title>Listing Packages with list (l)</title>
461 <body>
462
463 <p>
464 -<c>equery</c> has a power feature to list packages belonging to our system,
465 -portage or even an overlay. Let's try this:
466 +<c>list</c> is a simple, yet powerful module to list packages that are installed,
467 +in the Portage tree or in an overlay.
468 </p>
469
470 -<pre caption="Listing packages with equery">
471 -# <i>equery list gentoolkit</i>
472 -[ Searching for package 'gentoolkit' in all categories among: ]
473 - * installed packages
474 -[I--] [ ] app-portage/gentoolkit-0.2.0 (0)
475 +<pre caption="Listing Installed Packages with list">
476 +$ <i>equery list '*'</i>
477 + * Searching for * ...
478 +[IP-] [ ] app-admin/eselect-1.2.3 (0)
479 +[IP-] [ ] app-admin/eselect-ctags-1.10 (0)
480 +[IP-] [ ] app-admin/eselect-esd-20060719 (0)
481 +[IP-] [ ] app-admin/eselect-fontconfig-1.0 (0)
482 +[IP-] [ ] app-admin/eselect-opengl-1.0.8-r1 (0)
483 +[IP-] [ ] app-admin/eselect-python-20090824 (0)
484 +[IP-] [ ] app-admin/eselect-ruby-20081227 (0)
485 +[IP-] [ ] app-admin/eselect-vi-1.1.5 (0)
486 +[IP-] [ ] app-admin/perl-cleaner-1.05 (0)
487 +[IP-] [ ] app-admin/pessulus-2.24.0 (0)
488 +[IP-] [ ] app-admin/python-updater-0.7 (0)
489 +[IP-] [ ] app-admin/sudo-1.7.2_p1 (0)
490 +[...]
491 </pre>
492
493 <p>
494 -The standard query will search our installed packages for the name given.
495 -If found, the following info will be displayed: the package location between
496 -the first square brackets (I for Installed packages, P for Portage, O for
497 -Overlay), the possible masks between the second (~ by keyword, - by arch or
498 -M hard masked), then the category and complete name and last of all, the slot
499 -in which the package is stored.
500 +The standard query will search installed packages for the given package name.
501 +Passing in '*' displays all packages in the set. In the leftmost field, we
502 +see that all the above packages are <c>I</c>nstalled and from the <c>P</c>ortage
503 +tree. They're not masked (the second field is blank), and they're all installed
504 +in the default slot (0).
505 </p>
506
507 <p>
508 -Another example, this time we are going to use the local options in order
509 -to look for packages in our portage tree and overlay.
510 +This time we are going to use local options to look for packages in the
511 +Portage tree and overlays.
512 </p>
513
514 -<pre caption="Using local options with equery">
515 -# <i>equery list -p -o vim</i>
516 -[ Searching for package 'vim' in all categories among: ]
517 - * installed packages
518 -[I--] [ ] app-editors/vim-6.3-r4 (0)
519 - * Portage tree (/usr/portage)
520 -[-P-] [M~] app-editors/vim-7.0_alpha20050126 (0)
521 -[-P-] [M~] app-editors/vim-7.0_alpha20050201 (0)
522 -[-P-] [ ] app-editors/vim-6.3-r2 (0)
523 -[-P-] [M~] app-editors/vim-7.0_alpha20050122 (0)
524 -[-P-] [M~] app-editors/vim-core-7.0_alpha20050126 (0)
525 -[-P-] [ ] app-editors/vim-core-6.3-r3 (0)
526 -[-P-] [M~] app-editors/vim-core-7.0_alpha20050122 (0)
527 -[-P-] [M~] app-editors/vim-core-7.0_alpha20050201 (0)
528 -[-P-] [ ] app-editors/vim-core-6.3-r4 (0)
529 - * overlay tree (/opt/ebuilds)
530 +<pre caption="Using Local Options with list">
531 +$ <i>equery list -po vim</i>
532 + * Searching for vim ...
533 +[-P-] [ ] app-editors/vim-7.0.235 (0)
534 +[-P-] [ ~] app-editors/vim-7.0.243 (0)
535 +[-P-] [ ] app-editors/vim-7.1.123 (0)
536 +[-P-] [ ~] app-editors/vim-7.1.330 (0)
537 +[-P-] [ ] app-editors/vim-7.2 (0)
538 +[-P-] [ ~] app-editors/vim-7.2.108 (0)
539 +[IP-] [ ] app-editors/vim-7.2.182 (0)
540 +[-P-] [ ~] app-editors/vim-7.2.238 (0)
541 +[-P-] [ ~] app-editors/vim-7.2.264 (0)
542 </pre>
543
544 +<p>
545 +In this example you can see version 7.2.182 is installed and there are no
546 +versions available from an overlay. You can see which versions are keyword
547 +masked by the <c>~</c> in the second field.
548 +</p>
549 +
550 </body>
551 </section>
552 <section>
553 -<title>Finding Package Sizes</title>
554 +<title>Viewing Package Metadata with meta (m)</title>
555 <body>
556
557 <p>
558 -Ever been curious to find out how much space a specific package is occupying?
559 -Since a package could have its files over a number of directories, the usual
560 -<c>du -hc</c> might not give you the correct figure. Not to worry, here comes
561 -<c>equery</c> to the rescue!
562 +Each package in the Portage tree provides at least some metadata about
563 +its maintainer, herd, etc. Read about <uri
564 +link="http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&amp;chap=4">Gentoo
565 +Metadata</uri>. The amount of useful information depends on how much package
566 +maintainers decide to provide. With no options, <c>meta</c> returns some basic
567 +useful information.
568 </p>
569
570 -<pre caption="Package Size">
571 -# <i>equery size openoffice-bin</i>
572 -* app-office/openoffice-bin-1.1.2
573 - Total Files : 2908
574 - Total Size : 223353.31 KiB
575 +<pre caption="Getting Package Metadata with meta">
576 +$ <i>equery meta gnucash</i>
577 + * app-office/gnucash [gentoo]
578 + Herd: gnome-office (gnome-office@g.o)
579 + Maintainer: tove@g.o (Torsten Veller)
580 + Upstream: None specified
581 + Location: /usr/portage/app-office/gnucash
582 + Keywords: 2.2.9-r1:0: alpha amd64 ppc sparc x86
583 + Keywords: 2.2.9-r2:0:
584 + Keywords: 2.3.8:0:
585 + Keywords: 2.3.10:0: ~alpha ~amd64 ~ppc ~sparc ~x86
586 </pre>
587
588 <p>
589 -As you can see, <c>equery</c> prints the total space used in kilobytes and
590 -also lists the total number of files the package has.
591 +When the maintainer provides extra information, it can be very useful:
592 </p>
593
594 +<pre caption="Getting Long Package Descriptions with meta">
595 +$ <i>equery meta --description emacs</i>
596 + * app-editors/emacs
597 + GNU Emacs is an extensible, customizable text editor - and more. At its core
598 + is an interpreter for Emacs Lisp, a dialect of the Lisp programming language
599 + with extensions to support text editing. The features of GNU Emacs include:
600 + * Content-sensitive editing modes, including syntax coloring, for a wide
601 + variety of file types including plain text, source code, and HTML.
602 + * Complete built-in documentation, including a tutorial for new users.
603 + * Support for many languages and their scripts, including all the European
604 + "Latin" scripts, Russian, Greek, Japanese, Chinese, Korean, Thai,
605 + Vietnamese, Lao, Ethiopian, and some Indian scripts.
606 + * Highly customizable, using Emacs Lisp code or a graphical customization
607 + interface.
608 + * A large number of extensions that add other functionality, including a
609 + project planner, mail and news reader, debugger interface, calendar, and
610 + more. Many of these extensions are distributed with GNU Emacs; others are
611 + available separately.
612 +</pre>
613 +
614 </body>
615 </section>
616 <section>
617 -<title>Package-wise list of USE Flags</title>
618 +<title>Finding Package Sizes with size (s)</title>
619 <body>
620
621 <p>
622 -<c>equery</c> can be used to give us information about what USE flags
623 -are being used by a specific package. It also tells us what our current USE
624 -flags are for a package and also what USE flags are available for the package.
625 +Have you ever been curious to find out how much space a specific package is
626 +occupying? Since a package could have its files over a number of directories,
627 +the usual <c>du -hc</c> might not give you the correct figure. Not to worry,
628 +here comes <c>equery</c> to the rescue!
629 </p>
630
631 -<pre caption="Set and Unset USE Flags">
632 -# <i>equery uses wireshark</i>
633 -[ Colour Code : set unset ]
634 -[ Legend : (U) Col 1 - Current USE flags ]
635 -[ : (I) Col 2 - Installed With USE flags ]
636 +<pre caption="Displaying Package Size">
637 +$ <i>equery size openoffice-bin</i>
638 + * app-office/openoffice-bin-3.1.1
639 + Total files : 4624
640 + Total size : 361.38 MiB
641 +</pre>
642
643 - U I [ Found these USE variables in : net-analyzer/wireshark-0.99.4 ]
644 - - - adns : Adds support for the adns DNS client library
645 - + + gtk : Adds support for x11-libs/gtk+ (The GIMP Toolkit)
646 - - - ipv6 : Adds support for IP version 6
647 - - - kerberos : Adds kerberos support
648 - - - portaudio : Adds support for the crossplatform portaudio audio API
649 - - - selinux : !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
650 - - - snmp : Adds support for the Simple Network Management Protocol if available
651 - + + ssl : Adds support for Secure Socket Layer connections
652 - - - threads : Adds threads support for various packages. Usually pthreads
653 +<p>
654 +As you can see, <c>size</c> prints the total space used in human-readable
655 +units and lists the total number of files the package has. To get the
656 +total size in bytes, use <c>--bytes</c>.
657 +</p>
658 +
659 +</body>
660 +</section>
661 +<section>
662 +<title>Listing Per-Package USE Flags with uses (u)</title>
663 +<body>
664 +
665 +<p>
666 +<c>equery</c>'s <c>uses</c> module can provide information about what USE
667 +flags are available for a specific package, and which of those flags is
668 +currently enabled.
669 +</p>
670 +
671 +<pre caption="Showing Set and Unset USE Flags">
672 +$ <i>equery uses gst-plugins-meta</i>
673 + * Searching for gst-plugins-meta ...
674 +[ Legend : U - flag is set in make.conf ]
675 +[ : I - package is installed with flag ]
676 +[ Colors : set, unset ]
677 + * Found these USE flags for media-plugins/gst-plugins-meta-0.10-r2:
678 + U I
679 + + + X : Adds support for X11
680 + - - a52 : Enables support for decoding ATSC A/52 streams used in DVD
681 + + + alsa : Adds support for media-libs/alsa-lib (Advanced Linux Sound
682 + Architecture)
683 + - - dvb : Adds support for DVB (Digital Video Broadcasting)
684 + + + dvd : Adds support for DVDs
685 + + + esd : Adds support for media-sound/esound (Enlightened Sound Daemon)
686 + + + ffmpeg : Enable ffmpeg-based audio/video codec support
687 + + + flac : Adds support for FLAC: Free Lossless Audio Codec
688 + - - mad : Adds support for mad (high-quality mp3 decoder library and cli
689 + frontend)
690 + + + mpeg : Adds libmpeg3 support to various packages
691 + - - mythtv : Support for retrieval from media-tv/mythtv backend
692 + + + ogg : Adds support for the Ogg container format (commonly used by
693 + Vorbis, Theora and flac)
694 + - - oss : Adds support for OSS (Open Sound System)
695 + + + theora : Adds support for the Theora Video Compression Codec
696 + + + vorbis : Adds support for the OggVorbis audio codec
697 + - - xv : Adds in optional support for the Xvideo extension (an X API for
698 + video playback)
699 </pre>
700
701 <p>
702 -I have installed wireshark with only the gtk and ssl flags set, but there are
703 -several other USE flags for wireshark still available. For more information on
704 -USE flags, please refer to the <uri
705 +Here, a number of USE flags are enabled in <c>gstreamer</c>'s plugin
706 +meta-package, but you can see that there are other USE flags available.
707 +For more information on USE flags, please refer to the <uri
708 link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>
709 chapter of the <uri link="/doc/en/handbook/">Gentoo Handbook</uri>.
710 </p>
711 @@ -419,20 +582,40 @@
712 </body>
713 </section>
714 <section>
715 -<title>Where's the ebuild?</title>
716 +<title>Finding the Ebuild Path with which (w)</title>
717 <body>
718
719 <p>
720 -We can also find out which ebuild is being used for a specific package using
721 -<c>equery</c>. This is done by using the <c>equery which</c> command which
722 -displays the full path to the ebuild.
723 +<c>which</c> is a simple script to help you quickly find the file path to an
724 +ebuild. If you pass an unversioned package name, <c>which</c> will return the
725 +path to the newest installable ebuild version, in other words, the ebuild
726 +Portage would use if you typed <c>emerge package</c>. Pass in a versioned
727 +package to get the path to that ebuild.
728 </p>
729
730 -<pre caption="Displaying the ebuild path">
731 -# <i>equery which cdrtools</i>
732 -/usr/portage/app-cdr/cdrtools/cdrtools-2.01_alpha37.ebuild
733 +<pre caption="Displaying the Latest Installable Ebuild Path">
734 +$ <i>equery which gnome</i>
735 +/usr/portage/gnome-base/gnome/gnome-2.26.3.ebuild
736 </pre>
737
738 +<p>
739 +Lastly, if none of the above features of <c>equery</c> have answered your
740 +question, try using <c>which</c> to manually search an ebuild with programs
741 +like <c>cat</c>, <c>less</c> or <c>grep</c>:
742 +</p>
743 +
744 +<pre caption="Other Useful Ways to Use which">
745 +$ <i>grep HOMEPAGE $(equery which gentoolkit)</i>
746 +HOMEPAGE="http://www.gentoo.org/proj/en/portage/tools/index.xml"
747 +</pre>
748 +
749 +<warn>
750 +Be aware that equery currently changes the format of the output if it is sent
751 +through a pipe. The piped format is intended to be easier to parse by tools, but
752 +you can also turn it off by adding the <c>--no-pipe</c> option. If you write
753 +scripts that employ equery, you should be aware of this.
754 +</warn>
755 +
756 </body>
757 </section>
758 </chapter>
759 @@ -643,7 +826,7 @@
760 This tool is Gentoo's Reverse Dependency rebuilder. It will scan your installed
761 ebuilds to find packages that have become broken as a result of an upgrade of a
762 package they depend on. It can emerge those packages for you but it can also
763 -happen that a given package does not work anymore with the currently installed
764 +happen that a given package does not work any more with the currently installed
765 dependencies, in which case you should upgrade the broken package to a more
766 recent version. revdep-rebuild will pass flags to emerge which lets you use the
767 <c>--pretend</c> flag to see what is going to be emerged again before you go any
768 @@ -653,61 +836,53 @@
769 <pre caption="Running revdep-rebuild in pretend mode">
770 # <i>revdep-rebuild -p</i>
771
772 -Checking reverse dependencies...
773 -Packages containing binaries and libraries broken by any package update,
774 -will be recompiled.
775 -
776 -Collecting system binaries and libraries... done.
777 - (/root/.revdep-rebuild.1_files)
778 -
779 -Collecting complete LD_LIBRARY_PATH... done.
780 - (/root/.revdep-rebuild.2_ldpath)
781 -
782 -Checking dynamic linking consistency...
783 - broken /usr/lib/ao/plugins-2/libarts.so (requires libartsc.so.0)
784 - broken /usr/lib/kde3/libkpresenterpart.so (requires libartskde.so.1 libqtmcop.so.1
785 - libsoundserver_idl.so.1 libkmedia2_idl.so.1 libartsflow.so.1 libartsflow_idl.so.1 libmcop.so.1)
786 - broken /usr/lib/ruby/site_ruby/1.8/i686-linux/fox.so (requires libFOX-1.0.so.0)
787 - broken /usr/lib/xine/plugins/1.0.0/xineplug_ao_out_arts.so (requires libartsc.so.0)
788 - broken /usr/lib/perl5/vendor_perl/5.8.0/i686-linux/auto/SDL_perl/SDL_perl.so (requires libSDL_gfx.so.0)
789 - broken /usr/lib/libloudmouth-1.so.0.0.0 (requires libgnutls.so.10)
790 - broken /usr/bin/k3b (requires libartskde.so.1 libqtmcop.so.1 libsoundserver_idl.so.1 libkmedia2_idl.so.1
791 - libartsflow.so.1 libartsflow_idl.so.1 libmcop.so.1)
792 - broken /usr/bin/lua (requires libhistory.so.4)
793 - broken /usr/bin/lyx (requires libAiksaurus-1.0.so.0)
794 - broken /usr/bin/luac (requires libhistory.so.4)
795 - broken /usr/bin/avidemux2 (requires libartsc.so.0)
796 - broken /usr/bin/pptout (requires libxml++-0.1.so.11)
797 - broken /usr/bin/xml2ps (requires libxml++-0.1.so.11)
798 - done.
799 - (/root/.revdep-rebuild.3_rebuild)
800 -
801 -Assigning files to ebuilds... done.
802 - (/root/.revdep-rebuild.4_ebuilds)
803 -
804 -Evaluating package order... done.
805 - (/root/.revdep-rebuild.5_order)
806 -
807 -All prepared. Starting rebuild...
808 -emerge --oneshot --nodeps -p =app-cdr/k3b-0.11.14 =app-office/koffice-1.3.2 =app-office/lyx-1.3.4 \
809 - =app-office/passepartout-0.2 =dev-lang/lua-5.0.2 =dev-ruby/fxruby-1.0.29 =media-libs/libao-0.8.5 \
810 - =media-libs/xine-lib-1_rc5-r3 =media-video/avidemux-2.0.26 =net-libs/loudmouth-0.16
811 -
812 -These are the packages that I would merge, in order:
813 -
814 -Calculating dependencies ...done!
815 -[ebuild R ] app-cdr/k3b-0.11.14
816 -[ebuild R ] app-office/koffice-1.3.2
817 -[ebuild R ] app-office/lyx-1.3.4
818 -[ebuild R ] app-office/passepartout-0.2
819 -[ebuild R ] dev-lang/lua-5.0.2
820 -[ebuild R ] dev-ruby/fxruby-1.0.29
821 -[ebuild R ] media-libs/libao-0.8.5
822 -[ebuild R ] media-libs/xine-lib-1_rc5-r3
823 -[ebuild R ] media-video/avidemux-2.0.26
824 -[ebuild R ] net-libs/loudmouth-0.16
825 + * Configuring search environment for revdep-rebuild
826
827 -Now you can remove -p (or --pretend) from arguments and re-run revdep-rebuild.
828 + * Checking reverse dependencies
829 + * Packages containing binaries and libraries broken by a package update
830 + * will be emerged.
831 +
832 + * Collecting system binaries and libraries
833 + * Generated new 1_files.rr
834 + * Collecting complete LD_LIBRARY_PATH
835 + * Generated new 2_ldpath.rr
836 + * Checking dynamic linking consistency
837 +[ 48% ] * broken /usr/lib/gstreamer-0.10/libgsttaglib.la (requires /usr/lib/libtag.la)
838 +[ 64% ] * broken /usr/lib/libgdkglext-x11-1.0.la (requires /usr/lib/libGLU.la)
839 +[ 67% ] * broken /usr/lib/libgtkglext-x11-1.0.la (requires /usr/lib/libGLU.la)
840 +[ 85% ] * broken /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gdkgl/_gdkgl.la (requires /usr/lib/libGLU.la)
841 + * broken /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gtkgl/_gtkgl.la (requires /usr/lib/libGLU.la)
842 +[ 97% ] * broken /usr/qt/3/lib/libqt-mt.la (requires -lpng)
843 +[ 100% ]
844 + * Generated new 3_broken.rr
845 + * Assigning files to packages
846 + * /usr/lib/gstreamer-0.10/libgsttaglib.la -> media-plugins/gst-plugins-taglib
847 + * /usr/lib/libgdkglext-x11-1.0.la -> x11-libs/gtkglext
848 + * /usr/lib/libgtkglext-x11-1.0.la -> x11-libs/gtkglext
849 + * /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gdkgl/_gdkgl.la -> dev-python/pygtkglext
850 + * /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gtkgl/_gtkgl.la -> dev-python/pygtkglext
851 + * /usr/qt/3/lib/libqt-mt.la -> x11-libs/qt
852 + * Generated new 4_raw.rr and 4_owners.rr
853 + * Cleaning list of packages to rebuild
854 + * Generated new 4_pkgs.rr
855 + * Assigning packages to ebuilds
856 + * Generated new 4_ebuilds.rr
857 + * Evaluating package order
858 + * Generated new 5_order.rr
859 + * All prepared. Starting rebuild
860 +emerge --oneshot --pretend dev-python/pygtkglext:0
861 +media-plugins/gst-plugins-taglib:0.10
862 +x11-libs/gtkglext:0
863 +x11-libs/qt:3
864 +
865 +These are the packages that would be merged, in order:
866 +
867 +Calculating dependencies... done!
868 +[ebuild R ] media-plugins/gst-plugins-taglib-0.10.17
869 +[ebuild R ] x11-libs/gtkglext-1.2.0
870 +[ebuild R ] x11-libs/qt-3.3.8b-r2
871 +[ebuild R ] dev-python/pygtkglext-1.1.0
872 + * Now you can remove -p (or --pretend) from arguments and re-run revdep-rebuild.
873 </pre>
874
875 <p>
876 @@ -722,7 +897,7 @@
877 <body>
878
879 <p>
880 -<c>glsa-check</c> is mainly a test tool that keeps track of the various GLSAs
881 +<c>glsa-check</c> is mainly a test tool that keeps track of the various GLSA's
882 (Gentoo Linux Security Advisory) and will eventually be integrated into
883 <c>emerge</c> and <c>equery</c>.
884 </p>