Gentoolkit Matt Butcher John P. Davis Erwin Shyam Mani Xavier Neys 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.4 August 25, 2004 Introduction
What 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.

As of now, there are two versions of gentoolkit: app-portage/gentoolkit and app-portage/gentoolkit-dev. While the former contains administration scripts, the latter contains scripts specific to help development on Gentoo. This document discusses gentoolkit only.

Gentoolkit contains a whole bunch of useful tools to help manage your packages and keep track of what is going on in your system. 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 privilege. For that reason, some of the programs may only be executed (or only function properly) if run by a user with root permission.
Finding Documentation

Any documentation that a program might have (other than man pages) is stored in /usr/doc/gentoolkit-[version]/[program-name]/.

Querying Package Data with qpkg
Introduction

qpkg is a flexible tool for determining information about installed ebuilds. 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. It can also be used to query some information about ebuilds that have not been installed.

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. 

# qpkg -i net-misc/neon
net-misc/neon-0.24.4
        HTTP and WebDAV client library [ http://www.webdav.org/neon ]
net-misc/neon-0.23.8
        HTTP and WebDAV client library [ http://www.webdav.org/neon ]
net-misc/neon-0.24.6
        HTTP and WebDAV client library [ http://www.webdav.org/neon/ ]
net-misc/neon-0.24.5
        HTTP and WebDAV client library [ http://www.webdav.org/neon ]
net-misc/neon-0.24.0
        HTTP and WebDAV client library [ http://www.webdav.org/neon ]
net-misc/neon-0.21.3
        HTTP and WebDAV client library [ http://www.webdav.org/neon ]
net-misc/neon-0.23.9
        HTTP and WebDAV client library [ http://www.webdav.org/neon ]
net-misc/neon-0.24.7
        HTTP and WebDAV client library [ http://www.webdav.org/neon/ ]
net-misc/neon-0.24.2
        HTTP and WebDAV client library [ http://www.webdav.org/neon ]

qpkg read through the ebuild files for the nine net-misc/neon ebuilds and printed out the information stored in DESCRIPTION and HOMEPAGE.

Listing Files Belonging to an Ebuild

qpkg 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 do a qpkg -l. 

# qpkg -l app-portage/gentoolkit
app-portage/gentoolkit-0.2.0_pre8 *
CONTENTS:
/usr
/usr/bin
/usr/bin/euse
/usr/bin/qpkg
/usr/bin/etcat
/usr/bin/revdep-rebuild
/usr/bin/glsa-check
/usr/bin/dep-clean
/usr/bin/equery
/usr/bin/ewhich
/usr/bin/pkg-size
/usr/lib
/usr/lib/gentoolkit
/usr/lib/gentoolkit/pym
/usr/lib/gentoolkit/pym/glsa.py
/usr/lib/gentoolkit/pym/gentoolkit.py
/usr/sbin
/usr/sbin/pkg-clean
/usr/sbin/mkebuild
/usr/share
/usr/share/doc
/usr/share/doc/gentoolkit-0.2.0_pre8
/usr/share/doc/gentoolkit-0.2.0_pre8/NEWS
/usr/share/doc/gentoolkit-0.2.0_pre8/TODO
/usr/share/doc/gentoolkit-0.2.0_pre8/euse
/usr/share/doc/gentoolkit-0.2.0_pre8/euse/TODO
/usr/share/doc/gentoolkit-0.2.0_pre8/euse/README
/usr/share/doc/gentoolkit-0.2.0_pre8/euse/AUTHORS
/usr/share/doc/gentoolkit-0.2.0_pre8/euse/ChangeLog
/usr/share/doc/gentoolkit-0.2.0_pre8/qpkg
/usr/share/doc/gentoolkit-0.2.0_pre8/qpkg/README
/usr/share/doc/gentoolkit-0.2.0_pre8/qpkg/AUTHORS
/usr/share/doc/gentoolkit-0.2.0_pre8/qpkg/ChangeLog
/usr/share/doc/gentoolkit-0.2.0_pre8/etcat
/usr/share/doc/gentoolkit-0.2.0_pre8/etcat/README
/usr/share/doc/gentoolkit-0.2.0_pre8/etcat/AUTHORS
/usr/share/doc/gentoolkit-0.2.0_pre8/revdep-rebuild
/usr/share/doc/gentoolkit-0.2.0_pre8/revdep-rebuild/TODO
/usr/share/doc/gentoolkit-0.2.0_pre8/revdep-rebuild/README
/usr/share/doc/gentoolkit-0.2.0_pre8/revdep-rebuild/AUTHORS
/usr/share/doc/gentoolkit-0.2.0_pre8/README
/usr/share/doc/gentoolkit-0.2.0_pre8/equery
/usr/share/doc/gentoolkit-0.2.0_pre8/equery/README
/usr/share/doc/gentoolkit-0.2.0_pre8/equery/AUTHORS
/usr/share/doc/gentoolkit-0.2.0_pre8/AUTHORS
/usr/share/doc/gentoolkit-0.2.0_pre8/gentoolkit
/usr/share/doc/gentoolkit-0.2.0_pre8/gentoolkit/TODO
/usr/share/doc/gentoolkit-0.2.0_pre8/gentoolkit/README
/usr/share/doc/gentoolkit-0.2.0_pre8/gentoolkit/AUTHORS
/usr/share/doc/gentoolkit-0.2.0_pre8/gentoolkit/ChangeLog
/usr/share/doc/gentoolkit-0.2.0_pre8/ChangeLog
/usr/share/doc/gentoolkit-0.2.0_pre8/COPYING
/usr/share/man
/usr/share/man/man1
/usr/share/man/man1/revdep-rebuild.1.gz
/usr/share/man/man1/mkebuild.1.gz
/usr/share/man/man1/qpkg.1.gz
/usr/share/man/man1/pkg-clean.1.gz
/usr/share/man/man1/etcat.1.gz
/usr/share/man/man1/ewhich.1.gz
/usr/share/man/man1/equery.1.gz
/usr/share/man/man1/euse.1.gz
/usr/share/man/man1/dep-clean.1.gz
/usr/share/man/man1/pkg-size.1.gz
In case you have gentoolkit-dev installed, qpkg will list out files for that as well, i.e. it displays the file list for all installed packages with the name gentoolkit.
Finding the Package That a File Came From

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 --dups 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. 

# qpkg --dups --slot
app-portage/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
Verifying Package Integrity

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 files for the package might have been corrupted, replaced, or removed.

To check both mtimes and md5 sums, use the -c flag. 

# qpkg cdrtools -c -v
app-cdr/cdrtools-2.01_alpha25 *
/etc/default/rscsi.dfl !mtime!
/usr/bin/devdump !md5! !mtime!
/usr/bin/mkisofs !md5! !mtime!
/usr/bin/isovfy !md5! !mtime!
/usr/bin/readcd !md5! !mtime!
/usr/bin/cdda2wav !md5! !mtime!
/usr/bin/cdrecord !md5! !mtime!
/usr/bin/isodump !md5! !mtime!
/usr/bin/isoinfo !md5! !mtime!
/usr/lib/libfile.a !md5! !mtime!
/usr/lib/librscg.a !md5! !mtime!
/usr/lib/libunls.a !md5! !mtime!
/usr/lib/libedc_ecc.a !md5! !mtime!
/usr/lib/libdeflt.a !md5! !mtime!
/usr/lib/libhfs.a !md5! !mtime!
/usr/lib/libscg.a !md5! !mtime!
/usr/lib/libparanoia.a !md5! !mtime!
/usr/lib/libschily.a !md5! !mtime!
/usr/sbin/rscsi !md5! !mtime!
/usr/share/man/man1/cdrecord.1.gz !md5! !mtime!
/usr/share/man/man1/readcd.1.gz !md5! !mtime!
/usr/share/man/man1/cdda2wav.1.gz !md5! !mtime!
/usr/share/man/man8/mkisofs.8.gz !md5! !mtime!
76/150

app-cdr/cdrtools-2.01_alpha37 *
0/122

As you can see, I have more than one version of cdrtools 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 cdrtools-2.01_alpha25 to cdrtools-2.01_alpha37. Note that the last two lines indicate that 0 of 122 files from cdrtools-2.01 _alpha37 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 cover here. There is a very complete man page for qpkg. Please read it for more information.

equery
Introduction

equery is a tool that supports features that qpkg and epm have but has its own set of features that make it really useful. equery --help gives you the full set of options. equery will eventually replace etcat at some point of time.

Not all features listed by equery --help have been implemented yet. Those that have not been, are mentioned clearly.
Finding out Package Sizes

Ever been curious to find out how much space a specific package is occupying? Since a package could have its files over a number of directories, the usual du -hc might not give you the correct figure. Not to worry, here comes equery to the rescue! 

# equery size openoffice-bin
* app-office/openoffice-bin-1.1.2
	   Total Files : 2908
	   Total Size  : 223353.31 KiB

As you can see, equery prints the total space used in kilobytes and also lists the total number of files the package has.

Package-wise list of USE Flags

equery can be used to give us information about what USE flags are being used by a specific package. It tells us what our current USE flags are for a package and what USE flags are available for the package. 

# equery uses ethereal
[ Colour Code : set unset ]
[ Legend    : (U) Col 1 - Current USE flags        ]
[           : (I) Col 2 - Installed With USE flags ]

 U I [ Found these USE variables in : net-analyzer/ethereal-0.10.6 ]
 - - adns  : Adds support for the adns DNS client library
 + + gtk   : Adds support for x11-libs/gtk+ (The GIMP Toolkit)
 - - ipv6  : Adds support for IP version 6
 - - snmp  : Adds support for the Simple Network Management Protocol if available
 + + ssl   : Adds support for Secure Socket Layer connections
 + + gtk2  : Use gtk+-2.0.0 over gtk+-1.2 in cases where a program supports both.
 - - debug : Tells configure and the makefiles to build for debugging. Effects vary across packages,
             but generally it will at least add -g to CFLAGS. Remember to set FEATURES=nostrip too

I have installed ethereal with only the gtk, ssl and gtk2 flags set, but the other USE flags for ethereal are adns, ipv6, snmp and debug. For more information on USE flags, please refer to the USE Flags chapter of the Gentoo Handbook.

Where's the ebuild?

We can also find out which ebuild is being used for a specific package using equery. This is done my using the equery which command which displays the full path to the ebuild. 

# equery which cdrtools
/usr/portage/app-cdr/cdrtools/cdrtools-2.01_alpha37.ebuild
Dependency Graphs

equery is capable of giving us a dependency graph for a specified package. The dependency graph gives a listing of all the packages that have direct and indirect dependencies on the package in question. 

# equery depgraph cdrtools
Displaying dependencies for app-cdr/cdrtools-2.01_alpha37
`-- app-cdr/cdrtools-2.01_alpha37
 `-- sys-libs/glibc-2.3.4.20040808 (virtual/libc)
  `-- sys-kernel/linux-headers-2.4.22 (virtual/os-headers)
   `-- sys-apps/baselayout-1.10.4
    `-- sys-apps/sysvinit-2.85-r1
     `-- sys-apps/gawk-3.1.3-r1
      `-- sys-apps/util-linux-2.12-r4
          `-- sys-apps/sed-4.0.9
	      `-- sys-libs/ncurses-5.4-r4
	          `-- sys-apps/pam-login-3.14
	          `-- sys-libs/pam-0.77-r1
                 `-- sys-libs/cracklib-2.7-r10
               `-- sys-apps/miscfiles-1.3-r1
              `-- app-arch/gzip-1.3.5-r1
              `-- sys-apps/portage-2.0.50-r10

For example, while glibc may be a direct dependency for cdrtools, the linux-headers are an indirect dependency for cdrtools.

euse
Introduction

euse is a tool to see, set and unset USE flags at various places. For more information on USE flags, please refer to the USE Flags. euse -i lists all USE flags.

Reading, Setting and Unsetting USE Flags

The euse --conf command reads the current USE flags set/unset from make.conf. 

#  euse --conf
USE setting in make.conf:
alsa acpi apache2 cups cdr crypt cscope -doc ethereal fbcon gif gimpprint gnome
gpm gstreamer gtk2 gtkhtml imlib imlib2 innodb -java javascript jpeg libg++ libwww
mad md5sum mikmod mmx motif mozilla mpeg mpeg4 mysql ncurses oggvorbis odbc
offensive opengl pam pdflib perl png python quicktime readline sdl spell sse ssl
svga tcltk tiff truetype usb vanilla X xml2 xmms xosd xv xvid x86 zlib

Setting a USE flag is done with the help of the euse --enable command which requires a mandatory flag name argument. If the flag is not already set, euse appends the USE flag to the end of the current USE flag settings. In case the USE flag is invalid, there is a warning. Removing a USE flag is done using the euse --disable command. If an invalid flag is specified, the user is warned suitably. If the flag is present, it is unset with a -flag in make.conf 

# euse --enable 3dfx
USE setting in make.conf after enabling:
alsa acpi apache2 cups cdr crypt cscope -doc ethereal fbcon gif gimpprint gnome
gpm gstreamer gtk2 gtkhtml imlib imlib2 innodb -java javascript jpeg libg++ libwww
mad md5sum mikmod mmx motif mozilla mpeg mpeg4 mysql ncurses oggvorbis odbc
offensive opengl pam pdflib perl png python quicktime readline sdl spell sse ssl
svga tcltk tiff truetype usb vanilla X xml2 xmms xosd xv xvid x86 zlib 3dfx

# euse --disable 3dfx
USE setting in make.conf after disabling:
alsa acpi apache2 cups cdr crypt cscope -doc ethereal fbcon gif gimpprint gnome
gpm gstreamer gtk2 gtkhtml imlib imlib2 innodb -java javascript jpeg libg++ libwww
mad md5sum mikmod mmx motif mozilla mpeg mpeg4 mysql ncurses oggvorbis odbc
offensive opengl pam pdflib perl png python quicktime readline sdl spell sse ssl
svga tcltk tiff truetype usb vanilla X xml2 xmms xosd xv xvid x86 zlib -3dfx
euse does not physically remove the flag from make.conf. It just adds a - (minus) before the flag to unset it. You may have to manually clean up your make.conf to avoid unwanted variables.
Other tools
revdep-rebuild

This tool is Gentoo's Reverse Dependency rebuilder. It will scan your installed ebuilds to find packages that have become broken as a result of an upgrade of a package they depend on. It can emerge those packages for you but it can also happen that a given package does not work anymore with the currently installed dependencies, in which cas you should upgrade the broken package to a more recent version. revdep-rebuild will pass flags to emerge which lets you use the --pretend flag to see what is going to be emerged again before you go any further. 

# revdep-rebuild -p

Checking reverse dependencies...
Packages containing binaries and libraries broken by any package update,
will be recompiled.

Collecting system binaries and libraries... done.
  (/root/.revdep-rebuild.1_files)

Collecting complete LD_LIBRARY_PATH... done.
  (/root/.revdep-rebuild.2_ldpath)

Checking dynamic linking consistency...
  broken /usr/lib/ao/plugins-2/libarts.so (requires libartsc.so.0)
  broken /usr/lib/kde3/libkpresenterpart.so (requires libartskde.so.1 libqtmcop.so.1
         libsoundserver_idl.so.1 libkmedia2_idl.so.1 libartsflow.so.1 libartsflow_idl.so.1 libmcop.so.1)
  broken /usr/lib/ruby/site_ruby/1.8/i686-linux/fox.so (requires libFOX-1.0.so.0)
  broken /usr/lib/xine/plugins/1.0.0/xineplug_ao_out_arts.so (requires libartsc.so.0)
  broken /usr/lib/perl5/vendor_perl/5.8.0/i686-linux/auto/SDL_perl/SDL_perl.so (requires libSDL_gfx.so.0)
  broken /usr/lib/libloudmouth-1.so.0.0.0 (requires libgnutls.so.10)
  broken /usr/bin/k3b (requires libartskde.so.1 libqtmcop.so.1 libsoundserver_idl.so.1 libkmedia2_idl.so.1
         libartsflow.so.1 libartsflow_idl.so.1 libmcop.so.1)
  broken /usr/bin/lua (requires libhistory.so.4)
  broken /usr/bin/lyx (requires libAiksaurus-1.0.so.0)
  broken /usr/bin/luac (requires libhistory.so.4)
  broken /usr/bin/avidemux2 (requires libartsc.so.0)
  broken /usr/bin/pptout (requires libxml++-0.1.so.11)
  broken /usr/bin/xml2ps (requires libxml++-0.1.so.11)
 done.
  (/root/.revdep-rebuild.3_rebuild)

Assigning files to ebuilds... done.
  (/root/.revdep-rebuild.4_ebuilds)

Evaluating package order... done.
  (/root/.revdep-rebuild.5_order)

All prepared. Starting rebuild...
emerge --oneshot --nodeps -p =app-cdr/k3b-0.11.14 =app-office/koffice-1.3.2 =app-office/lyx-1.3.4 \
       =app-office/passepartout-0.2 =dev-lang/lua-5.0.2 =dev-ruby/fxruby-1.0.29 =media-libs/libao-0.8.5 \
       =media-libs/xine-lib-1_rc5-r3 =media-video/avidemux-2.0.26 =net-libs/loudmouth-0.16 

These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild   R   ] app-cdr/k3b-0.11.14  
[ebuild   R   ] app-office/koffice-1.3.2  
[ebuild   R   ] app-office/lyx-1.3.4  
[ebuild   R   ] app-office/passepartout-0.2  
[ebuild   R   ] dev-lang/lua-5.0.2  
[ebuild   R   ] dev-ruby/fxruby-1.0.29  
[ebuild   R   ] media-libs/libao-0.8.5  
[ebuild   R   ] media-libs/xine-lib-1_rc5-r3  
[ebuild   R   ] media-video/avidemux-2.0.26  
[ebuild   R   ] net-libs/loudmouth-0.16  

Now you can remove -p (or --pretend) from arguments and re-run revdep-rebuild.

If you need to rebuild some packages, you may run revdep-rebuild without the -p flag and the listed packages will be emerged again.

glsa-check

glsa-check is mainly a test tool that keeps track of the various GLSA's (Gentoo Linux Security Advisory) and will eventually be integrated into emerge and equery. For more information, please visit the Portage GLSA Integration Page.