/[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.5 - (hide annotations) (download) (as text)
Sat Oct 25 08:50:41 2003 UTC (10 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.4: +3 -1 lines
File MIME type: application/xml
ZhEN asked to have his e-mail address removed from all docs

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

  ViewVC Help
Powered by ViewVC 1.1.20