/[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.6 - (show annotations) (download) (as text)
Sat Nov 15 00:35:18 2003 UTC (10 years, 7 months ago) by neysx
Branch: MAIN
Changes since 1.5: +1 -0 lines
File MIME type: application/xml
Added $Header$ cvs tag -- NO CONTENT CHANGE

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

  ViewVC Help
Powered by ViewVC 1.1.20