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 Introduction
- 2 equery
- 2.1 Introduction
- 2.2 Finding the package that a file came from with belongs (b)
- 2.3 Viewing ChangeLog entries with changes (c)
- 2.4 Verifying package integrity with check (k)
- 2.5 Listing all packages depending on a package with depends (d)
- 2.6 Getting dependency graphs with depgraph (g)
- 2.7 Listing files installed by a package with files (f)
- 2.8 Looking for packages that have a specific USE flag with hasuse (h)
- 2.9 Listing packages with list (l)
- 2.10 Viewing package metadata with meta (m)
- 2.11 Finding package sizes with size (s)
- 2.12 Listing per-package USE flags with uses (u)
- 2.13 Finding the ebuild path with which (w)
- 3 euse
- 4 Other tools
- 5 See also
- 6 External resources
What is gentoolkit?
Gentoo is a unique distribution and presents some complexities that simply do not 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 app-portage/gentoolkit package.
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. Gentoo developers can have their scripts included into app-portage/gentoolkit-dev by contacting the Gentoolkit maintainer. The remainder of this document discusses the app-portage/gentoolkit package only.
Gentoolkit contains a whole bunch of useful tools to help users manage packages and keep track of what is going on in their systems. Most users -- particularly those who update systems often -- will benefit from having gentoolkit installed.
Just as with any Gentoo package, installation is just a simple emerge.
emerge --ask gentoolkit
Many of the tools in gentoolkit reveal important information about the system they are installed on or require root privileges. For that reason, some of the programs may only be executed (or only function properly) if run by a user with root privileges.
Any documentation that a program might have (other than man pages) is stored in /usr/share/doc/gentoolkit-[version]/[program-name]/.
equery is a tool that displays useful information about the installed packages on the system. equery is based on a system of modules. Every module has a shorthand name. For example, running equery l gcc is the same as running equery list gcc. Invoking the
--help option (equery --help) will output global options and list all available modules and their shorthand names. Adding a module name to the end (equery --help module) will display the help screen for that specific module. Lastly, executing man equery will also provide a detailed explanation of all available modules and options along with some useful examples.
Below is a list of features that work over the majority of modules.
equery --quiet list gcc
equery --quiet list sys-devel/gcc
equery --quiet list '>=sys-devel/gcc-4'
Like emerge, equery does not understand partial package names:
equery check zilla
!!! No package found matching zilla
Unlike emerge, equery can accept shell-like globbing in the category and/or package name:
equery check '*zilla*'
* Checking www-client/mozilla-firefox-3.0.14 ... 90 out of 90 files passed
equery check www-c*/*
* Checking www-client/links-2.2 ... 30 out of 30 files passed * Checking www-client/mozilla-firefox-3.0.14 ... 90 out of 90 files passed
Most equery modules take multiple input:
equery hasuse sse sse2
* Searching for USE flag sse ... [IP-] [ ] media-libs/flac-1.2.1-r3 (0) [IP-] [ ] media-libs/speex-1.2_beta3_p2 (0) * Searching for USE flag sse2 ... [IP-] [ ] dev-libs/openssl-0.9.8k (0) [IP-] [ ] x11-libs/pixman-0.16.0 (0)
A few modules also allow full regular expressions:
equery -q list --portage-tree --full-regex '[kr]?flickr.*'
dev-dotnet/flickrnet-bin-2.2 dev-ruby/flickr-1.0.2-r1 dev-ruby/flickr-1.0.2-r2 dev-ruby/rflickr-20060201 media-gfx/kflickr-0.6 [...]
Globbing support replaced a number of older options in equery. For example, to act on all packages in a certain set, use a
'*'(asterisk). To act on all packages in a category, use
Do not forget to quote input when using special shell characters like asterisks or greater than/less than signs.
The next few sections in this document give a quick introduction to the different equery modules.
Finding the package that a file came from with belongs (b)
equery belongs -e /usr/bin/glxgears
* Searching for /usr/bin/glxgears ... x11-apps/mesa-progs-7.5.1 (/usr/bin/glxgears)
belongs can search for files matching a regular expression with the
-f option. The
-e option stops searching after it finds a match. Since no file on your system should be owned by two packages, this is a safe optimization.
Viewing ChangeLog entries with changes (c)
changes lets the user view ChangeLog entries for a package version or range of versions. Imagine after running an emerge --sync Portage prints out a message saying it is going to be upgraded. To see what has changed this command can be used:
equery changes portage
*portage-184.108.40.206 (03 May 2009) 03 May 2009; Zac Medico <email@example.com> +portage-220.127.116.11.ebuild: 18.104.22.168 bump. This fixes bug #268398 (document econf automatic die) and bug #267104 (handle insufficient space interaction with userfetch). Bug #268228 tracks all bugs fixed since 22.214.171.124.
Verifying package integrity with check (k)
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.
equery check gentoolkit
* Checking app-portage/gentoolkit-0.3.0_rc7 ... 71 out of 71 files passed
Listing all packages depending on a package with depends (d)
Ever wonder why a certain package has been installed on the system? equery can tell which packages list it as a dependency with
depends. Include indirect dependencies with the
equery depends pygtk
* Searching for pygtk ... app-admin/pessulus-2.24.0 (>=dev-python/pygtk-2.6.0) app-editors/gedit-2.24.3 (python ? >=dev-python/pygtk-2.12) dev-libs/libgweather-2.24.3 (python ? >=dev-python/pygtk-2) dev-python/gnome-python-base-2.22.3 (>=dev-python/pygtk-2.10.3) dev-python/gnome-python-desktop-base-2.24.1 (>=dev-python/pygtk-2.10.3) [...]
Getting dependency graphs with depgraph (g)
depgraph is the opposite of
depends. A package is passed and it will find the packages that package depends on (not the packages that depend on that package). When it finds a dependency, it will recursively search for all of that package's dependencies. Control how deep the tree gets with the
equery depgraph mozilla-firefox
* Searching for mozilla-firefox ... * dependency graph for www-client/mozilla-firefox-126.96.36.199: `-- www-client/mozilla-firefox-188.8.131.52 `-- virtual/jre-1.6.0 (virtual/jre) [java] `-- virtual/jdk-1.6.0 (virtual/jdk-1.6.0*) `-- dev-java/icedtea6-bin (unable to resolve: package masked or removed) `-- dev-java/sun-jdk-184.108.40.206 `-- dev-java/java-sdk-docs-220.127.116.11 [doc] `-- app-arch/unzip-6.0-r1 `-- app-arch/bzip2-1.0.5-r1 [bzip2] `-- sys-libs/glibc-2.9_p20081201-r2 `-- sys-devel/gettext-0.17 [nls] `-- virtual/libiconv-0 (virtual/libiconv) [...]
jre is a direct dependency and
jdk is an indirect dependency if the
java USE is set?
Listing files installed by a package with files (f)
equery can list all the files installed by an ebuild with the
files module. Try
--tree to get an easy to read directory layout. Use
--filter to only find a certain type of file. For example, to find where executables were installed use
--filter=cmd, or to quickly find the configuration file location try
equery files --tree gentoolkit
* Searching for gentoolkit ... * Contents of app-portage/gentoolkit-0.3.0_rc7: /etc > /eclean + distfiles.exclude + packages.exclude > /env.d + 99gentoolkit-env > /revdep-rebuild + 99revdep-rebuild /usr > /bin + eclean + eclean-dist -> eclean + eclean-pkg -> eclean + epkginfo + equery + eread + euse + glsa-check + revdep-rebuild > /lib > /python2.6 > /site-packages > /gentoolkit + gentoolkit-0.3.0_rc7-py2.6.egg-info + __init__.py > /equery + __init__.py + belongs.py + changes.py + check.py + depends.py + depgraph.py + files.py [...]
Looking for packages that have a specific USE flag with hasuse (h)
hasuse can be used to find packages with a given USE flag.
hasuse will not indicate if the flag is enabled, only if the ebuild lists it as an option. See the EXAMPLES section of
hasuse in the equery man page for more tip on getting this kind of information.
equery hasuse qt3 qt4
* Searching for USE flag qt3 ... [IP-] [ ] app-crypt/pinentry-0.7.5 (0) [IP-] [ ] net-dns/avahi-0.6.24-r2 (0) [IP-] [ ] net-wireless/wpa_supplicant-0.6.9 (0) * Searching for USE flag qt4 ... [IP-] [ ] net-dns/avahi-0.6.24-r2 (0) [IP-] [ ] net-wireless/wpa_supplicant-0.6.9 (0)
Listing packages with list (l)
list is a simple, yet powerful module to list packages that are installed, in the Portage tree or in an overlay.
equery list '*'
* Searching for * ... [IP-] [ ] app-admin/eselect-1.2.3 (0) [IP-] [ ] app-admin/eselect-ctags-1.10 (0) [IP-] [ ] app-admin/eselect-esd-20060719 (0) [IP-] [ ] app-admin/eselect-fontconfig-1.0 (0) [IP-] [ ] app-admin/eselect-opengl-1.0.8-r1 (0) [IP-] [ ] app-admin/eselect-python-20090824 (0) [IP-] [ ] app-admin/eselect-ruby-20081227 (0) [IP-] [ ] app-admin/eselect-vi-1.1.5 (0) [IP-] [ ] app-admin/perl-cleaner-1.05 (0) [IP-] [ ] app-admin/pessulus-2.24.0 (0) [IP-] [ ] app-admin/python-updater-0.7 (0) [IP-] [ ] app-admin/sudo-1.7.2_p1 (0) [...]
The standard query will search installed packages for the given package name. Passing in
'*' displays all packages in the set. In the leftmost field it is possible to see all the above packages are
I(nstalled) and from the
P(ortage) tree. They are not masked (the second field is blank), and they are all installed in the default slot (0).
Use local options to look for packages in the Portage tree and overlays.
equery list -po vim
* Searching for vim ... [-P-] [ ] app-editors/vim-7.0.235 (0) [-P-] [ ~] app-editors/vim-7.0.243 (0) [-P-] [ ] app-editors/vim-7.1.123 (0) [-P-] [ ~] app-editors/vim-7.1.330 (0) [-P-] [ ] app-editors/vim-7.2 (0) [-P-] [ ~] app-editors/vim-7.2.108 (0) [IP-] [ ] app-editors/vim-7.2.182 (0) [-P-] [ ~] app-editors/vim-7.2.238 (0) [-P-] [ ~] app-editors/vim-7.2.264 (0)
In this is it possible to see version 7.2.182 is installed and there are no versions available from an overlay. Users can see which versions are keyword masked by the
~ in the second field.
Viewing package metadata with meta (m)
Each package in the Portage tree provides at least some metadata about its maintainer, herd, etc. Read about Gentoo Metadata. The amount of useful information depends on how much package maintainers decide to provide. With no options,
meta returns some basic useful information.
equery meta gnucash
* app-office/gnucash [gentoo] Herd: gnome-office (firstname.lastname@example.org) Maintainer: email@example.com (Torsten Veller) Upstream: None specified Location: /usr/portage/app-office/gnucash Keywords: 2.2.9-r1:0: alpha amd64 ppc sparc x86 Keywords: 2.2.9-r2:0: Keywords: 2.3.8:0: Keywords: 2.3.10:0: ~alpha ~amd64 ~ppc ~sparc ~x86
Maintainer's providing extra information about the package can be very useful:
equery meta --description emacs
* app-editors/emacs GNU Emacs is an extensible, customizable text editor - and more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp programming language with extensions to support text editing. The features of GNU Emacs include: * Content-sensitive editing modes, including syntax coloring, for a wide variety of file types including plain text, source code, and HTML. * Complete built-in documentation, including a tutorial for new users. * Support for many languages and their scripts, including all the European "Latin" scripts, Russian, Greek, Japanese, Chinese, Korean, Thai, Vietnamese, Lao, Ethiopian, and some Indian scripts. * Highly customizable, using Emacs Lisp code or a graphical customization interface. * A large number of extensions that add other functionality, including a project planner, mail and news reader, debugger interface, calendar, and more. Many of these extensions are distributed with GNU Emacs; others are available separately.
Finding package sizes with size (s)
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 command might not give the correct figure. Not to worry, equery to the rescue!
equery size openoffice-bin
* app-office/openoffice-bin-3.1.1 Total files : 4624 Total size : 361.38 MiB
size prints the total space used in human-readable units and lists the total number of files the package has. To get the total size in bytes use
Listing per-package USE flags with uses (u)
uses module can provide information about what USE flags are available for a specific package and which of those flags is currently enabled.
equery uses gst-plugins-meta
* Searching for gst-plugins-meta ... [ Legend : U - flag is set in make.conf ] [ : I - package is installed with flag ] [ Colors : set, unset ] * Found these USE flags for media-plugins/gst-plugins-meta-0.10-r2: U I + + X : Adds support for X11 - - a52 : Enables support for decoding ATSC A/52 streams used in DVD + + alsa : Adds support for media-libs/alsa-lib (Advanced Linux Sound Architecture) - - dvb : Adds support for DVB (Digital Video Broadcasting) + + dvd : Adds support for DVDs + + esd : Adds support for media-sound/esound (Enlightened Sound Daemon) + + ffmpeg : Enable ffmpeg-based audio/video codec support + + flac : Adds support for FLAC: Free Lossless Audio Codec - - mad : Adds support for mad (high-quality mp3 decoder library and cli frontend) + + mpeg : Adds libmpeg3 support to various packages - - mythtv : Support for retrieval from media-tv/mythtv backend + + ogg : Adds support for the Ogg container format (commonly used by Vorbis, Theora and flac) - - oss : Adds support for OSS (Open Sound System) + + theora : Adds support for the Theora Video Compression Codec + + vorbis : Adds support for the OggVorbis audio codec - - xv : Adds in optional support for the Xvideo extension (an X API for video playback)
Here a number of USE flags are enabled in gstreamer's plugin meta-package, but it can be seen that there are other USE flags available. For more information on USE flags, please refer to the USE Flags chapter of the Gentoo Handbook.
Finding the ebuild path with which (w)
which is a simple script to help users quickly find the file path to an ebuild. If an unversioned package name is passed using
which it will return the path to the newest installable ebuild version. In other words, it would return the ebuild Portage would use if emerge example/package was typed.
which also accepts a versioned package to get the path to that ebuild.
equery which gnome
Lastly, if none of the above features of equery have provided an answer, try using
which to manually search an ebuild with programs like cat, less or grep:
grep HOMEPAGE $(equery which gentoolkit)
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 it can be turned off by adding the
--no-pipeoption. When writing scripts that employ equery be aware of this option.
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. 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.
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].
Similarly the euse -a -g command is used to view active global USE flags. The euse -a -l command does the same for active local USE flags.
-l are suboptions to euse and need an option before them (like
-a) to function correctly.
euse -a -l
bitmap-fonts [+ D ] font-server [+ D ] fortran [+ D ] gimpprint [+ C ] md5sum [+ C ] mpeg4 [+ C ] nvidia [+ C ] offensive [+ ] truetype [+ CD ]
euse is able 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).
Do not use the euse -E or euse -D commands by themselves (without a flag). It will set/unset ALL USE flags in /etc/portage/make.conf. Although a backup is kept at /etc/portage/make.conf.euse_backup, please be careful while using euse -E or euse -D!
Enabling a USE Flag:
euse -E 3dfx
/etc/portage/make.conf was modified, a backup copy has been placed at /etc/portage/make.conf.euse_backup
The /etc/portage/make.conf file looks like so after the command was ran:
Disabling the USE flag:
euse -D 3dfx
/etc/portage/make.conf was modified, a backup copy has been placed at /etc/portage/make.conf.euse_backup
Again, the /etc/portage/make.conf file after the command:
euse does not physically remove the flag from make.conf. It adds a
-(minus) before the flag to unset it. A manual clean up of the make.conf might be needed to avoid unwanted variables. Otherwise use the
-P(purge) option to remove the flag. euse -P 3dfx for example would remove the
This tool is Gentoo's Reverse Dependency rebuilder. It will scan the 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 users automatically but it can also happen that a given package does not work 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 going any further.
* Configuring search environment for revdep-rebuild * Checking reverse dependencies * Packages containing binaries and libraries broken by a package update * will be emerged. * Collecting system binaries and libraries * Generated new 1_files.rr * Collecting complete LD_LIBRARY_PATH * Generated new 2_ldpath.rr * Checking dynamic linking consistency [ 48% ] * broken /usr/lib/gstreamer-0.10/libgsttaglib.la (requires /usr/lib/libtag.la) [ 64% ] * broken /usr/lib/libgdkglext-x11-1.0.la (requires /usr/lib/libGLU.la) [ 67% ] * broken /usr/lib/libgtkglext-x11-1.0.la (requires /usr/lib/libGLU.la) [ 85% ] * broken /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gdkgl/_gdkgl.la (requires /usr/lib/libGLU.la) * broken /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gtkgl/_gtkgl.la (requires /usr/lib/libGLU.la) [ 97% ] * broken /usr/qt/3/lib/libqt-mt.la (requires -lpng) [ 100% ] * Generated new 3_broken.rr * Assigning files to packages * /usr/lib/gstreamer-0.10/libgsttaglib.la -> media-plugins/gst-plugins-taglib * /usr/lib/libgdkglext-x11-1.0.la -> x11-libs/gtkglext * /usr/lib/libgtkglext-x11-1.0.la -> x11-libs/gtkglext * /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gdkgl/_gdkgl.la -> dev-python/pygtkglext * /usr/lib/python2.6/site-packages/gtk-2.0/gtk/gtkgl/_gtkgl.la -> dev-python/pygtkglext * /usr/qt/3/lib/libqt-mt.la -> x11-libs/qt * Generated new 4_raw.rr and 4_owners.rr * Cleaning list of packages to rebuild * Generated new 4_pkgs.rr * Assigning packages to ebuilds * Generated new 4_ebuilds.rr * Evaluating package order * Generated new 5_order.rr * All prepared. Starting rebuild emerge --oneshot --pretend dev-python/pygtkglext:0 media-plugins/gst-plugins-taglib:0.10 x11-libs/gtkglext:0 x11-libs/qt:3 These are the packages that would be merged, in order: Calculating dependencies... done! [ebuild R ] media-plugins/gst-plugins-taglib-0.10.17 [ebuild R ] x11-libs/gtkglext-1.2.0 [ebuild R ] x11-libs/qt-3.3.8b-r2 [ebuild R ] dev-python/pygtkglext-1.1.0 * Now you can remove -p (or --pretend) from arguments and re-run revdep-rebuild.
To rebuild some packages run revdep-rebuild without the
-p flag and the listed packages will be emerged again.
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.
eread is a simple utility to display elog files produced by >=
portage-2.1. The saving of elog files can be enabled by setting a couple of variables in /etc/portage/make.conf:
This is only 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 elog has been set up to satisfaction, run eread to view the log files.
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. The PAGER environmental variable can be set using eselect (module
After displaying the elog item, you will be prompted if you want to delete the file.
eclean is a tool to remove old source files and old binary packages from the system.
Building and installing packages, the source files are downloaded and preserved in
DISTDIR, usually /usr/portage/distfiles. This can accumulate several gigabytes of material over time if it is not cleaned periodically. Users should run eclean-dist to clean source files from
It is possible to create archives of installed packages by using quickpg or FEATURES="buildpkg". These archived packages are kept in PKGDIR, usually /usr/portage/packages. When they are no longer needed, or if they are too old, eclean-pkg can be ran to remove them from
PKGDIR. It is a good way to ensure that any binary packages on the system are only the latest versions.
For more information on eclean and tips on maintaining a cruft-free system, please read man eclean or check the eclean article.
This article is based on a document formerly found on our main website gentoo.org.
The following people have contributed to the original document: Matt Butcher, John P. Davis, Erwin, Shyam Mani, Xavier Neys, Karl Trygve, José Luis Rivero, Joshua Saddler, Douglas Anderson
They are listed here as the Wiki history does not provide for any attribution. If you edit the Wiki article, please do not add yourself here, your contributions are recorded on the history page.