/[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.2 - (hide annotations) (download) (as text)
Fri Nov 15 18:39:34 2002 UTC (12 years, 1 month ago) by zhen
Branch: MAIN
Changes since 1.1: +1 -1 lines
File MIME type: application/xml
changed all of the <guide link> tags so that they are current

1 drobbins 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
2     <?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
3    
4 zhen 1.2 <guide link = "/doc/en/gentoolkit.xml">
5 drobbins 1.1 <title>Gentoolkit</title>
6     <author title="Author"><mail link="mbutcher@aleph-null.tv">
7     Matt Butcher</mail>
8     </author>
9    
10     <author title="Editor"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
11     <!-- Licensed under GFDL -->
12    
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>
20     <date>25 September 2002</date>
21    
22     <chapter>
23     <title>Introduction</title>
24     <section>
25     <title>What is Gentoolkit?</title>
26     <body>
27     <p>Gentoo is a unique distribution, and presents some complexities that
28     simply don't exist for other distributions. As Gentoo developers
29     and contributors discovered some of these complexities, they also
30     wrote tools to help users and administrators work around them.
31     Many of these tools have been contributed to the Gentoo project,
32     and are included in the package <path>app-admin/gentoolkit</path>.
33     </p>
34    
35     <p>Gentoolkit contains a whole bunch of useful tools to help manage
36     Portage and the ebuild architecture. Most users -- particularly
37     those who update systems often -- will benefit from having
38     gentoolkit installed.</p>
39     </body>
40     </section>
41     <section>
42     <title>Installation</title>
43     <body>
44     <p>Just as with any Gentoo package, installation is just a simple
45     emerge.
46     </p>
47    
48     <pre>
49     <i>emerge gentoolkit </i>
50     </pre>
51     <note>Many of the tools in gentoolkit reveal important information
52     about your system or require root permissions. For that reason,
53     some of the programs may only be executed (or only function
54     properly) if run by a user with root permissions.</note>
55     </body>
56     </section>
57     <section>
58     <title>Finding Documentation</title>
59     <body>
60    
61     <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
65     <path>/usr/doc/gentoolkit-[version]/[program-name]/</path>.
66     </p>
67     </body>
68     </section>
69     </chapter>
70     <chapter>
71     <title>Querying Package Data with qpkg</title>
72     <section>
73    
74     <title>Introduction</title>
75     <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    
87     </body>
88     </section>
89     <section>
90     <title>Querying Package Information</title>
91     <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    
97     <pre>
98     hebron root # <i>qpkg -i net-misc/neon
99     net-misc/neon-0.15.3-r1
100     HTTP and WebDAV client library [ http://www.webdav.org/neon ]
101     net-misc/neon-0.18.5
102     HTTP and WebDAV client library [ http://www.webdav.org/neon ]
103     net-misc/neon-0.19.2
104     HTTP and WebDAV client library [ http://www.webdav.org/neon ]
105     net-misc/neon-0.19.2-r1
106     HTTP and WebDAV client library [ http://www.webdav.org/neon ]
107     net-misc/neon-0.21.1
108     HTTP and WebDAV client library [ http://www.webdav.org/neon ] </i>
109     </pre>
110     <p>
111     <c>qpkg</c> read through the ebuild files for the five <path>net-misc/neon</path>
112     ebuilds and printed out the information stored in DESCRIPTION and HOMEPAGE.
113     </p>
114     </body>
115    
116     </section>
117     <section>
118     <title>Listing Files Belonging to an Ebuild</title>
119     <body>
120     <p>
121     <c>qpkg</c> can also list the files that belong to an installed ebuild. I
122     Know that gentoolkit installed several tools, but I don't know what they
123     all are. To find out, I can do a <c>qpkg -l</c>
124    
125     </p>
126     <pre>
127     hebron portage # <i>qpkg -l app-admin/gentoolkit
128     app-admin/gentoolkit-0.1.14-r1 *
129     CONTENTS:
130     /usr
131     /usr/share
132     /usr/share/gentoolkit
133     /usr/share/gentoolkit/histogram.awk
134     /usr/share/doc
135     /usr/share/doc/gentoolkit-0.1.14-r1
136     /usr/share/doc/gentoolkit-0.1.14-r1/gentool
137     /usr/share/doc/gentoolkit-0.1.14-r1/gentool/ChangeLog.gz
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>
165     </body>
166     </section>
167     <section>
168     <title>Finding the Package from Where a File Came</title>
169     <body>
170    
171     <p>
172     To find the package that a file came from, use the <c>-f</c>
173     or <c>--find-file</c> flag.
174     </p>
175     <pre>
176     hebron portage # <i>qpkg -f net-www/mozilla * </i>
177     </pre>
178    
179     </body>
180     </section>
181     <section>
182     <title>Listing Duplicate Packages</title>
183     <body>
184     <p>
185     Sometimes multiple versions of the same package may exist. <c>qpkg --dup</c>
186    
187     will print a list of duplicate packages. The existence of a duplicate package
188     though may not indicate that the older version may be removed. They may fill
189     different slots. To look for duplicates in the same slot, use
190     <c>qpkg --dups --slot</c>. I just updated KDE from 3.0 to 3.0.2, so I have some
191     duplicates in the same slot.
192     </p>
193     <pre>
194     hebron portage # <i>qpkg --dups --slot
195     app-admin/gentoolkit
196     kde-base/kdeaddons
197     kde-base/kdeadmin
198     kde-base/kdeartwork
199     kde-base/kdebase
200     kde-base/kdegames
201     kde-base/kdelibs
202     kde-base/kdemultimedia
203     kde-base/kdenetwork
204     kde-base/kdetoys
205     kde-base/kdeutils
206     media-libs/freetype
207     x11-libs/qt </i>
208     </pre>
209     </body>
210     </section>
211     <section>
212     <title>Verifying Package Integrity</title>
213    
214     <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    
224     hebron portage # <i>qpkg gnupg -c -v
225     app-crypt/gnupg-1.0.6 *
226     /usr/lib/gnupg/rndunix !md5! !mtime!
227     /usr/lib/gnupg/rndegd !md5! !mtime!
228     /usr/lib/gnupg/tiger !md5! !mtime!
229     /usr/bin/gpg !md5! !mtime!
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!
250     24/92
251    
252     app-crypt/gnupg-1.0.7 *
253     0/101 </i>
254     </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
260     lines indicate
261     that 0 of 101 files from <path>gnupg-1.0.7</path> have been changed since I
262     installed. That
263     is good. If any of them had been changed, I would be worried.
264     </p>
265    
266     </body>
267     </section>
268     <section>
269     <title>But Wait... There's More</title>
270     <body>
271     <p>
272     <c>qpkg</c> can be used for other querying tasks that I will not go over here. There
273     is a very complete
274     manpage for <c>qpkg</c>. Consult that for more information.
275     </p>
276    
277     </body>
278     </section>
279     </chapter>
280     <chapter>
281     <title>lintool</title>
282     <section>
283     <title>Introduction</title>
284     <body>
285     <p>
286    
287     <c>lintool</c> is a program that checks ebuild scripts for conformance to
288     standards and requirements. It is important for ebuild developers to use <c>lintool</c>
289     to ensure that they are doing things correctly and not requiring the core team
290     to do more than they already have to in order to include the ebuild in the Gentoo
291     repository.
292     </p>
293     </body>
294     </section>
295     <section>
296     <title>Use</title>
297    
298     <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>
304     hebron portage # <i>lintool app-crypt/gnupg/gnupg-1.0.7.ebuild
305     app-crypt/gnupg/gnupg-1.0.7.ebuild : Not OK
306    
307     -------------------------------------------------------------------------------
308     Summary for all 1 ebuild(s) checked # errors/warns
309     -------------------------------------------------------------------------------
310     Testing for illegal space characters, weird backslash formatting : 0 / 0
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    
320     Total number of ebuilds with errors : 1 (100%)
321     Total number of ebuilds with warnings : 1 (100%)
322     </i> </pre>
323     <p>
324     The first line summarizes whether the ebuild is okay or not. In the case of
325     <c>gnupg-1.0.7.ebuild</c>, it's not. Reading through the list of checks, we can see
326     that it got a warning for malformed headers and an error for presence of env
327     vars.
328     </p>
329    
330     <p>
331     Looking at the ebuild, I see that it is missing a couple of required
332     env vars (LICENSE and RDEPEND). Adding those fixes the error. But there are
333     still two warnings -- one for malformed headers and one for env vars. To help
334     me find those, I can run <c>lintool</c> again with <c>--show-details</c>
335     </p>
336     <pre>
337     hebron gnupg # <i>lintool --show-details ./gnupg-1.0.7.ebuild
338    
339     -------------------------------------------------------------------------------
340     # Some data cut for brevity....
341    
342     Status for ./gnupg-1.0.7.ebuild
343     * Testing for malformed headers : passed
344     - (W) Has illegal or suspect headers:
345     |Suspect copyright year: # Copyright 1999-2000 Gentoo Technologies, Inc.
346     * Testing for occurence of deprecated try : passed
347     * Testing for superfluous A=${P}.tar.gz : passed
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    
355     -------------------------------------------------------------------------------
356     Summary for all 1 ebuild(s) checked # errors/warns
357     -------------------------------------------------------------------------------
358     Testing for illegal space characters, weird backslash formatting : 0 / 0
359     Testing for malformed headers : 0 / 1
360     Testing for occurence of deprecated try : 0 / 0
361     Testing for superfluous A=${P}.tar.gz : 0 / 0
362     Testing for empty DEPEND : 0 / 0
363     Testing for empty HOMEPAGE : 0 / 0
364     Testing for empty DESCRIPTION : 0 / 0
365     Testing for presence of env vars : 0 / 1
366     Testing for sane USE flag usage : 0 / 0
367    
368     Total number of ebuilds with errors : 0 (0%)
369     Total number of ebuilds with warnings : 1 (100%)
370     </i> </pre>
371     <p>Now I can see that the year in the ebuild is probably wrong, and that it is
372     missing the SLOT variable. Fixing those eliminates all warnings.</p>
373    
374     </body>
375     </section>
376     </chapter>
377     <chapter>
378    
379     <title>epm</title>
380     <section>
381     <title>Introduction</title>
382     <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    
389     <p>
390     It also handles removing packages, which is not covered here. Use <c>epm --help</c>
391     to learn more about deleting packages with <c>epm</c>.
392     </p>
393     </body>
394     </section>
395     <section>
396    
397     <title>Querying Packages with epm</title>
398     <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    
405     <pre>
406     hebron etc # <i>epm -ql ethereal
407     /usr/lib/ethereal/plugins/0.8.20/gryphon.so
408     /usr/lib/ethereal/plugins/0.8.20/gryphon.la
409     /usr/lib/ethereal/plugins/0.8.20/gryphon.a
410     /usr/lib/ethereal/plugins/0.8.20/mgcp.so
411     /usr/lib/ethereal/plugins/0.8.20/mgcp.la
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>
450     at the
451     time of this writing. For instance, it can query for just configuration files or
452     just documentation
453     files.
454     </p>
455     <pre>
456    
457     hebron etc # <i>epm -qc ethereal
458     /etc/ethereal/manuf
459    
460     hebron 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,
485     however, that
486     options prefixed with asterisks (*) are not yet implemented.
487     </note>
488     </body>
489     </section>
490     </chapter>
491    
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
518     statistics.
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    
532     hebron portage # <i>pkg-size nmap
533     net-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
541     much
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
554     code. -->
555     <p>Downloads the daily snapshot over HTTP with wget, and (optionally) syncs with
556     portage.
557     </p>
558     </body>
559    
560     </section>
561     </chapter>
562     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20