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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.5 - (show annotations) (download) (as text)
Sat Oct 25 08:50:41 2003 UTC (10 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.4: +3 -1 lines
File MIME type: application/xml
ZhEN asked to have his e-mail address removed from all docs

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3
4 <guide link = "/doc/en/gentoolkit.xml">
5 <title>Gentoolkit</title>
6 <author title="Author"><mail link="mbutcher@aleph-null.tv">
7 Matt Butcher</mail>
8 </author>
9
10 <author title="Editor"><!-- zhen@gentoo.org -->
11 John P. Davis
12 </author>
13 <!-- Licensed under GFDL -->
14
15 <abstract>
16 Gentoolkit is a suite of tools to ease the administration of a Gentoo system.
17 This document covers the basics of
18 some of the tools present in Gentoolkit.
19 </abstract>
20
21 <version>1.1</version>
22 <date>25 September 2002</date>
23
24 <chapter>
25 <title>Introduction</title>
26 <section>
27 <title>What is Gentoolkit?</title>
28 <body>
29 <p>Gentoo is a unique distribution, and presents some complexities that
30 simply don't exist for other distributions. As Gentoo developers
31 and contributors discovered some of these complexities, they also
32 wrote tools to help users and administrators work around them.
33 Many of these tools have been contributed to the Gentoo project,
34 and are included in the package <path>app-admin/gentoolkit</path>.
35 </p>
36
37 <p>Gentoolkit contains a whole bunch of useful tools to help manage
38 Portage and the ebuild architecture. Most users -- particularly
39 those who update systems often -- will benefit from having
40 gentoolkit installed.</p>
41 </body>
42 </section>
43 <section>
44 <title>Installation</title>
45 <body>
46 <p>Just as with any Gentoo package, installation is just a simple
47 emerge.
48 </p>
49
50 <pre>
51 <i>emerge gentoolkit </i>
52 </pre>
53 <note>Many of the tools in gentoolkit reveal important information
54 about your system or require root permissions. For that reason,
55 some of the programs may only be executed (or only function
56 properly) if run by a user with root permissions.</note>
57 </body>
58 </section>
59 <section>
60 <title>Finding Documentation</title>
61 <body>
62
63 <p>
64 At the time of this writing, not all of the programs in gentoolkit
65 are well documented. Some have man pages, but not all. Any documentation
66 that a program might have (other than man pages) is stored in
67 <path>/usr/doc/gentoolkit-[version]/[program-name]/</path>.
68 </p>
69 </body>
70 </section>
71 </chapter>
72 <chapter>
73 <title>Querying Package Data with qpkg</title>
74 <section>
75
76 <title>Introduction</title>
77 <body>
78 <p><c>qpkg</c> is flexible tool for determining information about ebuilds,
79 whether installed or not. It can provide information about what files belong
80 to which ebuilds, whether multiple versions of the same package are installed,
81 and what a particular ebuild does.
82 </p>
83 <p>Calling <c>qpkg</c> with no arguments prints a list of all ebuilds, with asterisks
84 (*) next to the packages that are installed on the system.
85 </p>
86 <note>By default, <c>qpkg</c> prints output in color. To turn this off on the command
87 line, use the <c>--no-color</c> or <c>-nc</c> flag.</note>
88
89 </body>
90 </section>
91 <section>
92 <title>Querying Package Information</title>
93 <body>
94 <p>One of the most common uses for <c>qpkg</c> is determining what a given package
95 is. For instance, while looking through <path>net-misc</path>, I saw a package
96 called <path>neon</path>. Having no idea what it was, I ran qpkg.
97 </p>
98
99 <pre>
100 hebron root # <i>qpkg -i net-misc/neon
101 net-misc/neon-0.15.3-r1
102 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
103 net-misc/neon-0.18.5
104 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
105 net-misc/neon-0.19.2
106 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
107 net-misc/neon-0.19.2-r1
108 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
109 net-misc/neon-0.21.1
110 HTTP and WebDAV client library [ http://www.webdav.org/neon ] </i>
111 </pre>
112 <p>
113 <c>qpkg</c> read through the ebuild files for the five <path>net-misc/neon</path>
114 ebuilds and printed out the information stored in DESCRIPTION and HOMEPAGE.
115 </p>
116 </body>
117
118 </section>
119 <section>
120 <title>Listing Files Belonging to an Ebuild</title>
121 <body>
122 <p>
123 <c>qpkg</c> can also list the files that belong to an installed ebuild. I
124 Know that gentoolkit installed several tools, but I don't know what they
125 all are. To find out, I can do a <c>qpkg -l</c>
126
127 </p>
128 <pre>
129 hebron portage # <i>qpkg -l app-admin/gentoolkit
130 app-admin/gentoolkit-0.1.14-r1 *
131 CONTENTS:
132 /usr
133 /usr/share
134 /usr/share/gentoolkit
135 /usr/share/gentoolkit/histogram.awk
136 /usr/share/doc
137 /usr/share/doc/gentoolkit-0.1.14-r1
138 /usr/share/doc/gentoolkit-0.1.14-r1/gentool
139 /usr/share/doc/gentoolkit-0.1.14-r1/gentool/ChangeLog.gz
140 /usr/share/doc/gentoolkit-0.1.14-r1/lintool
141 /usr/share/doc/gentoolkit-0.1.14-r1/lintool/checklist-for-ebuilds.gz
142 /usr/share/doc/gentoolkit-0.1.14-r1/lintool/ChangeLog.gz
143 /usr/share/doc/gentoolkit-0.1.14-r1/etc-update
144 /usr/share/doc/gentoolkit-0.1.14-r1/etc-update/ChangeLog.gz
145 /usr/share/man
146 /usr/share/man/man1
147 /usr/share/man/man1/qpkg.1.gz
148 /usr/share/man/man1/lintool.1.gz
149 /usr/share/man/man1/etc-update.1.gz
150 /usr/bin
151 /usr/bin/gentool-bump-revision
152 /usr/bin/gentool-total-coverage
153 /usr/bin/gentool-author-coverage
154 /usr/bin/gentool-package-count
155 /usr/bin/qpkg
156 /usr/bin/pkg-size
157 /usr/bin/lintool
158 /usr/sbin
159 /usr/sbin/pkg-clean
160 /usr/sbin/mkebuild
161 /usr/sbin/emerge-webrsync
162 /usr/sbin/epm
163 /usr/sbin/etc-update
164 /etc
165 /etc/etc-update.conf </i>
166 </pre>
167 </body>
168 </section>
169 <section>
170 <title>Finding the Package from Where a File Came</title>
171 <body>
172
173 <p>
174 To find the package that a file came from, use the <c>-f</c>
175 or <c>--find-file</c> flag.
176 </p>
177 <pre>
178 hebron portage # <i>qpkg -f net-www/mozilla * </i>
179 </pre>
180
181 </body>
182 </section>
183 <section>
184 <title>Listing Duplicate Packages</title>
185 <body>
186 <p>
187 Sometimes multiple versions of the same package may exist. <c>qpkg --dup</c>
188
189 will print a list of duplicate packages. The existence of a duplicate package
190 though may not indicate that the older version may be removed. They may fill
191 different slots. To look for duplicates in the same slot, use
192 <c>qpkg --dups --slot</c>. I just updated KDE from 3.0 to 3.0.2, so I have some
193 duplicates in the same slot.
194 </p>
195 <pre>
196 hebron portage # <i>qpkg --dups --slot
197 app-admin/gentoolkit
198 kde-base/kdeaddons
199 kde-base/kdeadmin
200 kde-base/kdeartwork
201 kde-base/kdebase
202 kde-base/kdegames
203 kde-base/kdelibs
204 kde-base/kdemultimedia
205 kde-base/kdenetwork
206 kde-base/kdetoys
207 kde-base/kdeutils
208 media-libs/freetype
209 x11-libs/qt </i>
210 </pre>
211 </body>
212 </section>
213 <section>
214 <title>Verifying Package Integrity</title>
215
216 <body>
217 <p>
218 Sometimes it is useful to check a package's integrity to know that files
219 have not been replaced since they were installed. <c>qpkg</c> can
220 verify md5 sums as well as install times to indicate whether or not files
221 for the package might have been corrupted, replaced, or removed.
222 </p>
223 <p>To check both mtimes and md5 sums, use the <c>-c</c> flag.</p>
224 <pre>
225
226 hebron portage # <i>qpkg gnupg -c -v
227 app-crypt/gnupg-1.0.6 *
228 /usr/lib/gnupg/rndunix !md5! !mtime!
229 /usr/lib/gnupg/rndegd !md5! !mtime!
230 /usr/lib/gnupg/tiger !md5! !mtime!
231 /usr/bin/gpg !md5! !mtime!
232 /usr/bin/gpgv !md5! !mtime!
233 /usr/share/gnupg/options.skel !md5! !mtime!
234 /usr/share/gnupg/FAQ !md5! !mtime!
235 /usr/share/gnupg/faq.html !md5! !mtime!
236 /usr/share/locale/da/LC_MESSAGES/gnupg.mo !md5! !mtime!
237 /usr/share/locale/de/LC_MESSAGES/gnupg.mo !md5! !mtime!
238 /usr/share/locale/eo/LC_MESSAGES/gnupg.mo !md5! !mtime!
239 /usr/share/locale/et/LC_MESSAGES/gnupg.mo !md5! !mtime!
240 /usr/share/locale/fr/LC_MESSAGES/gnupg.mo !md5! !mtime!
241 /usr/share/locale/id/LC_MESSAGES/gnupg.mo !md5! !mtime!
242 /usr/share/locale/it/LC_MESSAGES/gnupg.mo !md5! !mtime!
243 /usr/share/locale/ja/LC_MESSAGES/gnupg.mo !md5! !mtime!
244 /usr/share/locale/nl/LC_MESSAGES/gnupg.mo !md5! !mtime!
245 /usr/share/locale/pl/LC_MESSAGES/gnupg.mo !md5! !mtime!
246 /usr/share/locale/pt_BR/LC_MESSAGES/gnupg.mo !md5! !mtime!
247 /usr/share/locale/sv/LC_MESSAGES/gnupg.mo !md5! !mtime!
248 /usr/share/locale/tr/LC_MESSAGES/gnupg.mo !md5! !mtime!
249 /usr/share/info/gpgv.info.gz !md5! !mtime!
250 /usr/share/man/man1/gpg.1.gz !md5! !mtime!
251 /usr/share/man/man1/gpgv.1.gz !md5! !mtime!
252 24/92
253
254 app-crypt/gnupg-1.0.7 *
255 0/101 </i>
256 </pre>
257 <p>
258 As you can see, I have more than one version of GnuPG installed. <c>qpkg</c>
259 reports that many of the files from the older version have been changed since I
260 installed it. Those packages were most likely modified when I updated
261 from <path>gnupg-1.0.6</path> to <path>gnupg-1.0.7</path>. Note that the last two
262 lines indicate
263 that 0 of 101 files from <path>gnupg-1.0.7</path> have been changed since I
264 installed. That
265 is good. If any of them had been changed, I would be worried.
266 </p>
267
268 </body>
269 </section>
270 <section>
271 <title>But Wait... There's More</title>
272 <body>
273 <p>
274 <c>qpkg</c> can be used for other querying tasks that I will not go over here. There
275 is a very complete
276 manpage for <c>qpkg</c>. Consult that for more information.
277 </p>
278
279 </body>
280 </section>
281 </chapter>
282 <chapter>
283 <title>lintool</title>
284 <section>
285 <title>Introduction</title>
286 <body>
287 <p>
288
289 <c>lintool</c> is a program that checks ebuild scripts for conformance to
290 standards and requirements. It is important for ebuild developers to use <c>lintool</c>
291 to ensure that they are doing things correctly and not requiring the core team
292 to do more than they already have to in order to include the ebuild in the Gentoo
293 repository.
294 </p>
295 </body>
296 </section>
297 <section>
298 <title>Use</title>
299
300 <body>
301 <p>
302 Running <c>lintool</c> will produce a nicely formatted list of checks and results that
303 it performs.
304 </p>
305 <pre>
306 hebron portage # <i>lintool app-crypt/gnupg/gnupg-1.0.7.ebuild
307 app-crypt/gnupg/gnupg-1.0.7.ebuild : Not OK
308
309 -------------------------------------------------------------------------------
310 Summary for all 1 ebuild(s) checked # errors/warns
311 -------------------------------------------------------------------------------
312 Testing for illegal space characters, weird backslash formatting : 0 / 0
313 Testing for malformed headers : 0 / 1
314 Testing for occurence of deprecated try : 0 / 0
315 Testing for superfluous A=${P}.tar.gz : 0 / 0
316 Testing for empty DEPEND : 0 / 0
317 Testing for empty HOMEPAGE : 0 / 0
318 Testing for empty DESCRIPTION : 0 / 0
319 Testing for presence of env vars : 1 / 1
320 Testing for sane USE flag usage : 0 / 0
321
322 Total number of ebuilds with errors : 1 (100%)
323 Total number of ebuilds with warnings : 1 (100%)
324 </i> </pre>
325 <p>
326 The first line summarizes whether the ebuild is okay or not. In the case of
327 <c>gnupg-1.0.7.ebuild</c>, it's not. Reading through the list of checks, we can see
328 that it got a warning for malformed headers and an error for presence of env
329 vars.
330 </p>
331
332 <p>
333 Looking at the ebuild, I see that it is missing a couple of required
334 env vars (LICENSE and RDEPEND). Adding those fixes the error. But there are
335 still two warnings -- one for malformed headers and one for env vars. To help
336 me find those, I can run <c>lintool</c> again with <c>--show-details</c>
337 </p>
338 <pre>
339 hebron gnupg # <i>lintool --show-details ./gnupg-1.0.7.ebuild
340
341 -------------------------------------------------------------------------------
342 # Some data cut for brevity....
343
344 Status for ./gnupg-1.0.7.ebuild
345 * Testing for malformed headers : passed
346 - (W) Has illegal or suspect headers:
347 |Suspect copyright year: # Copyright 1999-2000 Gentoo Technologies, Inc.
348 * Testing for occurence of deprecated try : passed
349 * Testing for superfluous A=${P}.tar.gz : passed
350 * Testing for empty DEPEND : passed
351 * Testing for empty HOMEPAGE : passed
352 * Testing for empty DESCRIPTION : passed
353 * Testing for presence of env vars : passed
354 - (W) Missing SLOT=
355 * Testing for sane USE flag usage : passed
356
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 : 0 / 1
368 Testing for sane USE flag usage : 0 / 0
369
370 Total number of ebuilds with errors : 0 (0%)
371 Total number of ebuilds with warnings : 1 (100%)
372 </i> </pre>
373 <p>Now I can see that the year in the ebuild is probably wrong, and that it is
374 missing the SLOT variable. Fixing those eliminates all warnings.</p>
375
376 </body>
377 </section>
378 </chapter>
379 <chapter>
380
381 <title>epm</title>
382 <section>
383 <title>Introduction</title>
384 <body>
385 <p>
386 <c>epm</c> is a package managing tool that clones Red Hat rpm commands. As it stands
387 now, it does not offer all of the features of rpm, but it offers some of the more
388 powerful rpm query options.
389 </p>
390
391 <p>
392 It also handles removing packages, which is not covered here. Use <c>epm --help</c>
393 to learn more about deleting packages with <c>epm</c>.
394 </p>
395 </body>
396 </section>
397 <section>
398
399 <title>Querying Packages with epm</title>
400 <body>
401 <p>
402 <c>epm</c> functions with essentially the same command line functions as Red Hat's
403 rpm. <c>epm -qa</c> lists all packages installed. <c>epm -ql</c> lists all the
404 files from a specific ebuild.
405 </p>
406
407 <pre>
408 hebron etc # <i>epm -ql ethereal
409 /usr/lib/ethereal/plugins/0.8.20/gryphon.so
410 /usr/lib/ethereal/plugins/0.8.20/gryphon.la
411 /usr/lib/ethereal/plugins/0.8.20/gryphon.a
412 /usr/lib/ethereal/plugins/0.8.20/mgcp.so
413 /usr/lib/ethereal/plugins/0.8.20/mgcp.la
414 /usr/lib/ethereal/plugins/0.8.20/mgcp.a
415 /usr/lib/ethereal/plugins/0.8.20/cosnaming.so
416 /usr/lib/ethereal/plugins/0.8.20/cosnaming.la
417 /usr/lib/ethereal/plugins/0.8.20/cosnaming.a
418 /usr/lib/ethereal/plugins/0.8.20/coseventcomm.so
419 /usr/lib/ethereal/plugins/0.8.20/coseventcomm.la
420 /usr/lib/ethereal/plugins/0.8.20/coseventcomm.a
421 /usr/bin/ethereal
422 /usr/bin/editcap
423 /usr/bin/mergecap
424 /usr/bin/tethereal
425 /usr/bin/text2pcap
426 /usr/bin/idl2eth
427 /usr/share/man/man1/idl2eth.1.gz
428 /usr/share/man/man1/tethereal.1.gz
429 /usr/share/man/man1/text2pcap.1.gz
430 /usr/share/man/man1/editcap.1.gz
431 /usr/share/man/man1/ethereal.1.gz
432 /usr/share/man/man1/mergecap.1.gz
433 /usr/share/doc/ethereal-0.8.20/AUTHORS.gz
434 /usr/share/doc/ethereal-0.8.20/COPYING.gz
435 /usr/share/doc/ethereal-0.8.20/NEWS.gz
436 /usr/share/doc/ethereal-0.8.20/ChangeLog.gz
437 /usr/share/doc/ethereal-0.8.20/README.gz
438 /usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz
439 /usr/share/doc/ethereal-0.8.20/TODO.gz
440 /usr/share/doc/ethereal-0.8.20/README.aix.gz
441 /usr/share/doc/ethereal-0.8.20/README.bsd.gz
442 /usr/share/doc/ethereal-0.8.20/README.hpux.gz
443 /usr/share/doc/ethereal-0.8.20/README.irix.gz
444 /usr/share/doc/ethereal-0.8.20/README.linux.gz
445 /usr/share/doc/ethereal-0.8.20/README.tru64.gz
446 /usr/share/doc/ethereal-0.8.20/README.win32.gz
447 /usr/share/doc/ethereal-0.8.20/README.vmware.gz
448 /etc/ethereal/manuf </i>
449 </pre>
450 <p>
451 <c>epm</c> offers a few advanced query options that are not present in <c>qpkg</c>
452 at the
453 time of this writing. For instance, it can query for just configuration files or
454 just documentation
455 files.
456 </p>
457 <pre>
458
459 hebron etc # <i>epm -qc ethereal
460 /etc/ethereal/manuf
461
462 hebron etc # epm -qd ethereal
463 /usr/share/man/man1/idl2eth.1.gz
464 /usr/share/man/man1/tethereal.1.gz
465 /usr/share/man/man1/text2pcap.1.gz
466 /usr/share/man/man1/editcap.1.gz
467 /usr/share/man/man1/ethereal.1.gz
468 /usr/share/man/man1/mergecap.1.gz
469 /usr/share/doc/ethereal-0.8.20/AUTHORS.gz
470 /usr/share/doc/ethereal-0.8.20/COPYING.gz
471 /usr/share/doc/ethereal-0.8.20/NEWS.gz
472 /usr/share/doc/ethereal-0.8.20/ChangeLog.gz
473 /usr/share/doc/ethereal-0.8.20/README.gz
474 /usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz
475 /usr/share/doc/ethereal-0.8.20/TODO.gz
476 /usr/share/doc/ethereal-0.8.20/README.aix.gz
477 /usr/share/doc/ethereal-0.8.20/README.bsd.gz
478 /usr/share/doc/ethereal-0.8.20/README.hpux.gz
479 /usr/share/doc/ethereal-0.8.20/README.irix.gz
480 /usr/share/doc/ethereal-0.8.20/README.linux.gz
481 /usr/share/doc/ethereal-0.8.20/README.tru64.gz
482 /usr/share/doc/ethereal-0.8.20/README.win32.gz
483 /usr/share/doc/ethereal-0.8.20/README.vmware.gz
484 </i> </pre>
485 <note>
486 <c>emp --help</c> lists the options that epm <e>will eventually</e> support. Note,
487 however, that
488 options prefixed with asterisks (*) are not yet implemented.
489 </note>
490 </body>
491 </section>
492 </chapter>
493
494 <chapter>
495 <title>Others</title>
496 <section>
497 <title>etc-update</title>
498 <body>
499 <!--
500 - Feel free to add more to this. It probably deserves its own chapter, but I don't
501 - use it, so I can't really write much about it.
502 -->
503 <p>
504 <c>etc-update</c> provides a convenient alternative to updating configuration
505 files by hand. After running an emerge that changes configuration files, you
506 can run etc-update to step you through the process of updating all impacted
507 configuration files.
508 </p>
509
510 <p>
511 It is driven by a menu-based interface and includes the ability to view and merge
512 in config files before deciding what to do.
513 </p>
514 </body>
515 </section>
516 <section>
517 <title>gentool</title>
518 <body>
519 <p>gentool is a collective name for several small scripts that analyze ebuild
520 statistics.
521 For instance, gentool-total-coverage prints a list of email addresses and the
522 number of ebuilds each has in the portage tree.
523 </p>
524
525 </body>
526 </section>
527 <section>
528 <title>pkg-size</title>
529 <body>
530 <p><c>pkg-size</c> prints the size of the installed files in a given package.
531 </p>
532 <pre>
533
534 hebron portage # <i>pkg-size nmap
535 net-analyzer/nmap-2.54_beta24-r1 897024 (876KB) </i>
536 </pre>
537 </body>
538 </section>
539 <section>
540 <title>mkebuild</title>
541 <body>
542 <p><c>mkebuild</c> simplifies the process of creating a new ebuild by automating as
543 much
544 of the process as possible. Running <c>mkebuild [filename]</c> will create an
545 ebuild for that file. the file should be an archive of some kind. As it works, it
546 will provide
547 feedback about changes you may need to make.
548 </p>
549
550 </body>
551 </section>
552 <section>
553 <title>emerge-webrsync</title>
554 <body>
555 <!-- Can't find any documentation on this anywhere... not even a comment in the
556 code. -->
557 <p>Downloads the daily snapshot over HTTP with wget, and (optionally) syncs with
558 portage.
559 </p>
560 </body>
561
562 </section>
563 </chapter>
564 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20