Portage-utils

1. Introduction

portage-utils is a collection of very fast utilities written in C, which are meant to offer a faster but more limited alternative to their gentoolkit counterparts. Please note that portage-utils is not meant to replace gentoolkit. Its utilities are much more efficient than the equivalent ones from gentoolkit and might be better suited to be used in scripts that need to call Portage repeatedly, but portage-utils does not offer the same functionalities. It does not consider eclasses at all and does not provide tools like revdep-rebuild and glsa-check.

More information about gentoolkit can be found in the Gentoolkit guide.

You can view the complete list of applications in portage-utils by typing man q or q --help. Please read the man page for each utility described, as this guide is only meant to be a short reference for the most useful functions and does not include all the information about each application.

The first step of using portage-utils is to install the package:

Code Listing 1.1: Installing portage-utils

# emerge portage-utils

2. Usage

How to find a package to which a file belongs

qfile finds the package to which a file belongs:

Code Listing 2.1: Finding the package to which a file belongs

$ qfile /etc/fonts/fonts.conf
media-libs/fontconfig (/etc/fonts/fonts.conf)
$ qfile /usr/share/keymaps/atari/atari-uk-falcon.map.gz
sys-apps/kbd (/usr/share/keymaps/atari/atari-uk-falcon.map.gz)

Verifying package integrity

If you want to check MD5 sums or mtimes of the files installed by some package, you can do it using the qcheck application:

Code Listing 2.2: Checking package integrity

$ qcheck portage-utils
Checking app-portage/portage-utils-0.1.13 ...
  * 36 out of 36 files are good

Of course, all the files which were changed after installation will be reported here. If the application reports configuration files which you have manually edited after installation, there's nothing to worry about.

Listing packages which depend on some package

Of course there's also an application which allows you to list all the packages which depend on some package. This is done using qdepends. Use the -a flag to show all the DEPEND, RDEPEND, and PDEPEND information for a package.

Code Listing 2.3: Listing packages which depend on some package

$ qdepends -a pygtk
 * DEPEND
dev-python/pygtk-2.8.2: >=dev-lang/python-2.3 >=x11-libs/gtk+-2.8.0
>=dev-libs/glib-2.8.0 >=x11-libs/pango-1.10.0 >=dev-libs/atk-1.8.0
>=gnome-base/libglade-2.5.0 >=dev-python/pycairo-0.9.0 dev-python/numeric
virtual/opengl dev-python/pyopengl >=x11-libs/gtkglarea-1.99
>=dev-util/pkgconfig-0.9 sys-devel/patch
 * RDEPEND
dev-python/pygtk-2.8.2: >=dev-lang/python-2.3 >=x11-libs/gtk+-2.8.0
>=dev-libs/glib-2.8.0 >=x11-libs/pango-1.10.0 >=dev-libs/atk-1.8.0
>=gnome-base/libglade-2.5.0 >=dev-python/pycairo-0.9.0 dev-python/numeric
virtual/opengl dev-python/pyopengl >=x11-libs/gtkglarea-1.99
 * PDEPEND

Listing files that belong to an ebuild

qlist gives you a list of all files that belong to an ebuild.

Code Listing 2.4: Listing files which belong to an ebuild file

$ qlist vim
/usr/bin/gvim
/usr/bin/gvimdiff
/usr/bin/evim
/usr/bin/eview
/usr/bin/gview
/usr/bin/rgvim
[...]

Looking for packages that use some USE flag

This is done with quse, which must be run as root. It may take some time to first create/update the ebuild cache.

Code Listing 2.5: Looking for packages with the 'firefox' USE flag

# quse firefox
app-office/openoffice/openoffice-2.0.2_rc1.ebuild binfilter curl eds firefox gnome gtk java kde ldap xml2
dev-haskell/gtk2hs/gtk2hs-0.9.10.ebuild doc glade gnome firefox
dev-java/swt/swt-3.1-r1.ebuild accessibility cairo firefox gnome
[...]

Finding package sizes

This is done with qsize application and is as simple as:

Code Listing 2.6: Finding package size

$ qsize vim
app-editors/gvim-6.4: 10 files, 7 non-files, 2327.516 KB
app-editors/vim-6.4: 6 files, 2 non-files, 2058.14 KB
app-editors/vim-core-6.4: 1024 files, 68 non-files, 10950.984 KB
[...]

Searching the Portage tree

One of the most powerful tools of portage-utils is qsearch. This tool allows you to search your Portage tree much faster than default emerge -s.

Here are some examples of its usage:

Code Listing 2.7: Using qsearch to search the tree

(I forgot the name of the package with my favorite fonts)
$ qsearch terminus
media-fonts/terminus-font A clean fixed font for the console and X11

(I want to thank the guy who made them. What's his homepage?)
$ qsearch -H terminus
media-fonts/terminus-font http://www.is-vn.bg/hamster/jimmy-en.html

(I need a jabber client and I need it now)
$ qsearch -S "jabber client"
app-emacs/emacs-jabber A Jabber client for Emacs.
net-im/gajim Jabber client written in PyGTK
net-im/gnome-jabber Gnome Jabber Client
net-im/gossip Lightweight Jabber client for GNOME
net-im/imcom Python commandline Jabber Client
net-im/psi QT 3.x Jabber Client, with Licq-like interface
net-im/tkabber Featureful Jabber client for tcl/tk.
x11-themes/psi-themes Iconsets for Psi, a QT 3.x Jabber Client

Extracting information from emerge logs

There is also a tool that allows you to extract useful information from your emerge.log file. It's called qlop and it can be useful when you want to estimate package compilation times or compare with your friends whose computer compiles faster. It also allows you to check what's compiling at the moment and how long it will take - which is handy when you're working in the console and don't have any other means to check it.

Code Listing 2.8: Reading emerge logs with qlop

(I'm starting to emerge perl and I want an estimate on how long it usually takes)
$ qlop -tH perl
perl: 7 minutes, 52 seconds for 4 merges
(Now let's see what's emerging at the moment)
$ qlop -c
* perl-5.8.8-r23
    started: Mon May 21 12:41:11 2007
    elapsed: 19 seconds

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.