/[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.1 Revision 1.29
1<?xml version="1.0" encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.29 2007/06/26 04:02:53 nightmorph Exp $ -->
1<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
2<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
3 4
4<guide> 5<guide link="/doc/en/gentoolkit.xml">
5<title>Gentoolkit</title> 6<title>Gentoolkit</title>
6<author title="Author"><mail link="mbutcher@aleph-null.tv"> 7
7Matt Butcher</mail> 8<author title="Author">
9 <mail link="mbutcher@aleph-null.tv">Matt Butcher</mail>
8</author> 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>
9 32
10<author title="Editor"><mail link="zhen@gentoo.org">John P. Davis</mail></author> 33<abstract>
34Gentoolkit is a suite of tools to ease the administration of a Gentoo system.
35This document covers the basics of some of the tools present in Gentoolkit.
36</abstract>
37
11<!-- Licensed under GFDL --> 38<!-- Licensed under GFDL -->
12 39
13<abstract>
14 Gentoolkit is a suite of tools to ease the administration of a Gentoo system.
15 This document covers the basics of
16 some of the tools present in Gentoolkit.
17</abstract>
18
19<version>1.1</version> 40<version>1.11</version>
20<date>25 September 2002</date> 41<date>2007-02-20</date>
21 42
22<chapter> 43<chapter>
23 <title>Introduction</title> 44<title>Introduction</title>
24 <section> 45<section>
25 <title>What is Gentoolkit?</title> 46<title>What is Gentoolkit?</title>
26 <body> 47<body>
48
49<p>
27 <p>Gentoo is a unique distribution, and presents some complexities that 50Gentoo is a unique distribution and presents some complexities that simply
28 simply don't exist for other distributions. As Gentoo developers 51don't exist for other distributions. As Gentoo developers and contributors
29 and contributors discovered some of these complexities, they also 52discovered some of these complexities, they also wrote tools to help users and
30 wrote tools to help users and administrators work around them. 53administrators work around them. Many of these tools have been contributed to
31 Many of these tools have been contributed to the Gentoo project, 54the Gentoo project and are included in the package
32 and are included in the package <path>app-admin/gentoolkit</path>. 55<c>app-portage/gentoolkit</c>.
33 </p> 56</p>
34 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
67<p>
35 <p>Gentoolkit contains a whole bunch of useful tools to help manage 68Gentoolkit contains a whole bunch of useful tools to help manage your packages
36 Portage and the ebuild architecture. Most users -- particularly 69and keep track of what is going on in your system. Most users --&nbsp;particularly
37 those who update systems often -- will benefit from having 70those who update systems often&nbsp;-- will benefit from having gentoolkit
38 gentoolkit installed.</p> 71installed.
72</p>
73
39 </body> 74</body>
40 </section> 75</section>
41 <section> 76<section>
42 <title>Installation</title> 77<title>Installation</title>
43 <body> 78<body>
79
80<p>
44 <p>Just as with any Gentoo package, installation is just a simple 81Just as with any Gentoo package, installation is just a simple emerge.
45 emerge. 82</p>
46 </p>
47 83
48 <pre> 84<pre caption="Getting gentoolkit">
49<i>emerge gentoolkit </i> 85# <i>emerge gentoolkit</i>
50 </pre> 86</pre>
87
88<note>
51 <note>Many of the tools in gentoolkit reveal important information 89Many of the tools in gentoolkit reveal important information about your system
52 about your system or require root permissions. For that reason, 90or require root privilege. For that reason, some of the programs may only be
53 some of the programs may only be executed (or only function 91executed (or only function properly) if run by a user with root permission.
54 properly) if run by a user with root permissions.</note> 92</note>
93
55 </body> 94</body>
56 </section> 95</section>
57 <section> 96<section>
58 <title>Finding Documentation</title> 97<title>Finding Documentation</title>
59 <body> 98<body>
60 99
61 <p> 100<p>
62 At the time of this writing, not all of the programs in gentoolkit
63 are well documented. Some have man pages, but not all. Any documentation
64 that a program might have (other than man pages) is stored in 101Any documentation that a program might have (other than man pages) is stored in
65 <path>/usr/doc/gentoolkit-[version]/[program-name]/</path>. 102<path>/usr/share/doc/gentoolkit-[version]/[program-name]/</path>.
66 </p> 103</p>
104
67 </body> 105</body>
68 </section> 106</section>
69</chapter> 107</chapter>
108
70<chapter> 109<chapter>
71 <title>Querying Package Data with qpkg</title> 110<title>equery</title>
72 <section> 111<section>
73
74 <title>Introduction</title> 112<title>Introduction</title>
75 <body> 113<body>
76 <p><c>qpkg</c> is flexible tool for determining information about ebuilds,
77 whether installed or not. It can provide information about what files belong
78 to which ebuilds, whether multiple versions of the same package are installed,
79 and what a particular ebuild does.
80 </p>
81 <p>Calling <c>qpkg</c> with no arguments prints a list of all ebuilds, with asterisks
82 (*) next to the packages that are installed on the system.
83 </p>
84 <note>By default, <c>qpkg</c> prints output in color. To turn this off on the command
85 line, use the <c>--no-color</c> or <c>-nc</c> flag.</note>
86 114
115<p>
116<c>equery</c> is a tool that displays a great deal of useful information about
117the packages on your system and much more. <c>equery --help</c> gives you the
118full set of options.
119</p>
120
121<note>
122Not all features listed by <c>equery --help</c> have been implemented yet.
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>.
125</note>
126
127<note>
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>
133
87 </body> 134</body>
88 </section> 135</section>
89 <section> 136<section>
90 <title>Querying Package Information</title> 137<title>Finding the Package That a File Came From</title>
91 <body> 138<body>
92 <p>One of the most common uses for <c>qpkg</c> is determining what a given package
93 is. For instance, while looking through <path>net-misc</path>, I saw a package
94 called <path>neon</path>. Having no idea what it was, I ran qpkg.
95 </p>
96 139
97 <pre> 140<p>
98hebron root # <i>qpkg -i net-misc/neon 141<c>equery</c> also provides the functionality of finding the package that a
99net-misc/neon-0.15.3-r1 142file came from, using <c>belongs</c> command (or just <c>b</c>).
100 HTTP and WebDAV client library [ http://www.webdav.org/neon ] 143</p>
101net-misc/neon-0.18.5 144
102 HTTP and WebDAV client library [ http://www.webdav.org/neon ] 145<pre caption="Finding the ebuild that installed a given file">
103net-misc/neon-0.19.2 146# <i>equery belongs /usr/bin/audacious</i>
104 HTTP and WebDAV client library [ http://www.webdav.org/neon ] 147[ Searching for file(s) /usr/bin/audacious in *... ]
105net-misc/neon-0.19.2-r1 148media-sound/audacious-1.1.2 (/usr/bin/audacious)
106 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
107net-misc/neon-0.21.1
108 HTTP and WebDAV client library [ http://www.webdav.org/neon ] </i>
109 </pre> 149</pre>
110 <p> 150
111 <c>qpkg</c> read through the ebuild files for the five <path>net-misc/neon</path> 151<p>
112 ebuilds and printed out the information stored in DESCRIPTION and HOMEPAGE. 152By using the <c>-f</c> option, you may search for packages with files
113 </p> 153matching any regular expression. The <c>-e</c> option is useful for
154terminating your search immediately when a match is found.
155</p>
156
114 </body> 157</body>
115
116 </section> 158</section>
117 <section> 159<section>
160<title>Verifying Package Integrity</title>
161<body>
162
163<p>
164Sometimes it is useful to check a package's integrity. <c>equery</c> can
165verify md5 sums as well as timestamps to indicate when a package might
166have been corrupted, replaced, or removed.
167</p>
168
169<pre caption="OK package integrity">
170# <i>equery check gentoolkit</i>
171[ Checking app-portage/gentoolkit-0.2.0 ]
172 * 54 out of 54 files good
173</pre>
174
175<p>
176Please note that if you change configuration files after installation,
177these may be reported as "not good".
178</p>
179
180</body>
181</section>
182<section>
183<title>List of all packages depending on ...</title>
184<body>
185
186<p>
187<c>equery</c> is able to list all direct dependencies matching a package.
188The function we should use to do this is <c>depends</c> and it's as easy as:
189</p>
190
191<pre caption="Looking for packages depending on pygtk">
192# <i>equery depends pygtk</i>
193[ Searching for packages depending on pygtk... ]
194app-office/dia-0.93
195dev-python/gnome-python-2.0.0-r1
196gnome-extra/gdesklets-core-0.26.2
197media-gfx/gimp-2.0.4
198x11-libs/vte-0.11.11-r1
199</pre>
200
201</body>
202</section>
203<section>
204<title>Dependency Graphs</title>
205<body>
206
207<p>
208<c>equery</c> is capable of giving us a dependency graph for a specified
209package. The dependency graph gives a listing of all the packages that have
210direct and indirect dependencies on the package in question.
211</p>
212
213<pre caption="Dependency Graph for cdrtools">
214# <i>equery depgraph cdrtools</i>
215Displaying dependencies for app-cdr/cdrtools-2.01_alpha37
216`-- app-cdr/cdrtools-2.01_alpha37
217 `-- sys-libs/glibc-2.3.4.20040808 (virtual/libc)
218 `-- sys-kernel/linux-headers-2.4.22 (virtual/os-headers)
219 `-- sys-apps/baselayout-1.10.4
220 `-- sys-apps/sysvinit-2.85-r1
221 `-- sys-apps/gawk-3.1.3-r1
222 `-- sys-apps/util-linux-2.12-r4
223 `-- sys-apps/sed-4.0.9
224 `-- sys-libs/ncurses-5.4-r4
225 `-- sys-apps/pam-login-3.14
226 `-- sys-libs/pam-0.77-r1
227 `-- sys-libs/cracklib-2.7-r10
228 `-- sys-apps/miscfiles-1.3-r1
229 `-- app-arch/gzip-1.3.5-r1
230 `-- sys-apps/portage-2.0.50-r10
231</pre>
232
233<p>
234For example, while glibc is a direct dependency for cdrtools,linux-headers
235are an indirect dependency. Note that the output also includes information
236about virtual packages. In the example above, <c>cdrtools</c> is actually
237written to require virtual/libc, not sys-libs/glibc, but on the given
238system in the example sys-libs/glibc provides virtual/libc.
239</p>
240
241</body>
242</section>
243<section>
118 <title>Listing Files Belonging to an Ebuild</title> 244<title>Listing Files Belonging to an Ebuild</title>
119 <body> 245<body>
120 <p> 246
247<p>
121 <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
122 Know 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
123 all are. To find out, I can do a <c>qpkg -l</c> 250use <c>equery</c> to show them.
251</p>
124 252
125 </p> 253<pre caption="Listing files">
126 <pre> 254# <i>equery files gentoolkit</i>
127hebron portage # <i>qpkg -l app-admin/gentoolkit 255[ Searching for packages matching gentoolkit... ]
128app-admin/gentoolkit-0.1.14-r1 * 256app-portage/gentoolkit-0.2.0
129CONTENTS: 257* Contents of app-portage/gentoolkit-0.2.0:
130/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
131/usr/share 275/usr/share
132/usr/share/gentoolkit
133/usr/share/gentoolkit/histogram.awk
134/usr/share/doc 276/usr/share/doc
135/usr/share/doc/gentoolkit-0.1.14-r1 277/usr/share/doc/gentoolkit-0.2.0_pre10
136/usr/share/doc/gentoolkit-0.1.14-r1/gentool 278
137/usr/share/doc/gentoolkit-0.1.14-r1/gentool/ChangeLog.gz 279[...]
138/usr/share/doc/gentoolkit-0.1.14-r1/lintool
139/usr/share/doc/gentoolkit-0.1.14-r1/lintool/checklist-for-ebuilds.gz
140/usr/share/doc/gentoolkit-0.1.14-r1/lintool/ChangeLog.gz
141/usr/share/doc/gentoolkit-0.1.14-r1/etc-update
142/usr/share/doc/gentoolkit-0.1.14-r1/etc-update/ChangeLog.gz
143/usr/share/man
144/usr/share/man/man1
145/usr/share/man/man1/qpkg.1.gz
146/usr/share/man/man1/lintool.1.gz
147/usr/share/man/man1/etc-update.1.gz
148/usr/bin
149/usr/bin/gentool-bump-revision
150/usr/bin/gentool-total-coverage
151/usr/bin/gentool-author-coverage
152/usr/bin/gentool-package-count
153/usr/bin/qpkg
154/usr/bin/pkg-size
155/usr/bin/lintool
156/usr/sbin
157/usr/sbin/pkg-clean
158/usr/sbin/mkebuild
159/usr/sbin/emerge-webrsync
160/usr/sbin/epm
161/usr/sbin/etc-update
162/etc
163/etc/etc-update.conf </i>
164 </pre> 280</pre>
281
282<p>
283The command <c>files</c> of <c>equery</c> provide some options to modify
284the output. You can look them all up in the <c>equery</c> man page.
285</p>
286
165 </body> 287</body>
166 </section> 288</section>
167 <section> 289<section>
168 <title>Finding the Package from Where a File Came</title> 290<title>Looking for packages that use a specific USE flag</title>
169 <body> 291<body>
170 292
171 <p> 293<p>
172 To find the package that a file came from, use the <c>-f</c> 294If you want to find which packages on your system that make use of a specific
173 or <c>--find-file</c> flag. 295USE flag, <c>equery</c> has the function <c>hasuse</c>:
174 </p> 296</p>
175 <pre> 297
176 hebron portage # <i>qpkg -f net-www/mozilla * </i> 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)
177 </pre> 304</pre>
178 305
179 </body> 306</body>
180 </section> 307</section>
181 <section> 308<section>
182 <title>Listing Duplicate Packages</title> 309<title>Listing Packages</title>
183 <body> 310<body>
184 <p>
185 Sometimes multiple versions of the same package may exist. <c>qpkg --dup</c>
186 311
187 will print a list of duplicate packages. The existence of a duplicate package 312<p>
188 though may not indicate that the older version may be removed. They may fill 313<c>equery</c> has a power feature to list packages belonging to our system,
189 different slots. To look for duplicates in the same slot, use 314portage or even an overlay. Let's try this:
190 <c>qpkg --dups --slot</c>. I just updated KDE from 3.0 to 3.0.2, so I have some 315</p>
191 duplicates in the same slot. 316
192 </p> 317<pre caption="Listing packages with equery">
193 <pre> 318# <i>equery list gentoolkit</i>
194hebron portage # <i>qpkg --dups --slot 319[ Searching for package 'gentoolkit' in all categories among: ]
195app-admin/gentoolkit 320 * installed packages
196kde-base/kdeaddons 321[I--] [ ] app-portage/gentoolkit-0.2.0 (0)
197kde-base/kdeadmin
198kde-base/kdeartwork
199kde-base/kdebase
200kde-base/kdegames
201kde-base/kdelibs
202kde-base/kdemultimedia
203kde-base/kdenetwork
204kde-base/kdetoys
205kde-base/kdeutils
206media-libs/freetype
207x11-libs/qt </i>
208 </pre> 322</pre>
323
324<p>
325The standard query will search our installed packages for the name given.
326If found, the following info will be displayed: the package location between
327the first square brackets (I for Installed packages, P for Portage, O for
328Overlay), the possible masks between the second (~ by keyword, - by arch or
329M hard masked), then the category and complete name and last of all, the slot
330in which the package is stored.
331</p>
332
333<p>
334Another example, this time we are going to use the local options in order
335to look for packages in our portage tree and overlay.
336</p>
337
338<pre caption="Using local options with equery">
339# <i>equery list -p -o vim</i>
340[ Searching for package 'vim' in all categories among: ]
341 * installed packages
342[I--] [ ] app-editors/vim-6.3-r4 (0)
343 * Portage tree (/usr/portage)
344[-P-] [M~] app-editors/vim-7.0_alpha20050126 (0)
345[-P-] [M~] app-editors/vim-7.0_alpha20050201 (0)
346[-P-] [ ] app-editors/vim-6.3-r2 (0)
347[-P-] [M~] app-editors/vim-7.0_alpha20050122 (0)
348[-P-] [M~] app-editors/vim-core-7.0_alpha20050126 (0)
349[-P-] [ ] app-editors/vim-core-6.3-r3 (0)
350[-P-] [M~] app-editors/vim-core-7.0_alpha20050122 (0)
351[-P-] [M~] app-editors/vim-core-7.0_alpha20050201 (0)
352[-P-] [ ] app-editors/vim-core-6.3-r4 (0)
353 * overlay tree (/opt/ebuilds)
354</pre>
355
209 </body> 356</body>
210 </section> 357</section>
211 <section> 358<section>
212 <title>Verifying Package Integrity</title> 359<title>Finding Package Sizes</title>
213
214 <body> 360<body>
215 <p>
216 Sometimes it is useful to check a package's integrity to know that files
217 have not been replaced since they were installed. <c>qpkg</c> can
218 verify md5 sums as well as install times to indicate whether or not files
219 for the package might have been corrupted, replaced, or removed.
220 </p>
221 <p>To check both mtimes and md5 sums, use the <c>-c</c> flag.</p>
222 <pre>
223 361
224hebron portage # <i>qpkg gnupg -c -v 362<p>
225app-crypt/gnupg-1.0.6 * 363Ever been curious to find out how much space a specific package is occupying?
226/usr/lib/gnupg/rndunix !md5! !mtime! 364Since a package could have its files over a number of directories, the usual
227/usr/lib/gnupg/rndegd !md5! !mtime! 365<c>du -hc</c> might not give you the correct figure. Not to worry, here comes
228/usr/lib/gnupg/tiger !md5! !mtime! 366<c>equery</c> to the rescue!
229/usr/bin/gpg !md5! !mtime! 367</p>
230/usr/bin/gpgv !md5! !mtime!
231/usr/share/gnupg/options.skel !md5! !mtime!
232/usr/share/gnupg/FAQ !md5! !mtime!
233/usr/share/gnupg/faq.html !md5! !mtime!
234/usr/share/locale/da/LC_MESSAGES/gnupg.mo !md5! !mtime!
235/usr/share/locale/de/LC_MESSAGES/gnupg.mo !md5! !mtime!
236/usr/share/locale/eo/LC_MESSAGES/gnupg.mo !md5! !mtime!
237/usr/share/locale/et/LC_MESSAGES/gnupg.mo !md5! !mtime!
238/usr/share/locale/fr/LC_MESSAGES/gnupg.mo !md5! !mtime!
239/usr/share/locale/id/LC_MESSAGES/gnupg.mo !md5! !mtime!
240/usr/share/locale/it/LC_MESSAGES/gnupg.mo !md5! !mtime!
241/usr/share/locale/ja/LC_MESSAGES/gnupg.mo !md5! !mtime!
242/usr/share/locale/nl/LC_MESSAGES/gnupg.mo !md5! !mtime!
243/usr/share/locale/pl/LC_MESSAGES/gnupg.mo !md5! !mtime!
244/usr/share/locale/pt_BR/LC_MESSAGES/gnupg.mo !md5! !mtime!
245/usr/share/locale/sv/LC_MESSAGES/gnupg.mo !md5! !mtime!
246/usr/share/locale/tr/LC_MESSAGES/gnupg.mo !md5! !mtime!
247/usr/share/info/gpgv.info.gz !md5! !mtime!
248/usr/share/man/man1/gpg.1.gz !md5! !mtime!
249/usr/share/man/man1/gpgv.1.gz !md5! !mtime!
25024/92
251 368
252app-crypt/gnupg-1.0.7 * 369<pre caption="Package Size">
2530/101 </i> 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
254 </pre> 374</pre>
255 <p>
256 As you can see, I have more than one version of GnuPG installed. <c>qpkg</c>
257 reports that many of the files from the older version have been changed since I
258 installed it. Those packages were most likely modified when I updated
259 from <path>gnupg-1.0.6</path> to <path>gnupg-1.0.7</path>. Note that the last two
260lines indicate
261 that 0 of 101 files from <path>gnupg-1.0.7</path> have been changed since I
262installed. That
263 is good. If any of them had been changed, I would be worried.
264 </p>
265 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
266 </body> 381</body>
267 </section> 382</section>
268 <section> 383<section>
269 <title>But Wait... There's More</title> 384<title>Package-wise list of USE Flags</title>
270 <body> 385<body>
271 <p>
272 <c>qpkg</c> can be used for other querying tasks that I will not go over here. There
273is a very complete
274 manpage for <c>qpkg</c>. Consult that for more information.
275 </p>
276 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
277 </body> 419</body>
278 </section> 420</section>
421<section>
422<title>Where's the ebuild?</title>
423<body>
424
425<p>
426We can also find out which ebuild is being used for a specific package using
427<c>equery</c>. This is done by using the <c>equery which</c> command which
428displays the full path to the ebuild.
429</p>
430
431<pre caption="Displaying the ebuild path">
432# <i>equery which cdrtools</i>
433/usr/portage/app-cdr/cdrtools/cdrtools-2.01_alpha37.ebuild
434</pre>
435
436</body>
437</section>
279</chapter> 438</chapter>
439
280<chapter> 440<chapter>
281 <title>lintool</title> 441<title>euse</title>
282 <section> 442<section>
283 <title>Introduction</title> 443<title>Introduction</title>
284 <body> 444<body>
285 <p>
286 445
287 <c>lintool</c> is a program that checks ebuild scripts for conformance to 446<p>
288 standards and requirements. It is important for ebuild developers to use <c>lintool</c> 447<c>euse</c> is a tool to see, set and unset USE flags at various places. For
289 to ensure that they are doing things correctly and not requiring the core team 448more information on USE flags, please refer to the <uri
290 to do more than they already have to in order to include the ebuild in the Gentoo 449link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE Flags</uri>.
291 repository. 450Please see <c>euse -h</c> for complete help and all options.
292 </p> 451</p>
452
293 </body> 453</body>
294 </section> 454</section>
295 <section> 455<section>
296 <title>Use</title> 456<title>Viewing, Setting and Unsetting USE Flags</title>
297
298 <body> 457<body>
299 <p>
300 Running <c>lintool</c> will produce a nicely formatted list of checks and results that
301 it performs.
302 </p>
303 <pre>
304hebron portage # <i>lintool app-crypt/gnupg/gnupg-1.0.7.ebuild
305app-crypt/gnupg/gnupg-1.0.7.ebuild : Not OK
306 458
307------------------------------------------------------------------------------- 459<p>
308 Summary for all 1 ebuild(s) checked # errors/warns 460The <c>euse -a</c> command reads the current active USE flags and displays
309 ------------------------------------------------------------------------------- 461them.
310 Testing for illegal space characters, weird backslash formatting : 0 / 0 462</p>
311 Testing for malformed headers : 0 / 1
312 Testing for occurence of deprecated try : 0 / 0
313 Testing for superfluous A=${P}.tar.gz : 0 / 0
314 Testing for empty DEPEND : 0 / 0
315 Testing for empty HOMEPAGE : 0 / 0
316 Testing for empty DESCRIPTION : 0 / 0
317 Testing for presence of env vars : 1 / 1
318 Testing for sane USE flag usage : 0 / 0
319 463
320 Total number of ebuilds with errors : 1 (100%) 464<note>
321 Total number of ebuilds with warnings : 1 (100%) 465There are 5 &quot;columns&quot; that <c>euse</c> now uses to show whether a
322 </i> </pre> 466flag is set/unset and where all the flag has been set. The columns are as
323 <p> 467follows -- +/-, set in the Environment, set in make.Conf, set in make.Defaults,
324 The first line summarizes whether the ebuild is okay or not. In the case of 468and set in make.Globals. The output looks like [+ECDG].
325 <c>gnupg-1.0.7.ebuild</c>, it's not. Reading through the list of checks, we can see 469</note>
326 that it got a warning for malformed headers and an error for presence of env
327 vars.
328 </p>
329 470
330 <p> 471<pre caption="Viewing all active USE flags">
331 Looking at the ebuild, I see that it is missing a couple of required 472# <i>euse -a</i>
332 env vars (LICENSE and RDEPEND). Adding those fixes the error. But there are 473X [+ CD ]
333 still two warnings -- one for malformed headers and one for env vars. To help 474aalib [+ ]
334 me find those, I can run <c>lintool</c> again with <c>--show-details</c> 475acpi [+ C ]
335 </p> 476alsa [+ C ]
336 <pre> 477apache2 [+ C ]
337hebron gnupg # <i>lintool --show-details ./gnupg-1.0.7.ebuild 478apm [+ D ]
338 479avi [+ D ]
339------------------------------------------------------------------------------- 480berkdb [+ D ]
340# Some data cut for brevity.... 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 ]
563</pre>
341 564
342 Status for ./gnupg-1.0.7.ebuild 565<p>
343* Testing for malformed headers : passed 566Similarly you can use the <c>euse -a -g</c> command to only view active global
344- (W) Has illegal or suspect headers: 567USE flags. The <c>euse -a -l</c> command does the same for active local USE
345 |Suspect copyright year: # Copyright 1999-2000 Gentoo Technologies, Inc. 568flags.<c>-g</c> &amp; <c>-l</c> are suboptions to <c>euse</c> and need an
346 * Testing for occurence of deprecated try : passed 569option before them (like <c>-a</c>) to function correctly.
347 * Testing for superfluous A=${P}.tar.gz : passed 570</p>
348 * Testing for empty DEPEND : passed
349 * Testing for empty HOMEPAGE : passed
350 * Testing for empty DESCRIPTION : passed
351 * Testing for presence of env vars : passed
352 - (W) Missing SLOT=
353 * Testing for sane USE flag usage : passed
354 571
355 ------------------------------------------------------------------------------- 572<pre caption="Viewing active local USE flags">
356 Summary for all 1 ebuild(s) checked # errors/warns 573# <i>euse -a -l</i>
357 ------------------------------------------------------------------------------- 574bitmap-fonts [+ D ]
358 Testing for illegal space characters, weird backslash formatting : 0 / 0 575font-server [+ D ]
359 Testing for malformed headers : 0 / 1 576fortran [+ D ]
360 Testing for occurence of deprecated try : 0 / 0 577gimpprint [+ C ]
361 Testing for superfluous A=${P}.tar.gz : 0 / 0 578md5sum [+ C ]
362 Testing for empty DEPEND : 0 / 0 579mpeg4 [+ C ]
363 Testing for empty HOMEPAGE : 0 / 0 580nvidia [+ C ]
364 Testing for empty DESCRIPTION : 0 / 0 581offensive [+ ]
365 Testing for presence of env vars : 0 / 1 582truetype [+ CD ]
366 Testing for sane USE flag usage : 0 / 0 583</pre>
367 584
368 Total number of ebuilds with errors : 0 (0%) 585<p>
369 Total number of ebuilds with warnings : 1 (100%) 586We can also use <c>euse</c> to set or unset use flags. The commands used for
370 </i> </pre> 587this are <c>euse -E flagname</c> (enable a flag) and <c>euse -D flagname</c>
371 <p>Now I can see that the year in the ebuild is probably wrong, and that it is 588(disable a flag).
372 missing the SLOT variable. Fixing those eliminates all warnings.</p> 589</p>
373 590
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"
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>
631
374 </body> 632</body>
375 </section> 633</section>
376</chapter> 634</chapter>
635
377<chapter> 636<chapter>
378 637<title>Other tools</title>
379 <title>epm</title>
380 <section> 638<section>
381 <title>Introduction</title> 639<title>revdep-rebuild</title>
382 <body> 640<body>
383 <p>
384 <c>epm</c> is a package managing tool that clones Red Hat rpm commands. As it stands
385 now, it does not offer all of the features of rpm, but it offers some of the more
386 powerful rpm query options.
387 </p>
388 641
389 <p> 642<p>
390 It also handles removing packages, which is not covered here. Use <c>epm --help</c> 643This tool is Gentoo's Reverse Dependency rebuilder. It will scan your installed
391 to learn more about deleting packages with <c>epm</c>. 644ebuilds to find packages that have become broken as a result of an upgrade of a
392 </p> 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
393 </body> 718</body>
394 </section> 719</section>
395 <section> 720<section>
396 721<title>glsa-check</title>
397 <title>Querying Packages with epm</title>
398 <body> 722<body>
399 <p>
400 <c>epm</c> functions with essentially the same command line functions as Red Hat's
401 rpm. <c>epm -qa</c> lists all packages installed. <c>epm -ql</c> lists all the
402 files from a specific ebuild.
403 </p>
404 723
405 <pre> 724<p>
406hebron etc # <i>epm -ql ethereal 725<c>glsa-check</c> is mainly a test tool that keeps track of the various GLSA's
407/usr/lib/ethereal/plugins/0.8.20/gryphon.so 726(Gentoo Linux Security Advisory) and will eventually be integrated into
408/usr/lib/ethereal/plugins/0.8.20/gryphon.la 727<c>emerge</c> and <c>equery</c>. For more information, please visit the <uri
409/usr/lib/ethereal/plugins/0.8.20/gryphon.a 728link="/proj/en/portage/glsa-integration.xml">Portage GLSA Integration
410/usr/lib/ethereal/plugins/0.8.20/mgcp.so 729Page</uri>.
411/usr/lib/ethereal/plugins/0.8.20/mgcp.la 730</p>
412/usr/lib/ethereal/plugins/0.8.20/mgcp.a
413/usr/lib/ethereal/plugins/0.8.20/cosnaming.so
414/usr/lib/ethereal/plugins/0.8.20/cosnaming.la
415/usr/lib/ethereal/plugins/0.8.20/cosnaming.a
416/usr/lib/ethereal/plugins/0.8.20/coseventcomm.so
417/usr/lib/ethereal/plugins/0.8.20/coseventcomm.la
418/usr/lib/ethereal/plugins/0.8.20/coseventcomm.a
419/usr/bin/ethereal
420/usr/bin/editcap
421/usr/bin/mergecap
422/usr/bin/tethereal
423/usr/bin/text2pcap
424/usr/bin/idl2eth
425/usr/share/man/man1/idl2eth.1.gz
426/usr/share/man/man1/tethereal.1.gz
427/usr/share/man/man1/text2pcap.1.gz
428/usr/share/man/man1/editcap.1.gz
429/usr/share/man/man1/ethereal.1.gz
430/usr/share/man/man1/mergecap.1.gz
431/usr/share/doc/ethereal-0.8.20/AUTHORS.gz
432/usr/share/doc/ethereal-0.8.20/COPYING.gz
433/usr/share/doc/ethereal-0.8.20/NEWS.gz
434/usr/share/doc/ethereal-0.8.20/ChangeLog.gz
435/usr/share/doc/ethereal-0.8.20/README.gz
436/usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz
437/usr/share/doc/ethereal-0.8.20/TODO.gz
438/usr/share/doc/ethereal-0.8.20/README.aix.gz
439/usr/share/doc/ethereal-0.8.20/README.bsd.gz
440/usr/share/doc/ethereal-0.8.20/README.hpux.gz
441/usr/share/doc/ethereal-0.8.20/README.irix.gz
442/usr/share/doc/ethereal-0.8.20/README.linux.gz
443/usr/share/doc/ethereal-0.8.20/README.tru64.gz
444/usr/share/doc/ethereal-0.8.20/README.win32.gz
445/usr/share/doc/ethereal-0.8.20/README.vmware.gz
446/etc/ethereal/manuf </i>
447 </pre>
448 <p>
449 <c>epm</c> offers a few advanced query options that are not present in <c>qpkg</c>
450at the
451 time of this writing. For instance, it can query for just configuration files or
452just documentation
453 files.
454 </p>
455 <pre>
456 731
457hebron etc # <i>epm -qc ethereal
458/etc/ethereal/manuf
459
460hebron etc # epm -qd ethereal
461/usr/share/man/man1/idl2eth.1.gz
462/usr/share/man/man1/tethereal.1.gz
463/usr/share/man/man1/text2pcap.1.gz
464/usr/share/man/man1/editcap.1.gz
465/usr/share/man/man1/ethereal.1.gz
466/usr/share/man/man1/mergecap.1.gz
467/usr/share/doc/ethereal-0.8.20/AUTHORS.gz
468/usr/share/doc/ethereal-0.8.20/COPYING.gz
469/usr/share/doc/ethereal-0.8.20/NEWS.gz
470/usr/share/doc/ethereal-0.8.20/ChangeLog.gz
471/usr/share/doc/ethereal-0.8.20/README.gz
472/usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz
473/usr/share/doc/ethereal-0.8.20/TODO.gz
474/usr/share/doc/ethereal-0.8.20/README.aix.gz
475/usr/share/doc/ethereal-0.8.20/README.bsd.gz
476/usr/share/doc/ethereal-0.8.20/README.hpux.gz
477/usr/share/doc/ethereal-0.8.20/README.irix.gz
478/usr/share/doc/ethereal-0.8.20/README.linux.gz
479/usr/share/doc/ethereal-0.8.20/README.tru64.gz
480/usr/share/doc/ethereal-0.8.20/README.win32.gz
481/usr/share/doc/ethereal-0.8.20/README.vmware.gz
482 </i> </pre>
483 <note>
484 <c>emp --help</c> lists the options that epm <e>will eventually</e> support. Note,
485however, that
486 options prefixed with asterisks (*) are not yet implemented.
487 </note>
488 </body> 732</body>
489 </section> 733</section>
490</chapter> 734</chapter>
491 735
492<chapter>
493 <title>Others</title>
494 <section>
495 <title>etc-update</title>
496 <body>
497 <!--
498 - Feel free to add more to this. It probably deserves its own chapter, but I don't
499 - use it, so I can't really write much about it.
500 -->
501 <p>
502 <c>etc-update</c> provides a convenient alternative to updating configuration
503 files by hand. After running an emerge that changes configuration files, you
504 can run etc-update to step you through the process of updating all impacted
505 configuration files.
506 </p>
507
508 <p>
509 It is driven by a menu-based interface and includes the ability to view and merge
510 in config files before deciding what to do.
511 </p>
512 </body>
513 </section>
514 <section>
515 <title>gentool</title>
516 <body>
517 <p>gentool is a collective name for several small scripts that analyze ebuild
518statistics.
519 For instance, gentool-total-coverage prints a list of email addresses and the
520 number of ebuilds each has in the portage tree.
521 </p>
522
523 </body>
524 </section>
525 <section>
526 <title>pkg-size</title>
527 <body>
528 <p><c>pkg-size</c> prints the size of the installed files in a given package.
529 </p>
530 <pre>
531
532hebron portage # <i>pkg-size nmap
533net-analyzer/nmap-2.54_beta24-r1 897024 (876KB) </i>
534 </pre>
535 </body>
536 </section>
537 <section>
538 <title>mkebuild</title>
539 <body>
540 <p><c>mkebuild</c> simplifies the process of creating a new ebuild by automating as
541much
542 of the process as possible. Running <c>mkebuild [filename]</c> will create an
543 ebuild for that file. the file should be an archive of some kind. As it works, it
544 will provide
545 feedback about changes you may need to make.
546 </p>
547
548 </body>
549 </section>
550 <section>
551 <title>emerge-webrsync</title>
552 <body>
553 <!-- Can't find any documentation on this anywhere... not even a comment in the
554code. -->
555 <p>Downloads the daily snapshot over HTTP with wget, and (optionally) syncs with
556portage.
557 </p>
558 </body>
559
560 </section>
561</chapter>
562</guide> 736</guide>
563

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.29

  ViewVC Help
Powered by ViewVC 1.1.20