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

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/gentoolkit.xml,v 1.7 2003/12/01 12:06:21 erwin Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link = "/doc/en/gentoolkit.xml">
6 <title>Gentoolkit</title>
7 <author title="Author"><mail link="mbutcher@aleph-null.tv">
8 Matt Butcher</mail>
9 </author>
10
11 <author title="Editor"><!-- zhen@gentoo.org -->
12 John P. Davis
13 </author>
14 <author title="Editor">
15 <mail link="erwin@gentoo.org">Erwin</mail>
16 </author>
17 <!-- 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 <version>1.2</version>
26 <date>December 1, 2003</date>
27
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 and are included in the package <path>app-portage/gentoolkit</path>.
39 </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 hebron portage # <i>qpkg -l app-portage/gentoolkit
134 app-portage/gentoolkit-0.1.14-r1 *
135 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 app-portage/gentoolkit
202 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 <c>epm --help</c> lists the options that epm <e>will eventually</e> support. Note,
491 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