/[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.10 - (show annotations) (download) (as text)
Fri Mar 26 12:58:32 2004 UTC (10 years, 6 months ago) by cam
Branch: MAIN
Changes since 1.9: +162 -110 lines
File MIME type: application/xml
Fixed coding style.

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.8 2004/03/06 17:06:19 swift Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="/doc/en/gentoolkit.xml">
6 <title>Gentoolkit</title>
7
8 <author title="Author">
9 <mail link="mbutcher@aleph-null.tv">Matt Butcher</mail>
10 </author>
11
12 <author title="Editor">
13 <!-- zhen@gentoo.org -->John P. Davis
14 </author>
15
16 <author title="Editor">
17 <mail link="erwin@gentoo.org">Erwin</mail>
18 </author>
19
20 <!-- Licensed under GFDL -->
21
22 <abstract>
23 Gentoolkit is a suite of tools to ease the administration of a Gentoo system.
24 This document covers the basics of some of the tools present in Gentoolkit.
25 </abstract>
26
27 <version>1.2</version>
28 <date>December 1, 2003</date>
29
30 <chapter>
31 <title>Introduction</title>
32 <section>
33 <title>What is Gentoolkit?</title>
34 <body>
35
36 <p>
37 Gentoo is a unique distribution, and presents some complexities that simply
38 don't exist for other distributions. As Gentoo developers and contributors
39 discovered some of these complexities, they also wrote tools to help users and
40 administrators work around them. Many of these tools have been contributed to
41 the Gentoo project, and are included in the package
42 <c>app-portage/gentoolkit</c>.
43 </p>
44
45 <p>
46 Gentoolkit contains a whole bunch of useful tools to help manage Portage and the
47 ebuild architecture. Most users -- particularly those who update systems often
48 -- will benefit from having gentoolkit installed.
49 </p>
50
51 </body>
52 </section>
53
54 <section>
55 <title>Installation</title>
56 <body>
57
58 <p>
59 Just as with any Gentoo package, installation is just a simple emerge.
60 </p>
61
62 <pre>
63 # <i>emerge gentoolkit</i>
64 </pre>
65
66 <note>
67 Many of the tools in gentoolkit reveal important information about your system
68 or require root permissions. For that reason, some of the programs may only be
69 executed (or only function properly) if run by a user with root permissions.
70 </note>
71
72 </body>
73 </section>
74
75 <section>
76 <title>Finding Documentation</title>
77 <body>
78
79 <p>
80 At the time of this writing, not all of the programs in gentoolkit are well
81 documented. Some have man pages, but not all. Any documentation that a program
82 might have (other than man pages) is stored in
83 <path>/usr/doc/gentoolkit-[version]/[program-name]/</path>.
84 </p>
85
86 </body>
87 </section>
88 </chapter>
89
90 <chapter>
91 <title>Querying Package Data with qpkg</title>
92 <section>
93 <title>Introduction</title>
94 <body>
95
96 <p>
97 <c>qpkg</c> is a flexible tool for determining information about ebuilds,
98 whether installed or not. It can provide information about what files belong
99 to which ebuilds, whether multiple versions of the same package are installed,
100 and what a particular ebuild does.
101 </p>
102
103 <p>
104 Calling <c>qpkg</c> with no arguments prints a list of all ebuilds, with
105 asterisks (*) next to the packages that are installed on the system.
106 </p>
107
108 <note>
109 By default, <c>qpkg</c> prints output in color. To turn this off on the command
110 line, use the <c>--no-color</c> or <c>-nc</c> flag.
111 </note>
112
113 </body>
114 </section>
115
116 <section>
117 <title>Querying Package Information</title>
118 <body>
119
120 <p>
121 One of the most common uses for <c>qpkg</c> is determining what a given package
122 is. For instance, while looking through <path>net-misc</path>, I saw a package
123 called <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>
128 net-misc/neon-0.15.3-r1
129 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
130 net-misc/neon-0.18.5
131 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
132 net-misc/neon-0.19.2
133 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
134 net-misc/neon-0.19.2-r1
135 HTTP and WebDAV client library [ http://www.webdav.org/neon ]
136 net-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
143 DESCRIPTION and HOMEPAGE.
144 </p>
145
146 </body>
147 </section>
148
149 <section>
150 <title>Listing Files Belonging to an Ebuild</title>
151 <body>
152
153 <p>
154 <c>qpkg</c> can also list the files that belong to an installed ebuild. I
155 Know that gentoolkit installed several tools, but I don't know what they
156 all are. To find out, I can do a <c>qpkg -l</c>.
157 </p>
158
159 <pre>
160 # <i>qpkg -l app-portage/gentoolkit</i>
161 app-portage/gentoolkit-0.1.14-r1 *
162 CONTENTS:
163 /usr
164 /usr/share
165 /usr/share/gentoolkit
166 /usr/share/gentoolkit/histogram.awk
167 /usr/share/doc
168 /usr/share/doc/gentoolkit-0.1.14-r1
169 /usr/share/doc/gentoolkit-0.1.14-r1/gentool
170 /usr/share/doc/gentoolkit-0.1.14-r1/gentool/ChangeLog.gz
171 /usr/share/doc/gentoolkit-0.1.14-r1/lintool
172 /usr/share/doc/gentoolkit-0.1.14-r1/lintool/checklist-for-ebuilds.gz
173 /usr/share/doc/gentoolkit-0.1.14-r1/lintool/ChangeLog.gz
174 /usr/share/doc/gentoolkit-0.1.14-r1/etc-update
175 /usr/share/doc/gentoolkit-0.1.14-r1/etc-update/ChangeLog.gz
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>
198
199 </body>
200 </section>
201
202 <section>
203 <title>Finding the Package from Where a File Came</title>
204 <body>
205
206 <p>
207 To 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>
217
218 <section>
219 <title>Listing Duplicate Packages</title>
220 <body>
221
222 <p>
223 Sometimes multiple versions of the same package may exist. <c>qpkg --dup</c>
224 will print a list of duplicate packages. The existence of a duplicate package
225 though may not indicate that the older version may be removed. They may fill
226 different 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
228 duplicates in the same slot.
229 </p>
230
231 <pre>
232 # <i>qpkg --dups --slot</i>
233 app-portage/gentoolkit
234 kde-base/kdeaddons
235 kde-base/kdeadmin
236 kde-base/kdeartwork
237 kde-base/kdebase
238 kde-base/kdegames
239 kde-base/kdelibs
240 kde-base/kdemultimedia
241 kde-base/kdenetwork
242 kde-base/kdetoys
243 kde-base/kdeutils
244 media-libs/freetype
245 x11-libs/qt
246 </pre>
247
248 </body>
249 </section>
250
251 <section>
252 <title>Verifying Package Integrity</title>
253 <body>
254
255 <p>
256 Sometimes it is useful to check a package's integrity to know that files have
257 not been replaced since they were installed. <c>qpkg</c> can verify md5 sums as
258 well as install times to indicate whether or not files for the package might
259 have been corrupted, replaced, or removed.
260 </p>
261
262 <p>
263 To check both mtimes and md5 sums, use the <c>-c</c> flag.
264 </p>
265
266 <pre>
267 # <i>qpkg gnupg -c -v</i>
268 app-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!
293 24/92
294
295 app-crypt/gnupg-1.0.7 *
296 0/101
297 </pre>
298
299 <p>
300 As you can see, I have more than one version of GnuPG installed. <c>qpkg</c>
301 reports that many of the files from the older version have been changed since I
302 installed 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
304 lines indicate that 0 of 101 files from <path>gnupg-1.0.7</path> have been
305 changed since I installed. That is good. If any of them had been changed, I
306 would be worried.
307 </p>
308
309 </body>
310 </section>
311
312 <section>
313 <title>But Wait... There's More</title>
314 <body>
315
316 <p>
317 <c>qpkg</c> can be used for other querying tasks that I will not go over here.
318 There is a very complete manpage for <c>qpkg</c>. Consult that for more
319 information.
320 </p>
321
322 </body>
323 </section>
324 </chapter>
325
326 <chapter>
327 <title>lintool</title>
328 <section>
329 <title>Introduction</title>
330 <body>
331
332 <p>
333
334 <c>lintool</c> is a program that checks ebuild scripts for conformance to
335 standards and requirements. It is important for ebuild developers to use
336 <c>lintool</c> to ensure that they are doing things correctly and not requiring
337 the core team to do more than they already have to in order to include the
338 ebuild in the Gentoo repository.
339 </p>
340
341 </body>
342 </section>
343
344 <section>
345 <title>Use</title>
346 <body>
347
348 <p>
349 Running <c>lintool</c> will produce a nicely formatted list of checks and
350 results that it performs.
351 </p>
352
353 <pre>
354 # <i>lintool app-crypt/gnupg/gnupg-1.0.7.ebuild</i>
355 app-crypt/gnupg/gnupg-1.0.7.ebuild : Not OK
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 : 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>
375 The 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
377 see that it got a warning for malformed headers and an error for presence of env
378 vars.
379 </p>
380
381 <p>
382 Looking at the ebuild, I see that it is missing a couple of required
383 env vars (LICENSE and RDEPEND). Adding those fixes the error. But there are
384 still two warnings -- one for malformed headers and one for env vars. To help
385 me find those, I can run <c>lintool</c> again with <c>--show-details</c>
386 </p>
387
388 <pre>
389 # <i>lintool --show-details ./gnupg-1.0.7.ebuild</i>
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>
425 Now I can see that the year in the ebuild is probably wrong, and that it is
426 missing the SLOT variable. Fixing those eliminates all warnings.
427 </p>
428
429 </body>
430 </section>
431 </chapter>
432
433 <chapter>
434 <title>epm</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
441 stands now, it does not offer all of the features of rpm, but it offers some of
442 the more powerful rpm query options.
443 </p>
444
445 <p>
446 It 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>
452 <section>
453
454 <title>Querying Packages with epm</title>
455 <body>
456
457 <p>
458 <c>epm</c> functions with essentially the same command line functions as Red
459 Hat's rpm. <c>epm -qa</c> lists all packages installed. <c>epm -ql</c> lists all
460 the files from a specific ebuild.
461 </p>
462
463 <pre>
464 # <i>epm -ql ethereal</i>
465 /usr/lib/ethereal/plugins/0.8.20/gryphon.so
466 /usr/lib/ethereal/plugins/0.8.20/gryphon.la
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>
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
510 configuration 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.
543 Note, however, that options prefixed with asterisks (*) are not yet implemented.
544 </note>
545
546 </body>
547 </section>
548 </chapter>
549
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
562 files by hand. After running an emerge that changes configuration files, you
563 can run etc-update to step you through the process of updating all impacted
564 configuration files.
565 </p>
566
567 <p>
568 It is driven by a menu-based interface and includes the ability to view and
569 merge 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>
580 gentool is a collective name for several small scripts that analyze ebuild
581 statistics.
582 For instance, gentool-total-coverage prints a list of email addresses and the
583 number 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>
599 net-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
611 much of the process as possible. Running <c>mkebuild [filename]</c> will create
612 an ebuild for that file. the file should be an archive of some kind. As it
613 works, 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
623 code. -->
624
625 <p>
626 Downloads the daily snapshot over HTTP with wget, and (optionally) syncs with
627 portage.
628 </p>
629
630 </body>
631 </section>
632 </chapter>
633 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20