/[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.8 - (hide annotations) (download) (as text)
Sat Mar 6 17:06:19 2004 UTC (10 years, 6 months ago) by swift
Branch: MAIN
Changes since 1.7: +2 -2 lines
File MIME type: application/xml
#43858, fix typo

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

  ViewVC Help
Powered by ViewVC 1.1.20