/[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.3 - (hide annotations) (download) (as text)
Mon Nov 18 14:40:50 2002 UTC (11 years, 9 months ago) by zhen
Branch: MAIN
Changes since 1.2: +1 -0 lines
File MIME type: application/xml
changed encoding to UTF-8

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

  ViewVC Help
Powered by ViewVC 1.1.20