<?xml version='1.0'?> <!DOCTYPE guide SYSTEM "../dtd/guide.dtd"> <guide> <title>Gentoolkit</title> <author title="Author"><mail link="mbutcher@aleph-null.tv"> Matt Butcher</mail> </author> <!-- Licensed under GFDL --> <abstract> Gentoolkit is a suite of tools to ease the administration of a Gentoo system. This document covers the basics of some of the tools present in Gentoolkit. </abstract> <version>1.0</version> <date>16 July 2002</date> <chapter> <title>Introduction</title> <section> <title>What is Gentoolkit?</title> <body> <p>Gentoo is a unique distribution, and presents some complexities that simply don't exist for other distributions. As Gentoo developers and contributors discovered some of these complexities, they also wrote tools to help users and administrators work around them. Many of these tools have been contributed to the Gentoo project, and are included in the package <path>app-admin/gentoolkit</path>. </p> <p>Gentoolkit contains a whole bunch of useful tools to help manage Portage and the ebuild architecture. Most users -- particularly those who update systems often -- will benefit from having gentoolkit installed.</p> </body> </section> <section> <title>Installation</title> <body> <p>Just as with any Gentoo package, installation is just a simple emerge. </p> <pre> emerge app-admin/gentoolkit </pre> <note>Many of the tools in gentoolkit reveal important information about your system or require root permissions. For that reason, some of the programs may only be executed (or only function properly) if run by a user with root permissions.</note> </body> </section> <section> <title>Finding Documentation</title> <body> <p> At the time of this writing, not all of the programs in gentoolkit are well documented. Some have man pages, but not all. Any documentation that a program might have (other than man pages) is stored in <path>/usr/doc/gentoolkit-[version]/[programname]/</path>. </p> </body> </section> </chapter> <chapter> <title>Querying Package Data with qpkg</title> <section> <title>Introduction</title> <body> <p><c>qpkg</c> is flexible tool for determining information about ebuilds, whether installed or not. It can provide information about what files belong to which ebuilds, whether multiple versions of the same package are installed, and what a particular ebuild does. </p> <p>Calling <c>qpkg</c> with no arguments prints a list of all ebuilds, with asterisks (*) next to the packages that are installed on the system. </p> <note>By default, <c>qpkg</c> prints output in color. To turn this off on the command line, use the <c>--no-color</c> or <c>-nc</c> flag.</note> </body> </section> <section> <title>Querying Package Information</title> <body> <p>One of the most common uses for <c>qpkg</c> is determining what a given package is. For instance, while looking through <path>net-misc</path>, I saw a package called <path>neon</path>. Having no idea what it was, I ran qpkg. </p> <pre> hebron root # qpkg -i net-misc/neon net-misc/neon-0.15.3-r1 HTTP and WebDAV client library [ http://www.webdav.org/neon ] net-misc/neon-0.18.5 HTTP and WebDAV client library [ http://www.webdav.org/neon ] net-misc/neon-0.19.2 HTTP and WebDAV client library [ http://www.webdav.org/neon ] net-misc/neon-0.19.2-r1 HTTP and WebDAV client library [ http://www.webdav.org/neon ] net-misc/neon-0.21.1 HTTP and WebDAV client library [ http://www.webdav.org/neon ] </pre> <p> <c>qpkg</c> read through the ebuild files for the five <path>net-misc/neon</path> ebuilds and printed out the information stored in DESCRIPTION and HOMEPAGE. </p> </body> </section> <section> <title>Listing Files Belonging to an Ebuild</title> <body> <p> <c>qpkg</c> can also list the files that belong to an installed ebuild. I Know that gentoolkit installed several tools, but I don't know what they all are. To find out, I can use the <c>-l</c> option with <c>qpkg</c> </p> <pre> hebron portage # qpkg -l app-admin/gentoolkit app-admin/gentoolkit-0.1.14-r1 * CONTENTS: /usr /usr/share /usr/share/gentoolkit /usr/share/gentoolkit/histogram.awk /usr/share/doc /usr/share/doc/gentoolkit-0.1.14-r1 /usr/share/doc/gentoolkit-0.1.14-r1/gentool /usr/share/doc/gentoolkit-0.1.14-r1/gentool/ChangeLog.gz /usr/share/doc/gentoolkit-0.1.14-r1/lintool /usr/share/doc/gentoolkit-0.1.14-r1/lintool/checklist-for-ebuilds.gz /usr/share/doc/gentoolkit-0.1.14-r1/lintool/ChangeLog.gz /usr/share/doc/gentoolkit-0.1.14-r1/etc-update /usr/share/doc/gentoolkit-0.1.14-r1/etc-update/ChangeLog.gz /usr/share/man /usr/share/man/man1 /usr/share/man/man1/qpkg.1.gz /usr/share/man/man1/useflag.1.gz /usr/share/man/man1/lintool.1.gz /usr/share/man/man1/etc-update.1.gz /usr/bin /usr/bin/gentool-bump-revision /usr/bin/gentool-total-coverage /usr/bin/gentool-author-coverage /usr/bin/gentool-package-count /usr/bin/qpkg /usr/bin/pkg-size /usr/bin/useflag /usr/bin/lintool /usr/sbin /usr/sbin/pkg-clean /usr/sbin/mkebuild /usr/sbin/emerge-webrsync /usr/sbin/epm /usr/sbin/etc-update /etc /etc/etc-update.conf </pre> </body> </section> <section> <title>Finding the Package from Whence a File Came</title> <body> <p> To find the package that a file came from, use the <c>-f</c> or <c>--find-file</c> flag. </p> <pre> hebron portage # qpkg -f /usr/bin/pp net-www/mozilla * </pre> </body> </section> <section> <title>Listing Duplicate Packages</title> <body> <p> Sometimes multiple versions of the same package may exist. <c>qpkg --dup</c> will print a list of duplicate packages. The existence of a duplicate package, though, may not indicate that the older version may be removed. They may fill different slots. To look for duplicates in the same slot, use <c>qpkg --dups --slot</c>. I just updated KDE from 3.0 to 3.0.2, so I have some duplicates in the same slot. </p> <pre> hebron portage # qpkg --dups --slot app-admin/gentoolkit kde-base/kdeaddons kde-base/kdeadmin kde-base/kdeartwork kde-base/kdebase kde-base/kdegames kde-base/kdelibs kde-base/kdemultimedia kde-base/kdenetwork kde-base/kdetoys kde-base/kdeutils media-libs/freetype x11-libs/qt </pre> </body> </section> <section> <title>Verifying Package Integrity</title> <body> <p> Sometimes it is useful to check a package's integrity to know that files have not been replaced since they were installed. <c>qpkg</c> can verify md5 sums as well as install times to indicate whether or not files for the package might have been corrupted, replaced, or removed. </p> <p>To check both mtimes and md5 sums, use the <c>-c</c> flag.</p> <pre> hebron portage # qpkg gnupg -c -v app-crypt/gnupg-1.0.6 * /usr/lib/gnupg/rndunix !md5! !mtime! /usr/lib/gnupg/rndegd !md5! !mtime! /usr/lib/gnupg/tiger !md5! !mtime! /usr/bin/gpg !md5! !mtime! /usr/bin/gpgv !md5! !mtime! /usr/share/gnupg/options.skel !md5! !mtime! /usr/share/gnupg/FAQ !md5! !mtime! /usr/share/gnupg/faq.html !md5! !mtime! /usr/share/locale/da/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/de/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/eo/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/et/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/fr/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/id/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/it/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/ja/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/nl/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/pl/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/pt_BR/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/sv/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/locale/tr/LC_MESSAGES/gnupg.mo !md5! !mtime! /usr/share/info/gpgv.info.gz !md5! !mtime! /usr/share/man/man1/gpg.1.gz !md5! !mtime! /usr/share/man/man1/gpgv.1.gz !md5! !mtime! 24/92 app-crypt/gnupg-1.0.7 * 0/101 </pre> <p> As you can see, I have more than one version of GnuPG installed. <c>qpkg</c> reports that many of the files from the older version have been changed since I installed it. Those packages were most likely modified when I updated from <path>gnupg-1.0.6</path> to <path>gnupg-1.0.7</path>. Note that the last two lines indicate that 0 of 101 files from <path>gnupg-1.0.7</path> have been changed since I installed. That is good. If any of them had been changed, I would be worried. </p> </body> </section> <section> <title>But Wait... There's More</title> <body> <p> <c>qpkg</c> can be used for other querying tasks that I will not go over here. There is a very complete manpage for <c>qpkg</c>. Consult that for more information. </p> </body> </section> </chapter> <chapter> <title>lintool</title> <section> <title>Introduction</title> <body> <p> <c>lintool</c> is a program for checking ebuild scripts for conformance to standards and requirements. It is important for ebuild developers to use <c>lintool</c> to ensure that they are doing things correctly and not requiring the core team to do more than they already have to in order to include the ebuild in the Gentoo repository. </p> </body> </section> <section> <title>Use</title> <body> <p> Running <c>lintool</c> will produce a nicely formatted list of checks and results that it performs. </p> <pre> hebron portage # lintool app-crypt/gnupg/gnupg-1.0.7.ebuild app-crypt/gnupg/gnupg-1.0.7.ebuild : Not OK ------------------------------------------------------------------------------- Summary for all 1 ebuild(s) checked # errors/warns ------------------------------------------------------------------------------- Testing for illegal space characters, weird backslash formatting : 0 / 0 Testing for malformed headers : 0 / 1 Testing for occurence of deprecated try : 0 / 0 Testing for superfluous A=${P}.tar.gz : 0 / 0 Testing for empty DEPEND : 0 / 0 Testing for empty HOMEPAGE : 0 / 0 Testing for empty DESCRIPTION : 0 / 0 Testing for presence of env vars : 1 / 1 Testing for sane USE flag usage : 0 / 0 Total number of ebuilds with errors : 1 (100%) Total number of ebuilds with warnings : 1 (100%) </pre> <p> The first line summarizes whether the ebuild is okay or not. In the case of gnupg-1.0.7.ebuild, it's not. Reading through the list of checks, we can see that it got a warning for malformed headers and an error for presence of env vars. </p> <p> Looking at the ebuild, I see that it is missing a couple of required env vars (LICENSE and RDEPEND). Adding those fixes the error. But there are still two warnings -- one for malformed headers and one for env vars. To help me find those, I can run <c>lintool</c> again with <c>--show-details</c> </p> <pre> hebron gnupg # lintool --show-details ./gnupg-1.0.7.ebuild ------------------------------------------------------------------------------- # Some data cut for brevity.... Status for ./gnupg-1.0.7.ebuild * Testing for malformed headers : passed - (W) Has illegal or suspect headers: |Suspect copyright year: # Copyright 1999-2000 Gentoo Technologies, Inc. * Testing for occurence of deprecated try : passed * Testing for superfluous A=${P}.tar.gz : passed * Testing for empty DEPEND : passed * Testing for empty HOMEPAGE : passed * Testing for empty DESCRIPTION : passed * Testing for presence of env vars : passed - (W) Missing SLOT= * Testing for sane USE flag usage : passed ------------------------------------------------------------------------------- Summary for all 1 ebuild(s) checked # errors/warns ------------------------------------------------------------------------------- Testing for illegal space characters, weird backslash formatting : 0 / 0 Testing for malformed headers : 0 / 1 Testing for occurence of deprecated try : 0 / 0 Testing for superfluous A=${P}.tar.gz : 0 / 0 Testing for empty DEPEND : 0 / 0 Testing for empty HOMEPAGE : 0 / 0 Testing for empty DESCRIPTION : 0 / 0 Testing for presence of env vars : 0 / 1 Testing for sane USE flag usage : 0 / 0 Total number of ebuilds with errors : 0 (0%) Total number of ebuilds with warnings : 1 (100%) </pre> <p>Now I can see that the year in the ebuild is probably wrong, and that it is missing the SLOT variable. Fixing those eliminates all warnings.</p> </body> </section> </chapter> <chapter> <title>useflag</title> <section> <title>Introduction</title> <body> <p><c>useflag</c> is a tool for handling USE variables. It can display information about USE flags, as well as manage adding, deleting, and locking them. </p> </body> </section> <section> <title>Getting Information about USE Variables.</title> <body> <p> Every USE variable has a text description in <path>/usr/portage/profiles/use.desc</path>. <c>useflag</c> can be used to query the description for a particular USE var. </p> <pre> hebron portage # useflag -i xml xml - Check/Support flag for XML library (version 1) </pre> </body> </section> <section> <title>Managing USE Flags</title> <body> <p>To view the current list of USE flags, use <c>useflag -s</c> </p> <pre> hebron etc # useflag -s +zeo -ruby +voodoo3 </pre> <p>To delete a USE flag, use <c>useflag -d</c> </p> <pre> hebron etc # useflag -d -ruby hebron etc # useflag -s +zeo +voodoo3 </pre> <p>To add a USE flag, use <c>useflag -a</c> </p> <pre> hebron etc # useflag -a +ruby hebron etc # useflag -s +zeo +voodoo3 +ruby </pre> <impo> If /etc/make.conf does not have USE defined, this tool will not function correctly. </impo> <p>For more information, consult the man page.</p> </body> </section> </chapter> <chapter> <title>epm</title> <section> <title>Introduction</title> <body> <p> <c>epm</c> is a package managing tool that clones Red Hat rpm commands. As it stands now, it does not offer all of the features of rpm, but it offers some of the more powerful rpm query options. </p> <p> It also handles removing packages, which is not covered here. Use <c>epm --help</c> to learn more about deleting packages with <c>epm</c>. </p> </body> </section> <section> <title>Querying Packages with epm</title> <body> <p> <c>epm</c> functions with essentially the same command line functions as Red Hat's rpm. <c>epm -qa</c> lists all packages installed. <c>epm -ql</c> lists all the files from a specific ebuild. </p> <pre> hebron etc # epm -ql ethereal /usr/lib/ethereal/plugins/0.8.20/gryphon.so /usr/lib/ethereal/plugins/0.8.20/gryphon.la /usr/lib/ethereal/plugins/0.8.20/gryphon.a /usr/lib/ethereal/plugins/0.8.20/mgcp.so /usr/lib/ethereal/plugins/0.8.20/mgcp.la /usr/lib/ethereal/plugins/0.8.20/mgcp.a /usr/lib/ethereal/plugins/0.8.20/cosnaming.so /usr/lib/ethereal/plugins/0.8.20/cosnaming.la /usr/lib/ethereal/plugins/0.8.20/cosnaming.a /usr/lib/ethereal/plugins/0.8.20/coseventcomm.so /usr/lib/ethereal/plugins/0.8.20/coseventcomm.la /usr/lib/ethereal/plugins/0.8.20/coseventcomm.a /usr/bin/ethereal /usr/bin/editcap /usr/bin/mergecap /usr/bin/tethereal /usr/bin/text2pcap /usr/bin/idl2eth /usr/share/man/man1/idl2eth.1.gz /usr/share/man/man1/tethereal.1.gz /usr/share/man/man1/text2pcap.1.gz /usr/share/man/man1/editcap.1.gz /usr/share/man/man1/ethereal.1.gz /usr/share/man/man1/mergecap.1.gz /usr/share/doc/ethereal-0.8.20/AUTHORS.gz /usr/share/doc/ethereal-0.8.20/COPYING.gz /usr/share/doc/ethereal-0.8.20/NEWS.gz /usr/share/doc/ethereal-0.8.20/ChangeLog.gz /usr/share/doc/ethereal-0.8.20/README.gz /usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz /usr/share/doc/ethereal-0.8.20/TODO.gz /usr/share/doc/ethereal-0.8.20/README.aix.gz /usr/share/doc/ethereal-0.8.20/README.bsd.gz /usr/share/doc/ethereal-0.8.20/README.hpux.gz /usr/share/doc/ethereal-0.8.20/README.irix.gz /usr/share/doc/ethereal-0.8.20/README.linux.gz /usr/share/doc/ethereal-0.8.20/README.tru64.gz /usr/share/doc/ethereal-0.8.20/README.win32.gz /usr/share/doc/ethereal-0.8.20/README.vmware.gz /etc/ethereal/manuf </pre> <p> <c>epm</c> offers a few advanced query options that are not present in <c>qpkg</c> at the time of this writing. For instance, it can query for just configuration files or just documentation files. </p> <pre> hebron etc # epm -qc ethereal /etc/ethereal/manuf hebron etc # epm -qd ethereal /usr/share/man/man1/idl2eth.1.gz /usr/share/man/man1/tethereal.1.gz /usr/share/man/man1/text2pcap.1.gz /usr/share/man/man1/editcap.1.gz /usr/share/man/man1/ethereal.1.gz /usr/share/man/man1/mergecap.1.gz /usr/share/doc/ethereal-0.8.20/AUTHORS.gz /usr/share/doc/ethereal-0.8.20/COPYING.gz /usr/share/doc/ethereal-0.8.20/NEWS.gz /usr/share/doc/ethereal-0.8.20/ChangeLog.gz /usr/share/doc/ethereal-0.8.20/README.gz /usr/share/doc/ethereal-0.8.20/INSTALL.configure.gz /usr/share/doc/ethereal-0.8.20/TODO.gz /usr/share/doc/ethereal-0.8.20/README.aix.gz /usr/share/doc/ethereal-0.8.20/README.bsd.gz /usr/share/doc/ethereal-0.8.20/README.hpux.gz /usr/share/doc/ethereal-0.8.20/README.irix.gz /usr/share/doc/ethereal-0.8.20/README.linux.gz /usr/share/doc/ethereal-0.8.20/README.tru64.gz /usr/share/doc/ethereal-0.8.20/README.win32.gz /usr/share/doc/ethereal-0.8.20/README.vmware.gz </pre> <note> <c>emp --help</c> lists the options that epm <e>will eventually</e> support. Note, however, that options prefixed with asterisks (*) are not yet implemented. </note> </body> </section> </chapter> <chapter> <title>Others</title> <section> <title>etc-update</title> <body> <!-- - Feel free to add more to this. It probably deserves its own chapter, but I don't - use it, so I can't really write much about it. --> <p> <c>etc-update</c> provides a convenient alternative to updating configuration files by hand. After running an emerge that changes configuration files, you can run etc-update to step you through the process of updating all impacted configuration files. </p> <p> It is driven by a menu-based interface and includes the ability to view and merge in config files before deciding what to do. </p> </body> </section> <section> <title>gentool</title> <body> <p>gentool is a collective name for several small scripts that analyze ebuild statistics. For instance, gentool-total-coverage prints a list of email addresses and the number of ebuilds each has in the portage tree. </p> </body> </section> <section> <title>pkg-size</title> <body> <p><c>pkg-size</c> prints the size of the installed files in a given package. </p> <pre> hebron portage # pkg-size nmap net-analyzer/nmap-2.54_beta24-r1 897024 (876KB) </pre> </body> </section> <section> <title>mkebuild</title> <body> <p><c>mkebuild</c> simplifies the process of creating a new ebuild by automating as much of the process as possible. Running <c>mkebuild [filename]</c> will create an ebuild for that file. the file should be an archive of some kind. As it works, it will provide feedback about changes you may need to make. </p> </body> </section> <section> <title>emerge-webrsync</title> <body> <!-- Can't find any documentation on this anywhere... not even a comment in the code. --> <p>Downloads the daily snapshot over HTTP with wget, and (optionally) syncs with portage. </p> </body> </section> </chapter> </guide>
Thank you VERY much for this. Sorry for the delay in posting, but there has been a lot of changes in the doc team. Thanks again, and hope to see more from you soon. See you in #gentoo-doc maybe? Thanks again, //ZhEN
This is in CVS, and it is current on the website. //ZhEN
