/[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.10 Revision 1.26
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.10 2004/03/26 12:58:32 cam Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.26 2007/03/05 21:07:33 nightmorph Exp $ -->
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 4
5<guide link="/doc/en/gentoolkit.xml"> 5<guide link="/doc/en/gentoolkit.xml">
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
12<author title="Editor"> 11<author title="Editor">
13 <!-- zhen@gentoo.org -->John P. Davis 12 <!-- zhen@gentoo.org -->John P. Davis
14</author> 13</author>
15
16<author title="Editor"> 14<author title="Editor">
17 <mail link="erwin@gentoo.org">Erwin</mail> 15 <mail link="erwin@gentoo.org">Erwin</mail>
18</author> 16</author>
19 17<author title="Editor">
20<!-- Licensed under GFDL --> 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>
21 32
22<abstract> 33<abstract>
23Gentoolkit is a suite of tools to ease the administration of a Gentoo system. 34Gentoolkit is a suite of tools to ease the administration of a Gentoo system.
24This document covers the basics of some of the tools present in Gentoolkit. 35This document covers the basics of some of the tools present in Gentoolkit.
25</abstract> 36</abstract>
26 37
38<!-- Licensed under GFDL -->
39
27<version>1.2</version> 40<version>1.11</version>
28<date>December 1, 2003</date> 41<date>2007-02-20</date>
29 42
30<chapter> 43<chapter>
31<title>Introduction</title> 44<title>Introduction</title>
32<section> 45<section>
33<title>What is Gentoolkit?</title> 46<title>What is Gentoolkit?</title>
34<body> 47<body>
35 48
36<p> 49<p>
37Gentoo is a unique distribution, and presents some complexities that simply 50Gentoo is a unique distribution and presents some complexities that simply
38don't exist for other distributions. As Gentoo developers and contributors 51don't exist for other distributions. As Gentoo developers and contributors
39discovered some of these complexities, they also wrote tools to help users and 52discovered some of these complexities, they also wrote tools to help users and
40administrators work around them. Many of these tools have been contributed to 53administrators work around them. Many of these tools have been contributed to
41the Gentoo project, and are included in the package 54the Gentoo project and are included in the package
42<c>app-portage/gentoolkit</c>. 55<c>app-portage/gentoolkit</c>.
43</p> 56</p>
44 57
58<note>
59As of now, there are two versions of gentoolkit: <c>app-portage/gentoolkit</c>
60and <c>app-portage/gentoolkit-dev</c>. While the former contains administration
61scripts, the latter contains scripts specific to help development on Gentoo.
62If you are a developer, you can have your scripts included into
63<c>gentoolkit-dev</c> by contacting the Gentoolkit maintainer. This document
64discusses gentoolkit only.
65</note>
66
45<p> 67<p>
46Gentoolkit contains a whole bunch of useful tools to help manage Portage and the 68Gentoolkit contains a whole bunch of useful tools to help manage your packages
47ebuild architecture. Most users -- particularly those who update systems often 69and keep track of what is going on in your system. Most users --&nbsp;particularly
48-- will benefit from having gentoolkit installed. 70those who update systems often&nbsp;-- will benefit from having gentoolkit
71installed.
49</p> 72</p>
50 73
51</body> 74</body>
52</section> 75</section>
53
54<section> 76<section>
55<title>Installation</title> 77<title>Installation</title>
56<body> 78<body>
57 79
58<p> 80<p>
59Just as with any Gentoo package, installation is just a simple emerge. 81Just as with any Gentoo package, installation is just a simple emerge.
60</p> 82</p>
61 83
62<pre> 84<pre caption="Getting gentoolkit">
63# <i>emerge gentoolkit</i> 85# <i>emerge gentoolkit</i>
64</pre> 86</pre>
65 87
66<note> 88<note>
67Many of the tools in gentoolkit reveal important information about your system 89Many of the tools in gentoolkit reveal important information about your system
68or require root permissions. For that reason, some of the programs may only be 90or require root privilege. For that reason, some of the programs may only be
69executed (or only function properly) if run by a user with root permissions. 91executed (or only function properly) if run by a user with root permission.
70</note> 92</note>
71 93
72</body> 94</body>
73</section> 95</section>
74
75<section> 96<section>
76<title>Finding Documentation</title> 97<title>Finding Documentation</title>
77<body> 98<body>
78 99
79<p> 100<p>
80At the time of this writing, not all of the programs in gentoolkit are well 101Any documentation that a program might have (other than man pages) is stored in
81documented. Some have man pages, but not all. Any documentation that a program
82might have (other than man pages) is stored in
83<path>/usr/doc/gentoolkit-[version]/[program-name]/</path>. 102<path>/usr/share/doc/gentoolkit-[version]/[program-name]/</path>.
84</p> 103</p>
85 104
86</body> 105</body>
87</section> 106</section>
88</chapter> 107</chapter>
89 108
90<chapter> 109<chapter>
91<title>Querying Package Data with qpkg</title> 110<title>equery</title>
92<section> 111<section>
93<title>Introduction</title> 112<title>Introduction</title>
94<body> 113<body>
95 114
96<p> 115<p>
97<c>qpkg</c> is a flexible tool for determining information about ebuilds, 116<c>equery</c> is a tool that displays a great deal of useful information about
98whether installed or not. It can provide information about what files belong 117the packages on your system and much more. <c>equery --help</c> gives you the
99to which ebuilds, whether multiple versions of the same package are installed, 118full set of options.
100and what a particular ebuild does.
101</p>
102
103<p>
104Calling <c>qpkg</c> with no arguments prints a list of all ebuilds, with
105asterisks (*) next to the packages that are installed on the system.
106</p> 119</p>
107 120
108<note> 121<note>
109By default, <c>qpkg</c> prints output in color. To turn this off on the command 122Not all features listed by <c>equery --help</c> have been implemented yet.
110line, use the <c>--no-color</c> or <c>-nc</c> flag. 123Those that have not been, are mentioned clearly. You will also see that
124every command has a short option, e.g. <c>b</c> instead of <c>belongs</c>.
111</note> 125</note>
112 126
113</body> 127<note>
114</section> 128Be 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
130you 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.
132</note>
115 133
134</body>
116<section> 135</section>
117<title>Querying Package Information</title>
118<body>
119
120<p>
121One of the most common uses for <c>qpkg</c> is determining what a given package
122is. For instance, while looking through <path>net-misc</path>, I saw a package
123called <path>neon</path>. Having no idea what it was, I ran qpkg.
124</p>
125
126<pre>
127# <i>qpkg -i net-misc/neon</i>
128net-misc/neon-0.15.3-r1
129 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
130net-misc/neon-0.18.5
131 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
132net-misc/neon-0.19.2
133 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
134net-misc/neon-0.19.2-r1
135 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
136net-misc/neon-0.21.1
137 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
138</pre>
139
140<p>
141<c>qpkg</c> read through the ebuild files for the five
142<path>net-misc/neon</path> ebuilds and printed out the information stored in
143DESCRIPTION and HOMEPAGE.
144</p>
145
146</body>
147</section> 136<section>
137<title>Finding the Package That a File Came From</title>
138<body>
148 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>
149<section> 243<section>
150<title>Listing Files Belonging to an Ebuild</title> 244<title>Listing Files Belonging to an Ebuild</title>
151<body> 245<body>
152 246
153<p> 247<p>
154<c>qpkg</c> can also list the files that belong to an installed ebuild. I 248<c>equery</c> can list the files that belong to an installed ebuild. If I
155Know that gentoolkit installed several tools, but I don't know what they 249don't know the files that Gentoolkit has installed on the system, I will
156all are. To find out, I can do a <c>qpkg -l</c>. 250use <c>equery</c> to show them.
157</p> 251</p>
158 252
159<pre> 253<pre caption="Listing files">
160# <i>qpkg -l app-portage/gentoolkit</i> 254# <i>equery files gentoolkit</i>
255[ Searching for packages matching gentoolkit... ]
161app-portage/gentoolkit-0.1.14-r1 * 256app-portage/gentoolkit-0.2.0
162CONTENTS: 257* Contents of app-portage/gentoolkit-0.2.0:
163/usr 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
164/usr/share 275/usr/share
165/usr/share/gentoolkit
166/usr/share/gentoolkit/histogram.awk
167/usr/share/doc 276/usr/share/doc
168/usr/share/doc/gentoolkit-0.1.14-r1 277/usr/share/doc/gentoolkit-0.2.0_pre10
169/usr/share/doc/gentoolkit-0.1.14-r1/gentool 278
170/usr/share/doc/gentoolkit-0.1.14-r1/gentool/ChangeLog.gz 279[...]
171/usr/share/doc/gentoolkit-0.1.14-r1/lintool 280</pre>
172/usr/share/doc/gentoolkit-0.1.14-r1/lintool/checklist-for-ebuilds.gz 281
173/usr/share/doc/gentoolkit-0.1.14-r1/lintool/ChangeLog.gz 282<p>
174/usr/share/doc/gentoolkit-0.1.14-r1/etc-update 283The command <c>files</c> of <c>equery</c> provide some options to modify
175/usr/share/doc/gentoolkit-0.1.14-r1/etc-update/ChangeLog.gz 284the output. You can look them all up in the <c>equery</c> man page.
176/usr/share/man
177/usr/share/man/man1
178/usr/share/man/man1/qpkg.1.gz
179/usr/share/man/man1/lintool.1.gz
180/usr/share/man/man1/etc-update.1.gz
181/usr/bin
182/usr/bin/gentool-bump-revision
183/usr/bin/gentool-total-coverage
184/usr/bin/gentool-author-coverage
185/usr/bin/gentool-package-count
186/usr/bin/qpkg
187/usr/bin/pkg-size
188/usr/bin/lintool
189/usr/sbin
190/usr/sbin/pkg-clean
191/usr/sbin/mkebuild
192/usr/sbin/emerge-webrsync
193/usr/sbin/epm
194/usr/sbin/etc-update
195/etc
196/etc/etc-update.conf
197</pre> 285</p>
198 286
199</body> 287</body>
200</section>
201
202<section> 288</section>
203<title>Finding the Package from Where a File Came</title>
204<body>
205
206<p>
207To find the package that a file came from, use the <c>-f</c> or
208<c>--find-file</c> flag.
209</p>
210
211<pre>
212# <i>qpkg -fnet-www/mozilla * </i>
213</pre>
214
215</body>
216</section> 289<section>
290<title>Looking for packages that use a specific USE flag</title>
291<body>
217 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>
218<section> 307</section>
219<title>Listing Duplicate Packages</title>
220<body>
221
222<p>
223Sometimes multiple versions of the same package may exist. <c>qpkg --dup</c>
224will print a list of duplicate packages. The existence of a duplicate package
225though may not indicate that the older version may be removed. They may fill
226different slots. To look for duplicates in the same slot, use
227<c>qpkg --dups --slot</c>. I just updated KDE from 3.0 to 3.0.2, so I have some
228duplicates in the same slot.
229</p>
230
231<pre>
232# <i>qpkg --dups --slot</i>
233app-portage/gentoolkit
234kde-base/kdeaddons
235kde-base/kdeadmin
236kde-base/kdeartwork
237kde-base/kdebase
238kde-base/kdegames
239kde-base/kdelibs
240kde-base/kdemultimedia
241kde-base/kdenetwork
242kde-base/kdetoys
243kde-base/kdeutils
244media-libs/freetype
245x11-libs/qt
246</pre>
247
248</body>
249</section> 308<section>
309<title>Listing Packages</title>
310<body>
250 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 possibles 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>
251<section> 357</section>
252<title>Verifying Package Integrity</title>
253<body>
254
255<p>
256Sometimes it is useful to check a package's integrity to know that files have
257not been replaced since they were installed. <c>qpkg</c> can verify md5 sums as
258well as install times to indicate whether or not files for the package might
259have been corrupted, replaced, or removed.
260</p>
261
262<p>
263To check both mtimes and md5 sums, use the <c>-c</c> flag.
264</p>
265
266<pre>
267# <i>qpkg gnupg -c -v</i>
268app-crypt/gnupg-1.0.6 *
269/usr/lib/gnupg/rndunix !md5! !mtime!
270/usr/lib/gnupg/rndegd !md5! !mtime!
271/usr/lib/gnupg/tiger !md5! !mtime!
272/usr/bin/gpg !md5! !mtime!
273/usr/bin/gpgv !md5! !mtime!
274/usr/share/gnupg/options.skel !md5! !mtime!
275/usr/share/gnupg/FAQ !md5! !mtime!
276/usr/share/gnupg/faq.html !md5! !mtime!
277/usr/share/locale/da/LC_MESSAGES/gnupg.mo !md5! !mtime!
278/usr/share/locale/de/LC_MESSAGES/gnupg.mo !md5! !mtime!
279/usr/share/locale/eo/LC_MESSAGES/gnupg.mo !md5! !mtime!
280/usr/share/locale/et/LC_MESSAGES/gnupg.mo !md5! !mtime!
281/usr/share/locale/fr/LC_MESSAGES/gnupg.mo !md5! !mtime!
282/usr/share/locale/id/LC_MESSAGES/gnupg.mo !md5! !mtime!
283/usr/share/locale/it/LC_MESSAGES/gnupg.mo !md5! !mtime!
284/usr/share/locale/ja/LC_MESSAGES/gnupg.mo !md5! !mtime!
285/usr/share/locale/nl/LC_MESSAGES/gnupg.mo !md5! !mtime!
286/usr/share/locale/pl/LC_MESSAGES/gnupg.mo !md5! !mtime!
287/usr/share/locale/pt_BR/LC_MESSAGES/gnupg.mo !md5! !mtime!
288/usr/share/locale/sv/LC_MESSAGES/gnupg.mo !md5! !mtime!
289/usr/share/locale/tr/LC_MESSAGES/gnupg.mo !md5! !mtime!
290/usr/share/info/gpgv.info.gz !md5! !mtime!
291/usr/share/man/man1/gpg.1.gz !md5! !mtime!
292/usr/share/man/man1/gpgv.1.gz !md5! !mtime!
29324/92
294
295app-crypt/gnupg-1.0.7 *
2960/101
297</pre>
298
299<p>
300As you can see, I have more than one version of GnuPG installed. <c>qpkg</c>
301reports that many of the files from the older version have been changed since I
302installed it. Those packages were most likely modified when I updated from
303<path>gnupg-1.0.6</path> to <path>gnupg-1.0.7</path>. Note that the last two
304lines indicate that 0 of 101 files from <path>gnupg-1.0.7</path> have been
305changed since I installed. That is good. If any of them had been changed, I
306would be worried.
307</p>
308
309</body>
310</section> 358<section>
359<title>Finding Package Sizes</title>
360<body>
311 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>
312<section> 382</section>
313<title>But Wait... There's More</title> 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
314<body> 419</body>
420</section>
421<section>
422<title>Where's the ebuild?</title>
423<body>
315 424
316<p>
317<c>qpkg</c> can be used for other querying tasks that I will not go over here.
318There is a very complete manpage for <c>qpkg</c>. Consult that for more
319information.
320</p> 425<p>
426We can also find out which ebuild is being used for a specific package using
427<c>equery</c>. This is done my 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>
321 435
322</body> 436</body>
323</section> 437</section>
324</chapter> 438</chapter>
325 439
326<chapter> 440<chapter>
327<title>lintool</title> 441<title>euse</title>
328<section> 442<section>
329<title>Introduction</title> 443<title>Introduction</title>
330<body> 444<body>
331 445
332<p> 446<p>
333 447<c>euse</c> is a tool to see, set and unset USE flags at various places. For
334<c>lintool</c> is a program that checks ebuild scripts for conformance to 448more information on USE flags, please refer to the <uri
335standards and requirements. It is important for ebuild developers to use 449link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>.
336<c>lintool</c> to ensure that they are doing things correctly and not requiring 450Please see <c>euse -h</c> for complete help and all options.
337the core team to do more than they already have to in order to include the
338ebuild in the Gentoo repository.
339</p> 451</p>
340 452
341</body> 453</body>
342</section>
343
344<section> 454</section>
345<title>Use</title> 455<section>
456<title>Viewing, Setting and Unsetting USE Flags</title>
346<body> 457<body>
347 458
348<p>
349Running <c>lintool</c> will produce a nicely formatted list of checks and
350results that it performs.
351</p> 459<p>
460The <c>euse -a</c> command reads the current active USE flags and displays
461them.
462</p>
352 463
464<note>
465There are 5 &quot;columns&quot; that <c>euse</c> now uses to show whether a
466flag is set/unset and where all the flag has been set. The columns are as
467follows -- +/-, set in the Environment, set in make.Conf, set in make.Defaults,
468and set in make.Globals. The output looks like [+ECDG].
469</note>
470
471<pre caption="Viewing all active USE flags">
472# <i>euse -a</i>
473X [+ CD ]
474aalib [+ ]
475acpi [+ C ]
476alsa [+ C ]
477apache2 [+ C ]
478apm [+ D ]
479avi [+ D ]
480berkdb [+ D ]
481bitmap-fonts [+ D ]
482bonobo [+ ]
483cdr [+ C ]
484crypt [+ CD ]
485cscope [+ C ]
486cups [+ CD ]
487curl [+ ]
488emboss [+ D ]
489encode [+ D ]
490esd [+ ]
491fam [+ ]
492fbcon [+ C ]
493firefox [+ C ]
494font-server [+ D ]
495foomaticdb [+ D ]
496fortran [+ D ]
497gd [+ C ]
498gdbm [+ D ]
499gif [+ CD ]
500gimpprint [+ C ]
501gnome [+ CD ]
502gphoto2 [+ ]
503gpm [+ CD ]
504gstreamer [+ C ]
505gtk [+ D ]
506gtkhtml [+ C ]
507guile [+ ]
508imagemagick [+ ]
509imlib [+ CD ]
510innodb [+ ]
511ipv6 [+ D ]
512javascript [+ C ]
513jpeg [+ CD ]
514kde [+ D ]
515ldap [+ ]
516libg++ [+ CD ]
517libwww [+ CD ]
518mad [+ CD ]
519mbox [+ C ]
520md5sum [+ C ]
521mikmod [+ CD ]
522mmx [+ C ]
523motif [+ CD ]
524mp3 [+ ]
525mpeg [+ CD ]
526mpeg4 [+ C ]
527mysql [+ C ]
528ncurses [+ CD ]
529nls [+ D ]
530nvidia [+ C ]
531odbc [+ ]
532offensive [+ ]
533ogg [+ CD ]
534opengl [+ CD ]
535oss [+ D ]
536pam [+ CD ]
537pdflib [+ CD ]
538perl [+ CD ]
539png [+ CD ]
540python [+ CD ]
541qt [+ D ]
542quicktime [+ CD ]
543readline [+ CD ]
544ruby [+ ]
545sdl [+ CD ]
546slang [+ D ]
547spell [+ CD ]
548sse [+ C ]
549ssl [+ CD ]
550svga [+ CD ]
551tcltk [+ C ]
552tcpd [+ D ]
553tiff [+ C ]
554truetype [+ CD ]
555usb [+ C ]
556vanilla [+ C ]
557x86 [+ C ]
558xml [+ ]
559xosd [+ C ]
560xv [+ CD ]
561xvid [+ C ]
562zlib [+ CD ]
353<pre> 563</pre>
354# <i>lintool app-crypt/gnupg/gnupg-1.0.7.ebuild</i>
355app-crypt/gnupg/gnupg-1.0.7.ebuild : Not OK
356 564
357-------------------------------------------------------------------------------
358 Summary for all 1 ebuild(s) checked # errors/warns
359 -------------------------------------------------------------------------------
360 Testing for illegal space characters, weird backslash formatting : 0 / 0
361 Testing for malformed headers : 0 / 1
362 Testing for occurence of deprecated try : 0 / 0
363 Testing for superfluous A=${P}.tar.gz : 0 / 0
364 Testing for empty DEPEND : 0 / 0
365 Testing for empty HOMEPAGE : 0 / 0
366 Testing for empty DESCRIPTION : 0 / 0
367 Testing for presence of env vars : 1 / 1
368 Testing for sane USE flag usage : 0 / 0
369
370 Total number of ebuilds with errors : 1 (100%)
371 Total number of ebuilds with warnings : 1 (100%)
372</pre>
373
374<p>
375The first line summarizes whether the ebuild is okay or not. In the case of
376<c>gnupg-1.0.7.ebuild</c>, it's not. Reading through the list of checks, we can
377see that it got a warning for malformed headers and an error for presence of env
378vars.
379</p> 565<p>
380 566Similarly you can use the <c>euse -a -g</c> command to only view active global
567USE flags. The <c>euse -a -l</c> command does the same for active local USE
568flags.<c>-g</c> &amp; <c>-l</c> are suboptions to <c>euse</c> and need an
569option before them (like <c>-a</c>) to function correctly.
381<p> 570</p>
382Looking at the ebuild, I see that it is missing a couple of required 571
383env vars (LICENSE and RDEPEND). Adding those fixes the error. But there are 572<pre caption="Viewing active local USE flags">
384still two warnings -- one for malformed headers and one for env vars. To help 573# <i>euse -a -l</i>
385me find those, I can run <c>lintool</c> again with <c>--show-details</c> 574bitmap-fonts [+ D ]
575font-server [+ D ]
576fortran [+ D ]
577gimpprint [+ C ]
578md5sum [+ C ]
579mpeg4 [+ C ]
580nvidia [+ C ]
581offensive [+ ]
582truetype [+ CD ]
583</pre>
584
386</p> 585<p>
387 586We can also use <c>euse</c> to set or unset use flags. The commands used for
388<pre> 587this are <c>euse -E flagname</c> (enable a flag) and <c>euse -D flagname</c>
389# <i>lintool --show-details ./gnupg-1.0.7.ebuild</i> 588(disable a flag).
390
391-------------------------------------------------------------------------------
392# Some data cut for brevity....
393
394 Status for ./gnupg-1.0.7.ebuild
395* Testing for malformed headers : passed
396- (W) Has illegal or suspect headers:
397 |Suspect copyright year: # Copyright 1999-2000 Gentoo Technologies, Inc.
398 * Testing for occurence of deprecated try : passed
399 * Testing for superfluous A=${P}.tar.gz : passed
400 * Testing for empty DEPEND : passed
401 * Testing for empty HOMEPAGE : passed
402 * Testing for empty DESCRIPTION : passed
403 * Testing for presence of env vars : passed
404 - (W) Missing SLOT=
405 * Testing for sane USE flag usage : passed
406
407 -------------------------------------------------------------------------------
408 Summary for all 1 ebuild(s) checked # errors/warns
409 -------------------------------------------------------------------------------
410 Testing for illegal space characters, weird backslash formatting : 0 / 0
411 Testing for malformed headers : 0 / 1
412 Testing for occurence of deprecated try : 0 / 0
413 Testing for superfluous A=${P}.tar.gz : 0 / 0
414 Testing for empty DEPEND : 0 / 0
415 Testing for empty HOMEPAGE : 0 / 0
416 Testing for empty DESCRIPTION : 0 / 0
417 Testing for presence of env vars : 0 / 1
418 Testing for sane USE flag usage : 0 / 0
419
420 Total number of ebuilds with errors : 0 (0%)
421 Total number of ebuilds with warnings : 1 (100%)
422</pre>
423
424<p> 589</p>
425Now I can see that the year in the ebuild is probably wrong, and that it is 590
426missing the SLOT variable. Fixing those eliminates all warnings. 591<warn>
592Do not use the <c>euse -E</c> or <c>euse -D</c> commands by themselves (without
593a flag). It will set/unset ALL USE flags in <c>/etc/make.conf</c>. Although a
594backup is kept at <path>/etc/make.conf.euse_backup</path>, please be careful
595while using <c>euse -E</c> or <c>euse -D</c>.
596</warn>
597
598<pre caption="Setting and Unsetting USE flags">
599<comment>(Enabling a USE Flag)</comment>
600# <i> euse -E 3dfx</i>
601/etc/make.conf was modified, a backup copy has been placed at /etc/make.conf.euse_backup
602
603<comment>(/etc/make.conf after the command)</comment>
604USE="alsa acpi apache2 -arts cups cdr crypt cscope -doc fbcon \
605 firefox gd gif gimpprint gnome gpm gstreamer gtkhtml imlib \
606 innodb -java javascript jpeg libg++ libwww mad mbox md5sum \
607 mikmod mmx motif mpeg mpeg4 mysql ncurses nvidia \
608 ogg odbc offensive opengl pam pdflib perl png python \
609 quicktime readline sdl spell sse ssl svga tcltk tiff truetype usb \
610 vanilla X xosd xv xvid x86 zlib 3dfx"
611
612<comment>(Disabling the USE Flag)</comment>
613# <i> euse -D 3dfx</i>
614/etc/make.conf was modified, a backup copy has been placed at /etc/make.conf.euse_backup
615
616<comment>(/etc/make.conf after the command)</comment>
617USE="alsa acpi apache2 -arts cups cdr crypt cscope -doc fbcon \
618 firefox gd gif gimpprint gnome gpm gstreamer gtkhtml imlib \
619 innodb -java javascript jpeg libg++ libwww mad mbox md5sum \
620 mikmod mmx motif mpeg mpeg4 mysql ncurses nvidia \
621 ogg odbc offensive opengl pam pdflib perl png python \
622 quicktime readline sdl spell sse ssl svga tcltk tiff truetype usb \
623 vanilla X xosd xv xvid x86 zlib -3dfx"
427</p> 624</pre>
625
626<note>
627<c>euse</c> does not physically remove the flag from make.conf. It just adds a
628- (minus) before the flag to unset it. You may have to manually clean up your
629make.conf to avoid unwanted variables.
630</note>
428 631
429</body> 632</body>
430</section> 633</section>
431</chapter> 634</chapter>
432 635
433<chapter> 636<chapter>
434<title>epm</title> 637<title>Other tools</title>
435<section>
436<title>Introduction</title>
437<body>
438
439<p>
440<c>epm</c> is a package managing tool that clones Red Hat rpm commands. As it
441stands now, it does not offer all of the features of rpm, but it offers some of
442the more powerful rpm query options.
443</p>
444
445<p>
446It also handles removing packages, which is not covered here. Use <c>epm
447--help</c> to learn more about deleting packages with <c>epm</c>.
448</p>
449
450</body>
451</section> 638<section>
639<title>revdep-rebuild</title>
640<body>
641
642<p>
643This 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
645package 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
647dependencies, 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
649<c>--pretend</c> flag to see what is going to be emerged again before you go any
650further.
651</p>
652
653<pre caption="Running revdep-rebuild in pretend mode">
654# <i>revdep-rebuild -p</i>
655
656Checking reverse dependencies...
657Packages containing binaries and libraries broken by any package update,
658will be recompiled.
659
660Collecting system binaries and libraries... done.
661 (/root/.revdep-rebuild.1_files)
662
663Collecting complete LD_LIBRARY_PATH... done.
664 (/root/.revdep-rebuild.2_ldpath)
665
666Checking dynamic linking consistency...
667 broken /usr/lib/ao/plugins-2/libarts.so (requires libartsc.so.0)
668 broken /usr/lib/kde3/libkpresenterpart.so (requires libartskde.so.1 libqtmcop.so.1
669 libsoundserver_idl.so.1 libkmedia2_idl.so.1 libartsflow.so.1 libartsflow_idl.so.1 libmcop.so.1)
670 broken /usr/lib/ruby/site_ruby/1.8/i686-linux/fox.so (requires libFOX-1.0.so.0)
671 broken /usr/lib/xine/plugins/1.0.0/xineplug_ao_out_arts.so (requires libartsc.so.0)
672 broken /usr/lib/perl5/vendor_perl/5.8.0/i686-linux/auto/SDL_perl/SDL_perl.so (requires libSDL_gfx.so.0)
673 broken /usr/lib/libloudmouth-1.so.0.0.0 (requires libgnutls.so.10)
674 broken /usr/bin/k3b (requires libartskde.so.1 libqtmcop.so.1 libsoundserver_idl.so.1 libkmedia2_idl.so.1
675 libartsflow.so.1 libartsflow_idl.so.1 libmcop.so.1)
676 broken /usr/bin/lua (requires libhistory.so.4)
677 broken /usr/bin/lyx (requires libAiksaurus-1.0.so.0)
678 broken /usr/bin/luac (requires libhistory.so.4)
679 broken /usr/bin/avidemux2 (requires libartsc.so.0)
680 broken /usr/bin/pptout (requires libxml++-0.1.so.11)
681 broken /usr/bin/xml2ps (requires libxml++-0.1.so.11)
682 done.
683 (/root/.revdep-rebuild.3_rebuild)
684
685Assigning files to ebuilds... done.
686 (/root/.revdep-rebuild.4_ebuilds)
687
688Evaluating package order... done.
689 (/root/.revdep-rebuild.5_order)
690
691All 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 \
693 =app-office/passepartout-0.2 =dev-lang/lua-5.0.2 =dev-ruby/fxruby-1.0.29 =media-libs/libao-0.8.5 \
694 =media-libs/xine-lib-1_rc5-r3 =media-video/avidemux-2.0.26 =net-libs/loudmouth-0.16
695
696These are the packages that I would merge, in order:
697
698Calculating dependencies ...done!
699[ebuild R ] app-cdr/k3b-0.11.14
700[ebuild R ] app-office/koffice-1.3.2
701[ebuild R ] app-office/lyx-1.3.4
702[ebuild R ] app-office/passepartout-0.2
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.
711</pre>
712
713<p>
714If 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.
716</p>
717
718</body>
452<section> 719</section>
453 720
454<title>Querying Packages with epm</title> 721<section>
722<title>glsa-check</title>
455<body> 723<body>
456 724
457<p>
458<c>epm</c> functions with essentially the same command line functions as Red
459Hat's rpm. <c>epm -qa</c> lists all packages installed. <c>epm -ql</c> lists all
460the files from a specific ebuild.
461</p> 725<p>
462 726<c>glsa-check</c> is mainly a test tool that keeps track of the various GLSA's
463<pre> 727(Gentoo Linux Security Advisory) and will eventually be integrated into
464# <i>epm -ql ethereal</i> 728<c>emerge</c> and <c>equery</c>. For more information, please visit the <uri
465/usr/lib/ethereal/plugins/0.8.20/gryphon.so 729link="/proj/en/portage/glsa-integration.xml">Portage GLSA Integration
466/usr/lib/ethereal/plugins/0.8.20/gryphon.la 730Page</uri>.
467/usr/lib/ethereal/plugins/0.8.20/gryphon.a
468/usr/lib/ethereal/plugins/0.8.20/mgcp.so
469/usr/lib/ethereal/plugins/0.8.20/mgcp.la
470/usr/lib/ethereal/plugins/0.8.20/mgcp.a
471/usr/lib/ethereal/plugins/0.8.20/cosnaming.so
472/usr/lib/ethereal/plugins/0.8.20/cosnaming.la
473/usr/lib/ethereal/plugins/0.8.20/cosnaming.a
474/usr/lib/ethereal/plugins/0.8.20/coseventcomm.so
475/usr/lib/ethereal/plugins/0.8.20/coseventcomm.la
476/usr/lib/ethereal/plugins/0.8.20/coseventcomm.a
477/usr/bin/ethereal
478/usr/bin/editcap
479/usr/bin/mergecap
480/usr/bin/tethereal
481/usr/bin/text2pcap
482/usr/bin/idl2eth
483/usr/share/man/man1/idl2eth.1.gz
484/usr/share/man/man1/tethereal.1.gz
485/usr/share/man/man1/text2pcap.1.gz
486/usr/share/man/man1/editcap.1.gz
487/usr/share/man/man1/ethereal.1.gz
488/usr/share/man/man1/mergecap.1.gz
489/usr/share/doc/ethereal-0.8.20/AUTHORS.gz
490/usr/share/doc/ethereal-0.8.20/COPYING.gz
491/usr/share/doc/ethereal-0.8.20/NEWS.gz
492/usr/share/doc/ethereal-0.8.20/ChangeLog.gz
493/usr/share/doc/ethereal-0.8.20/README.gz
494/usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz
495/usr/share/doc/ethereal-0.8.20/TODO.gz
496/usr/share/doc/ethereal-0.8.20/README.aix.gz
497/usr/share/doc/ethereal-0.8.20/README.bsd.gz
498/usr/share/doc/ethereal-0.8.20/README.hpux.gz
499/usr/share/doc/ethereal-0.8.20/README.irix.gz
500/usr/share/doc/ethereal-0.8.20/README.linux.gz
501/usr/share/doc/ethereal-0.8.20/README.tru64.gz
502/usr/share/doc/ethereal-0.8.20/README.win32.gz
503/usr/share/doc/ethereal-0.8.20/README.vmware.gz
504/etc/ethereal/manuf
505</pre>
506
507<p> 731</p>
508<c>epm</c> offers a few advanced query options that are not present in
509<c>qpkg</c> at the time of this writing. For instance, it can query for just
510configuration files or just documentation files.
511</p>
512
513<pre>
514# <i>epm -qc ethereal</i>
515/etc/ethereal/manuf
516
517# <i>epm -qd ethereal</i>
518/usr/share/man/man1/idl2eth.1.gz
519/usr/share/man/man1/tethereal.1.gz
520/usr/share/man/man1/text2pcap.1.gz
521/usr/share/man/man1/editcap.1.gz
522/usr/share/man/man1/ethereal.1.gz
523/usr/share/man/man1/mergecap.1.gz
524/usr/share/doc/ethereal-0.8.20/AUTHORS.gz
525/usr/share/doc/ethereal-0.8.20/COPYING.gz
526/usr/share/doc/ethereal-0.8.20/NEWS.gz
527/usr/share/doc/ethereal-0.8.20/ChangeLog.gz
528/usr/share/doc/ethereal-0.8.20/README.gz
529/usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz
530/usr/share/doc/ethereal-0.8.20/TODO.gz
531/usr/share/doc/ethereal-0.8.20/README.aix.gz
532/usr/share/doc/ethereal-0.8.20/README.bsd.gz
533/usr/share/doc/ethereal-0.8.20/README.hpux.gz
534/usr/share/doc/ethereal-0.8.20/README.irix.gz
535/usr/share/doc/ethereal-0.8.20/README.linux.gz
536/usr/share/doc/ethereal-0.8.20/README.tru64.gz
537/usr/share/doc/ethereal-0.8.20/README.win32.gz
538/usr/share/doc/ethereal-0.8.20/README.vmware.gz
539</pre>
540
541<note>
542<c>epm --help</c> lists the options that epm <e>will eventually</e> support.
543Note, however, that options prefixed with asterisks (*) are not yet implemented.
544</note>
545 732
546</body> 733</body>
547</section> 734</section>
548</chapter> 735</chapter>
549 736
550<chapter>
551<title>Others</title>
552<section>
553<title>etc-update</title>
554<body>
555<!--
556- Feel free to add more to this. It probably deserves its own chapter, but I don't
557- use it, so I can't really write much about it.
558-->
559
560<p>
561<c>etc-update</c> provides a convenient alternative to updating configuration
562files by hand. After running an emerge that changes configuration files, you
563can run etc-update to step you through the process of updating all impacted
564configuration files.
565</p>
566
567<p>
568It is driven by a menu-based interface and includes the ability to view and
569merge in config files before deciding what to do.
570</p>
571
572</body>
573</section>
574
575<section>
576<title>gentool</title>
577<body>
578
579<p>
580gentool is a collective name for several small scripts that analyze ebuild
581statistics.
582For instance, gentool-total-coverage prints a list of email addresses and the
583number of ebuilds each has in the portage tree.
584</p>
585
586</body>
587</section>
588
589<section>
590<title>pkg-size</title>
591<body>
592
593<p>
594<c>pkg-size</c> prints the size of the installed files in a given package.
595</p>
596
597<pre>
598# <i>pkg-size nmap</i>
599net-analyzer/nmap-2.54_beta24-r1 897024 (876KB)
600</pre>
601
602</body>
603</section>
604
605<section>
606<title>mkebuild</title>
607<body>
608
609<p>
610<c>mkebuild</c> simplifies the process of creating a new ebuild by automating as
611much of the process as possible. Running <c>mkebuild [filename]</c> will create
612an ebuild for that file. the file should be an archive of some kind. As it
613works, it will provide feedback about changes you may need to make.
614</p>
615
616</body>
617</section>
618
619<section>
620<title>emerge-webrsync</title>
621<body>
622<!-- Can't find any documentation on this anywhere... not even a comment in the
623code. -->
624
625<p>
626Downloads the daily snapshot over HTTP with wget, and (optionally) syncs with
627portage.
628</p>
629
630</body>
631</section>
632</chapter>
633</guide> 737</guide>

Legend:
Removed from v.1.10  
changed lines
  Added in v.1.26

  ViewVC Help
Powered by ViewVC 1.1.20