/[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.4 - (show annotations) (download) (as text)
Tue Oct 7 18:41:09 2003 UTC (11 years ago) by swift
Branch: MAIN
Changes since 1.3: +0 -1 lines
File MIME type: application/xml
Fix guide.xsl issues

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

  ViewVC Help
Powered by ViewVC 1.1.20