GentoolkitMatt Butcher
John P. Davis
Erwin
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.
1.3December 1, 2003IntroductionWhat is Gentoolkit?

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
app-portage/gentoolkit.

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.

Installation

Just as with any Gentoo package, installation is just a simple emerge.

# emerge gentoolkit

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.
Finding Documentation

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
/usr/doc/gentoolkit-[version]/[program-name]/.

Querying Package Data with qpkgIntroduction

qpkg is a 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.

Calling qpkg with no arguments prints a list of all ebuilds, with
asterisks (*) next to the packages that are installed on the system.

By default, qpkg prints output in color. To turn this off on the command
line, use the --no-color or -nc flag.
Querying Package Information

One of the most common uses for qpkg is determining what a given package
is. For instance, while looking through net-misc, I saw a package
called neon. Having no idea what it was, I ran qpkg.

To find the package that a file came from, use the -f or
--find-file flag.

# qpkg -f /usr/lib/mozilla
net-www/mozilla *

Listing Duplicate Packages

Sometimes multiple versions of the same package may exist. qpkg --dup
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
qpkg --dups --slot. I just updated KDE from 3.0 to 3.0.2, so I have some
duplicates in the same slot.

Sometimes it is useful to check a package's integrity to know that files have
not been replaced since they were installed. qpkg 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.

As you can see, I have more than one version of GnuPG installed. qpkg
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
gnupg-1.0.6 to gnupg-1.0.7. Note that the last two
lines indicate that 0 of 101 files from gnupg-1.0.7 have been
changed since I installed. That is good. If any of them had been changed, I
would be worried.

But Wait... There's More

qpkg can be used for other querying tasks that I will not go over here.
There is a very complete manpage for qpkg. Consult that for more
information.

lintoolIntroduction

lintool is a program that checks ebuild scripts for conformance to
standards and requirements. It is important for ebuild developers to use
lintool 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.

Use

Running lintool will produce a nicely formatted list of checks and
results that it performs.

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.

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 lintool again with --show-details

epm --help lists the options that epm will eventually support.
Note, however, that options prefixed with asterisks (*) are not yet implemented.
Othersetc-update

etc-update 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.

It is driven by a menu-based interface and includes the ability to view and
merge in config files before deciding what to do.

gentool

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.

pkg-size

pkg-size prints the size of the installed files in a given package.

# pkg-size nmap
net-analyzer/nmap-2.54_beta24-r1 897024 (876KB)

mkebuild

mkebuild simplifies the process of creating a new ebuild by automating as
much of the process as possible. Running mkebuild [filename] 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.

emerge-webrsync

Downloads the daily snapshot over HTTP with wget, and (optionally) syncs with
portage.