Gentoolkit
1. 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.
Note:
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.
If you are a developer, you can have your scripts included into
gentoolkit-dev by contacting the Gentoolkit maintainer. 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.
Code Listing 1.1: Getting gentoolkit |
# emerge gentoolkit
|
Note:
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/share/doc/gentoolkit-[version]/[program-name]/.
2. equery
Introduction
equery is a tool that displays a great deal of useful information about
the packages on your system and much more. equery --help gives you the
full set of options.
Note:
Not all features listed by equery --help have been implemented yet.
Those that have not been, are mentioned clearly. You will also see that
every command has a short option, e.g. b instead of belongs.
|
Note:
Be aware that equery currently changes the format of the output if it is sent
through a pipe. The piped format is intended to be easier to parse by tools, but
you can also turn it off by adding the --no-pipe option. If you write
scripts that employ equery, you should be aware of this.
|
Finding the Package That a File Came From
equery also provides the functionality of finding the package that a
file came from, using belongs command (or just b).
Code Listing 2.1: Finding the ebuild that installed a given file |
# equery belongs /usr/bin/audacious
[ Searching for file(s) /usr/bin/audacious in *... ]
media-sound/audacious-1.1.2 (/usr/bin/audacious)
|
By using the -f option, you may search for packages with files
matching any regular expression. The -e option is useful for
terminating your search immediately when a match is found.
Verifying Package Integrity
Sometimes it is useful to check a package's integrity. equery can
verify md5 sums as well as timestamps to indicate when a package might
have been corrupted, replaced, or removed.
Code Listing 2.2: OK package integrity |
# equery check gentoolkit
[ Checking app-portage/gentoolkit-0.2.0 ]
* 54 out of 54 files good
|
Please note that if you change configuration files after installation,
these may be reported as "not good".
List of all packages depending on ...
equery is able to list all direct dependencies matching a package.
The function we should use to do this is depends and it's as easy as:
Code Listing 2.3: Looking for packages depending on pygtk |
# equery depends pygtk
[ Searching for packages depending on pygtk... ]
app-office/dia-0.93
dev-python/gnome-python-2.0.0-r1
gnome-extra/gdesklets-core-0.26.2
media-gfx/gimp-2.0.4
x11-libs/vte-0.11.11-r1
|
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.
Code Listing 2.4: Dependency Graph for cdrtools |
# 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 is a direct dependency for cdrtools,linux-headers
are an indirect dependency. Note that the output also includes information
about virtual packages. In the example above, cdrtools is actually
written to require virtual/libc, not sys-libs/glibc, but on the given
system in the example sys-libs/glibc provides virtual/libc.
Listing Files Belonging to an Ebuild
equery can list the files that belong to an installed ebuild. If I
don't know the files that Gentoolkit has installed on the system, I will
use equery to show them.
Code Listing 2.5: Listing files |
# equery files gentoolkit
[ Searching for packages matching gentoolkit... ]
app-portage/gentoolkit-0.2.0
* Contents of app-portage/gentoolkit-0.2.0:
/usr
/usr/bin
/usr/bin/equery
/usr/bin/etcat
/usr/bin/euse
/usr/bin/glsa-check
/usr/bin/qpkg
/usr/bin/revdep-rebuild
/usr/lib
/usr/lib/gentoolkit
/usr/lib/gentoolkit/pym
/usr/lib/gentoolkit/pym/gentoolkit
/usr/lib/gentoolkit/pym/gentoolkit/__init__.py
/usr/lib/gentoolkit/pym/gentoolkit/gentoolkit.py
/usr/lib/gentoolkit/pym/gentoolkit/pprinter.py
/usr/lib/gentoolkit/pym/glsa.py
/usr/sbin
/usr/share
/usr/share/doc
/usr/share/doc/gentoolkit-0.2.0_pre10
[...]
|
The command files of equery provide some options to modify
the output. You can look them all up in the equery man page.
Looking for packages that use a specific USE flag
If you want to find which packages on your system that make use of a specific
USE flag, equery has the function hasuse:
Code Listing 2.6: Searching packages which use the firefox USE flag |
# equery hasuse firefox
[ Searching for USE flag firefox in all categories among: ]
* installed packages
[I--] [ ] dev-python/gnome-python-extras-2.14.0-r1 (0)
[I--] [ ] media-video/totem-2.16.4 (0)
|
Listing Packages
equery has a power feature to list packages belonging to our system,
portage or even an overlay. Let's try this:
Code Listing 2.7: Listing packages with equery |
# equery list gentoolkit
[ Searching for package 'gentoolkit' in all categories among: ]
* installed packages
[I--] [ ] app-portage/gentoolkit-0.2.0 (0)
|
The standard query will search our installed packages for the name given.
If found, the following info will be displayed: the package location between
the first square brackets (I for Installed packages, P for Portage, O for
Overlay), the possible masks between the second (~ by keyword, - by arch or
M hard masked), then the category and complete name and last of all, the slot
in which the package is stored.
Another example, this time we are going to use the local options in order
to look for packages in our portage tree and overlay.
Code Listing 2.8: Using local options with equery |
# equery list -p -o vim
[ Searching for package 'vim' in all categories among: ]
* installed packages
[I--] [ ] app-editors/vim-6.3-r4 (0)
* Portage tree (/usr/portage)
[-P-] [M~] app-editors/vim-7.0_alpha20050126 (0)
[-P-] [M~] app-editors/vim-7.0_alpha20050201 (0)
[-P-] [ ] app-editors/vim-6.3-r2 (0)
[-P-] [M~] app-editors/vim-7.0_alpha20050122 (0)
[-P-] [M~] app-editors/vim-core-7.0_alpha20050126 (0)
[-P-] [ ] app-editors/vim-core-6.3-r3 (0)
[-P-] [M~] app-editors/vim-core-7.0_alpha20050122 (0)
[-P-] [M~] app-editors/vim-core-7.0_alpha20050201 (0)
[-P-] [ ] app-editors/vim-core-6.3-r4 (0)
* overlay tree (/opt/ebuilds)
|
Finding 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!
Code Listing 2.9: Package Size |
# 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 also tells us what our current USE
flags are for a package and also what USE flags are available for the package.
Code Listing 2.10: Set and Unset USE Flags |
# equery uses wireshark
[ 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/wireshark-0.99.4 ]
- - 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
- - kerberos : Adds kerberos support
- - portaudio : Adds support for the crossplatform portaudio audio API
- - selinux : !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
- - snmp : Adds support for the Simple Network Management Protocol if available
+ + ssl : Adds support for Secure Socket Layer connections
- - threads : Adds threads support for various packages. Usually pthreads
|
I have installed wireshark with only the gtk and ssl flags set, but there are
several other USE flags for wireshark still available. 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 by using the equery which command which
displays the full path to the ebuild.
Code Listing 2.11: Displaying the ebuild path |
# equery which cdrtools
/usr/portage/app-cdr/cdrtools/cdrtools-2.01_alpha37.ebuild
|
3. 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.
Please see euse -h for complete help and all options.
Viewing, Setting and Unsetting USE Flags
The euse -a command reads the current active USE flags and displays
them.
Note:
There are 5 "columns" that euse now uses to show whether a
flag is set/unset and where all the flag has been set. The columns are as
follows -- +/-, set in the Environment, set in make.Conf, set in make.Defaults,
and set in make.Globals. The output looks like [+ECDG].
|
Code Listing 3.1: Viewing all active USE flags |
# euse -a
X [+ CD ]
aalib [+ ]
acpi [+ C ]
alsa [+ C ]
apache2 [+ C ]
apm [+ D ]
avi [+ D ]
berkdb [+ D ]
bitmap-fonts [+ D ]
bonobo [+ ]
cdr [+ C ]
crypt [+ CD ]
cscope [+ C ]
cups [+ CD ]
curl [+ ]
emboss [+ D ]
encode [+ D ]
esd [+ ]
fam [+ ]
fbcon [+ C ]
firefox [+ C ]
font-server [+ D ]
foomaticdb [+ D ]
fortran [+ D ]
gd [+ C ]
gdbm [+ D ]
gif [+ CD ]
gimpprint [+ C ]
gnome [+ CD ]
gphoto2 [+ ]
gpm [+ CD ]
gstreamer [+ C ]
gtk [+ D ]
gtkhtml [+ C ]
guile [+ ]
imagemagick [+ ]
imlib [+ CD ]
innodb [+ ]
ipv6 [+ D ]
javascript [+ C ]
jpeg [+ CD ]
kde [+ D ]
ldap [+ ]
libg++ [+ CD ]
libwww [+ CD ]
mad [+ CD ]
mbox [+ C ]
md5sum [+ C ]
mikmod [+ CD ]
mmx [+ C ]
motif [+ CD ]
mp3 [+ ]
mpeg [+ CD ]
mpeg4 [+ C ]
mysql [+ C ]
ncurses [+ CD ]
nls [+ D ]
nvidia [+ C ]
odbc [+ ]
offensive [+ ]
ogg [+ CD ]
opengl [+ CD ]
oss [+ D ]
pam [+ CD ]
pdflib [+ CD ]
perl [+ CD ]
png [+ CD ]
python [+ CD ]
qt [+ D ]
quicktime [+ CD ]
readline [+ CD ]
ruby [+ ]
sdl [+ CD ]
slang [+ D ]
spell [+ CD ]
sse [+ C ]
ssl [+ CD ]
svga [+ CD ]
tcltk [+ C ]
tcpd [+ D ]
tiff [+ C ]
truetype [+ CD ]
usb [+ C ]
vanilla [+ C ]
x86 [+ C ]
xml [+ ]
xosd [+ C ]
xv [+ CD ]
xvid [+ C ]
zlib [+ CD ]
|
Similarly you can use the euse -a -g command to only view active global
USE flags. The euse -a -l command does the same for active local USE
flags.-g & -l are suboptions to euse and need an
option before them (like -a) to function correctly.
Code Listing 3.2: Viewing active local USE flags |
# euse -a -l
bitmap-fonts [+ D ]
font-server [+ D ]
fortran [+ D ]
gimpprint [+ C ]
md5sum [+ C ]
mpeg4 [+ C ]
nvidia [+ C ]
offensive [+ ]
truetype [+ CD ]
|
We can also use euse to set or unset use flags. The commands used for
this are euse -E flagname (enable a flag) and euse -D flagname
(disable a flag).
Warning:
Do not use the euse -E or euse -D commands by themselves (without
a flag). It will set/unset ALL USE flags in /etc/make.conf. Although a
backup is kept at /etc/make.conf.euse_backup, please be careful
while using euse -E or euse -D.
|
Code Listing 3.3: Setting and Unsetting USE flags |
# euse -E 3dfx
/etc/make.conf was modified, a backup copy has been placed at /etc/make.conf.euse_backup
USE="alsa acpi apache2 -arts cups cdr crypt cscope -doc fbcon \
firefox gd gif gimpprint gnome gpm gstreamer gtkhtml imlib \
innodb -java javascript jpeg libg++ libwww mad mbox md5sum \
mikmod mmx motif mpeg mpeg4 mysql ncurses nvidia \
ogg odbc offensive opengl pam pdflib perl png python \
quicktime readline sdl spell sse ssl svga tcltk tiff truetype usb \
vanilla X xosd xv xvid x86 zlib 3dfx"
# euse -D 3dfx
/etc/make.conf was modified, a backup copy has been placed at /etc/make.conf.euse_backup
USE="alsa acpi apache2 -arts cups cdr crypt cscope -doc fbcon \
firefox gd gif gimpprint gnome gpm gstreamer gtkhtml imlib \
innodb -java javascript jpeg libg++ libwww mad mbox md5sum \
mikmod mmx motif mpeg mpeg4 mysql ncurses nvidia \
ogg odbc offensive opengl pam pdflib perl png python \
quicktime readline sdl spell sse ssl svga tcltk tiff truetype usb \
vanilla X xosd xv xvid x86 zlib -3dfx"
|
Note:
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.
|
4. 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 case 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.
Code Listing 4.1: Running revdep-rebuild in pretend mode |
# 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.
eread
eread is a simple utility to display elog files produced by
>=portage-2.1. You can set the saving of elog files by setting a couple
of variables in /etc/make.conf:
Code Listing 4.2: Enabling elog in /etc/make.conf |
PORTAGE_ELOG_CLASSES="log"
PORTAGE_ELOG_SYSTEM="save"
|
Note:
This is just one way of saving elog messages. For more information on how
Portage's elog system works, please refer to the appropriate page in the Portage
Handbook.
|
Once you've set up elog to your satisfaction, just run eread to view your
log files.
Code Listing 4.3: Using eread |
$ eread
This is a list of portage log items. Choose a number to view that file or type q to quit.
1) app-portage:gentoolkit-0.2.4_pre2:20070320-000256.log
2) app-portage:gentoolkit-0.2.4_pre2:20070320-000258.log
3) app-portage:gentoolkit-0.2.4_pre2:20070320-000319.log
4) app-portage:gentoolkit-0.2.3:20070320-000408.log
Choice?
|
Select a number and the file will be displayed using the paging program
specified in the PAGER environment variable. If PAGER is not set, it will use
less.
After displaying the elog item, you will be prompted if you want to delete the
file.
|
