/[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.9 - (show annotations) (download) (as text)
Fri Mar 26 12:47:10 2004 UTC (10 years, 3 months ago) by cam
Branch: MAIN
Changes since 1.8: +318 -306 lines
File MIME type: application/xml
replacing chown user.group by chown user:group (posix is our friend)

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

  ViewVC Help
Powered by ViewVC 1.1.20