/[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.12 - (show annotations) (download) (as text)
Tue Jun 29 09:47:17 2004 UTC (10 years, 2 months ago) by neysx
Branch: MAIN
Changes since 1.11: +2 -2 lines
File MIME type: application/xml
#55154bis s/--dup/--dups/

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.11 2004/06/25 22:28:55 vapier 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.3</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 -f /usr/lib/mozilla</i>
213 net-www/mozilla *
214 </pre>
215
216 </body>
217 </section>
218
219 <section>
220 <title>Listing Duplicate Packages</title>
221 <body>
222
223 <p>
224 Sometimes multiple versions of the same package may exist. <c>qpkg --dups</c>
225 will print a list of duplicate packages. The existence of a duplicate package
226 though may not indicate that the older version may be removed. They may fill
227 different slots. To look for duplicates in the same slot, use
228 <c>qpkg --dups --slot</c>. I just updated KDE from 3.0 to 3.0.2, so I have some
229 duplicates in the same slot.
230 </p>
231
232 <pre>
233 # <i>qpkg --dups --slot</i>
234 app-portage/gentoolkit
235 kde-base/kdeaddons
236 kde-base/kdeadmin
237 kde-base/kdeartwork
238 kde-base/kdebase
239 kde-base/kdegames
240 kde-base/kdelibs
241 kde-base/kdemultimedia
242 kde-base/kdenetwork
243 kde-base/kdetoys
244 kde-base/kdeutils
245 media-libs/freetype
246 x11-libs/qt
247 </pre>
248
249 </body>
250 </section>
251
252 <section>
253 <title>Verifying Package Integrity</title>
254 <body>
255
256 <p>
257 Sometimes it is useful to check a package's integrity to know that files have
258 not been replaced since they were installed. <c>qpkg</c> can verify md5 sums as
259 well as install times to indicate whether or not files for the package might
260 have been corrupted, replaced, or removed.
261 </p>
262
263 <p>
264 To check both mtimes and md5 sums, use the <c>-c</c> flag.
265 </p>
266
267 <pre>
268 # <i>qpkg gnupg -c -v</i>
269 app-crypt/gnupg-1.0.6 *
270 /usr/lib/gnupg/rndunix !md5! !mtime!
271 /usr/lib/gnupg/rndegd !md5! !mtime!
272 /usr/lib/gnupg/tiger !md5! !mtime!
273 /usr/bin/gpg !md5! !mtime!
274 /usr/bin/gpgv !md5! !mtime!
275 /usr/share/gnupg/options.skel !md5! !mtime!
276 /usr/share/gnupg/FAQ !md5! !mtime!
277 /usr/share/gnupg/faq.html !md5! !mtime!
278 /usr/share/locale/da/LC_MESSAGES/gnupg.mo !md5! !mtime!
279 /usr/share/locale/de/LC_MESSAGES/gnupg.mo !md5! !mtime!
280 /usr/share/locale/eo/LC_MESSAGES/gnupg.mo !md5! !mtime!
281 /usr/share/locale/et/LC_MESSAGES/gnupg.mo !md5! !mtime!
282 /usr/share/locale/fr/LC_MESSAGES/gnupg.mo !md5! !mtime!
283 /usr/share/locale/id/LC_MESSAGES/gnupg.mo !md5! !mtime!
284 /usr/share/locale/it/LC_MESSAGES/gnupg.mo !md5! !mtime!
285 /usr/share/locale/ja/LC_MESSAGES/gnupg.mo !md5! !mtime!
286 /usr/share/locale/nl/LC_MESSAGES/gnupg.mo !md5! !mtime!
287 /usr/share/locale/pl/LC_MESSAGES/gnupg.mo !md5! !mtime!
288 /usr/share/locale/pt_BR/LC_MESSAGES/gnupg.mo !md5! !mtime!
289 /usr/share/locale/sv/LC_MESSAGES/gnupg.mo !md5! !mtime!
290 /usr/share/locale/tr/LC_MESSAGES/gnupg.mo !md5! !mtime!
291 /usr/share/info/gpgv.info.gz !md5! !mtime!
292 /usr/share/man/man1/gpg.1.gz !md5! !mtime!
293 /usr/share/man/man1/gpgv.1.gz !md5! !mtime!
294 24/92
295
296 app-crypt/gnupg-1.0.7 *
297 0/101
298 </pre>
299
300 <p>
301 As you can see, I have more than one version of GnuPG installed. <c>qpkg</c>
302 reports that many of the files from the older version have been changed since I
303 installed it. Those packages were most likely modified when I updated from
304 <path>gnupg-1.0.6</path> to <path>gnupg-1.0.7</path>. Note that the last two
305 lines indicate that 0 of 101 files from <path>gnupg-1.0.7</path> have been
306 changed since I installed. That is good. If any of them had been changed, I
307 would be worried.
308 </p>
309
310 </body>
311 </section>
312
313 <section>
314 <title>But Wait... There's More</title>
315 <body>
316
317 <p>
318 <c>qpkg</c> can be used for other querying tasks that I will not go over here.
319 There is a very complete manpage for <c>qpkg</c>. Consult that for more
320 information.
321 </p>
322
323 </body>
324 </section>
325 </chapter>
326
327 <chapter>
328 <title>lintool</title>
329 <section>
330 <title>Introduction</title>
331 <body>
332
333 <p>
334
335 <c>lintool</c> is a program that checks ebuild scripts for conformance to
336 standards and requirements. It is important for ebuild developers to use
337 <c>lintool</c> to ensure that they are doing things correctly and not requiring
338 the core team to do more than they already have to in order to include the
339 ebuild in the Gentoo repository.
340 </p>
341
342 </body>
343 </section>
344
345 <section>
346 <title>Use</title>
347 <body>
348
349 <p>
350 Running <c>lintool</c> will produce a nicely formatted list of checks and
351 results that it performs.
352 </p>
353
354 <pre>
355 # <i>lintool app-crypt/gnupg/gnupg-1.0.7.ebuild</i>
356 app-crypt/gnupg/gnupg-1.0.7.ebuild : Not OK
357
358 -------------------------------------------------------------------------------
359 Summary for all 1 ebuild(s) checked # errors/warns
360 -------------------------------------------------------------------------------
361 Testing for illegal space characters, weird backslash formatting : 0 / 0
362 Testing for malformed headers : 0 / 1
363 Testing for occurence of deprecated try : 0 / 0
364 Testing for superfluous A=${P}.tar.gz : 0 / 0
365 Testing for empty DEPEND : 0 / 0
366 Testing for empty HOMEPAGE : 0 / 0
367 Testing for empty DESCRIPTION : 0 / 0
368 Testing for presence of env vars : 1 / 1
369 Testing for sane USE flag usage : 0 / 0
370
371 Total number of ebuilds with errors : 1 (100%)
372 Total number of ebuilds with warnings : 1 (100%)
373 </pre>
374
375 <p>
376 The first line summarizes whether the ebuild is okay or not. In the case of
377 <c>gnupg-1.0.7.ebuild</c>, it's not. Reading through the list of checks, we can
378 see that it got a warning for malformed headers and an error for presence of env
379 vars.
380 </p>
381
382 <p>
383 Looking at the ebuild, I see that it is missing a couple of required
384 env vars (LICENSE and RDEPEND). Adding those fixes the error. But there are
385 still two warnings -- one for malformed headers and one for env vars. To help
386 me find those, I can run <c>lintool</c> again with <c>--show-details</c>
387 </p>
388
389 <pre>
390 # <i>lintool --show-details ./gnupg-1.0.7.ebuild</i>
391
392 -------------------------------------------------------------------------------
393 # Some data cut for brevity....
394
395 Status for ./gnupg-1.0.7.ebuild
396 * Testing for malformed headers : passed
397 - (W) Has illegal or suspect headers:
398 |Suspect copyright year: # Copyright 1999-2000 Gentoo Technologies, Inc.
399 * Testing for occurence of deprecated try : passed
400 * Testing for superfluous A=${P}.tar.gz : passed
401 * Testing for empty DEPEND : passed
402 * Testing for empty HOMEPAGE : passed
403 * Testing for empty DESCRIPTION : passed
404 * Testing for presence of env vars : passed
405 - (W) Missing SLOT=
406 * Testing for sane USE flag usage : passed
407
408 -------------------------------------------------------------------------------
409 Summary for all 1 ebuild(s) checked # errors/warns
410 -------------------------------------------------------------------------------
411 Testing for illegal space characters, weird backslash formatting : 0 / 0
412 Testing for malformed headers : 0 / 1
413 Testing for occurence of deprecated try : 0 / 0
414 Testing for superfluous A=${P}.tar.gz : 0 / 0
415 Testing for empty DEPEND : 0 / 0
416 Testing for empty HOMEPAGE : 0 / 0
417 Testing for empty DESCRIPTION : 0 / 0
418 Testing for presence of env vars : 0 / 1
419 Testing for sane USE flag usage : 0 / 0
420
421 Total number of ebuilds with errors : 0 (0%)
422 Total number of ebuilds with warnings : 1 (100%)
423 </pre>
424
425 <p>
426 Now I can see that the year in the ebuild is probably wrong, and that it is
427 missing the SLOT variable. Fixing those eliminates all warnings.
428 </p>
429
430 </body>
431 </section>
432 </chapter>
433
434 <chapter>
435 <title>epm</title>
436 <section>
437 <title>Introduction</title>
438 <body>
439
440 <p>
441 <c>epm</c> is a package managing tool that clones Red Hat rpm commands. As it
442 stands now, it does not offer all of the features of rpm, but it offers some of
443 the more powerful rpm query options.
444 </p>
445
446 <p>
447 It also handles removing packages, which is not covered here. Use <c>epm
448 --help</c> to learn more about deleting packages with <c>epm</c>.
449 </p>
450
451 </body>
452 </section>
453 <section>
454
455 <title>Querying Packages with epm</title>
456 <body>
457
458 <p>
459 <c>epm</c> functions with essentially the same command line functions as Red
460 Hat's rpm. <c>epm -qa</c> lists all packages installed. <c>epm -ql</c> lists all
461 the files from a specific ebuild.
462 </p>
463
464 <pre>
465 # <i>epm -ql ethereal</i>
466 /usr/lib/ethereal/plugins/0.8.20/gryphon.so
467 /usr/lib/ethereal/plugins/0.8.20/gryphon.la
468 /usr/lib/ethereal/plugins/0.8.20/gryphon.a
469 /usr/lib/ethereal/plugins/0.8.20/mgcp.so
470 /usr/lib/ethereal/plugins/0.8.20/mgcp.la
471 /usr/lib/ethereal/plugins/0.8.20/mgcp.a
472 /usr/lib/ethereal/plugins/0.8.20/cosnaming.so
473 /usr/lib/ethereal/plugins/0.8.20/cosnaming.la
474 /usr/lib/ethereal/plugins/0.8.20/cosnaming.a
475 /usr/lib/ethereal/plugins/0.8.20/coseventcomm.so
476 /usr/lib/ethereal/plugins/0.8.20/coseventcomm.la
477 /usr/lib/ethereal/plugins/0.8.20/coseventcomm.a
478 /usr/bin/ethereal
479 /usr/bin/editcap
480 /usr/bin/mergecap
481 /usr/bin/tethereal
482 /usr/bin/text2pcap
483 /usr/bin/idl2eth
484 /usr/share/man/man1/idl2eth.1.gz
485 /usr/share/man/man1/tethereal.1.gz
486 /usr/share/man/man1/text2pcap.1.gz
487 /usr/share/man/man1/editcap.1.gz
488 /usr/share/man/man1/ethereal.1.gz
489 /usr/share/man/man1/mergecap.1.gz
490 /usr/share/doc/ethereal-0.8.20/AUTHORS.gz
491 /usr/share/doc/ethereal-0.8.20/COPYING.gz
492 /usr/share/doc/ethereal-0.8.20/NEWS.gz
493 /usr/share/doc/ethereal-0.8.20/ChangeLog.gz
494 /usr/share/doc/ethereal-0.8.20/README.gz
495 /usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz
496 /usr/share/doc/ethereal-0.8.20/TODO.gz
497 /usr/share/doc/ethereal-0.8.20/README.aix.gz
498 /usr/share/doc/ethereal-0.8.20/README.bsd.gz
499 /usr/share/doc/ethereal-0.8.20/README.hpux.gz
500 /usr/share/doc/ethereal-0.8.20/README.irix.gz
501 /usr/share/doc/ethereal-0.8.20/README.linux.gz
502 /usr/share/doc/ethereal-0.8.20/README.tru64.gz
503 /usr/share/doc/ethereal-0.8.20/README.win32.gz
504 /usr/share/doc/ethereal-0.8.20/README.vmware.gz
505 /etc/ethereal/manuf
506 </pre>
507
508 <p>
509 <c>epm</c> offers a few advanced query options that are not present in
510 <c>qpkg</c> at the time of this writing. For instance, it can query for just
511 configuration files or just documentation files.
512 </p>
513
514 <pre>
515 # <i>epm -qc ethereal</i>
516 /etc/ethereal/manuf
517
518 # <i>epm -qd ethereal</i>
519 /usr/share/man/man1/idl2eth.1.gz
520 /usr/share/man/man1/tethereal.1.gz
521 /usr/share/man/man1/text2pcap.1.gz
522 /usr/share/man/man1/editcap.1.gz
523 /usr/share/man/man1/ethereal.1.gz
524 /usr/share/man/man1/mergecap.1.gz
525 /usr/share/doc/ethereal-0.8.20/AUTHORS.gz
526 /usr/share/doc/ethereal-0.8.20/COPYING.gz
527 /usr/share/doc/ethereal-0.8.20/NEWS.gz
528 /usr/share/doc/ethereal-0.8.20/ChangeLog.gz
529 /usr/share/doc/ethereal-0.8.20/README.gz
530 /usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz
531 /usr/share/doc/ethereal-0.8.20/TODO.gz
532 /usr/share/doc/ethereal-0.8.20/README.aix.gz
533 /usr/share/doc/ethereal-0.8.20/README.bsd.gz
534 /usr/share/doc/ethereal-0.8.20/README.hpux.gz
535 /usr/share/doc/ethereal-0.8.20/README.irix.gz
536 /usr/share/doc/ethereal-0.8.20/README.linux.gz
537 /usr/share/doc/ethereal-0.8.20/README.tru64.gz
538 /usr/share/doc/ethereal-0.8.20/README.win32.gz
539 /usr/share/doc/ethereal-0.8.20/README.vmware.gz
540 </pre>
541
542 <note>
543 <c>epm --help</c> lists the options that epm <e>will eventually</e> support.
544 Note, however, that options prefixed with asterisks (*) are not yet implemented.
545 </note>
546
547 </body>
548 </section>
549 </chapter>
550
551 <chapter>
552 <title>Others</title>
553 <section>
554 <title>etc-update</title>
555 <body>
556 <!--
557 - Feel free to add more to this. It probably deserves its own chapter, but I don't
558 - use it, so I can't really write much about it.
559 -->
560
561 <p>
562 <c>etc-update</c> provides a convenient alternative to updating configuration
563 files by hand. After running an emerge that changes configuration files, you
564 can run etc-update to step you through the process of updating all impacted
565 configuration files.
566 </p>
567
568 <p>
569 It is driven by a menu-based interface and includes the ability to view and
570 merge in config files before deciding what to do.
571 </p>
572
573 </body>
574 </section>
575
576 <section>
577 <title>gentool</title>
578 <body>
579
580 <p>
581 gentool is a collective name for several small scripts that analyze ebuild
582 statistics.
583 For instance, gentool-total-coverage prints a list of email addresses and the
584 number of ebuilds each has in the portage tree.
585 </p>
586
587 </body>
588 </section>
589
590 <section>
591 <title>pkg-size</title>
592 <body>
593
594 <p>
595 <c>pkg-size</c> prints the size of the installed files in a given package.
596 </p>
597
598 <pre>
599 # <i>pkg-size nmap</i>
600 net-analyzer/nmap-2.54_beta24-r1 897024 (876KB)
601 </pre>
602
603 </body>
604 </section>
605
606 <section>
607 <title>mkebuild</title>
608 <body>
609
610 <p>
611 <c>mkebuild</c> simplifies the process of creating a new ebuild by automating as
612 much of the process as possible. Running <c>mkebuild [filename]</c> will create
613 an ebuild for that file. the file should be an archive of some kind. As it
614 works, it will provide feedback about changes you may need to make.
615 </p>
616
617 </body>
618 </section>
619
620 <section>
621 <title>emerge-webrsync</title>
622 <body>
623 <!-- Can't find any documentation on this anywhere... not even a comment in the
624 code. -->
625
626 <p>
627 Downloads the daily snapshot over HTTP with wget, and (optionally) syncs with
628 portage.
629 </p>
630
631 </body>
632 </section>
633 </chapter>
634 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20