/[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.6 - (hide annotations) (download) (as text)
Sat Nov 15 00:35:18 2003 UTC (10 years, 11 months ago) by neysx
Branch: MAIN
Changes since 1.5: +1 -0 lines
File MIME type: application/xml
Added $Header$ cvs tag -- NO CONTENT CHANGE

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

  ViewVC Help
Powered by ViewVC 1.1.20