Gentoo Logo

[ << ] [ < ] [ Home ] [ > ] [ >> ]

6. Advanced Portage Features


6.a. Introduction

For most users, the information received thus far is sufficient for all their Linux operations. But Portage is capable of much more; many of its features are for advanced users or only applicable in specific corner cases. Still, that would not be an excuse not to document them.

Of course, with lots of flexibility comes a huge list of potential cases. It will not be possible to document them all here. Instead, we hope to focus on some generic issues which you can then bend to fit your own needs. If you have need for more specific tweaks and tips, you might find them on the Gentoo Wiki instead.

Most, if not all of these additional features can be easily found by digging through the manual pages that portage provides:

Code Listing 1.1: Reading up on portage man pages

$ man portage
$ man make.conf

Finally, know that these are advanced features which, if not worked with correctly, can make debugging and troubleshooting very difficult. Make sure you mention these if you think you hit a bug and want to open a bugreport.

6.b. Per-Package Environment Variables

Using /etc/portage/env

By default, package builds will use the environment variables defined in /etc/portage/make.conf, such as CFLAGS, MAKEOPTS and more. In some cases though, you might want to provide different variables for specific packages. To do so, Portage supports the use of /etc/portage/env and /etc/portage/package.env.

The /etc/portage/package.env file contains the list of packages for which you want deviating variables as well as a specific identifier that tells Portage which changes you want. The identifier name you pick yourself, Portage will look for the variables in the /etc/portage/env/<identifier> file.

Example: Using debugging for specific packages

As an example, we enable debugging for the media-video/mplayer package.

First of all, we set the debugging variables in a file called /etc/portage/env/debug-cflags. The name is arbitrarily chosen, but of course reflects the reason of the deviation to make it more obvious later why a deviation was put in.

Code Listing 2.1: /etc/portage/env/debug-cflags content

CFLAGS="-O2 -ggdb -pipe"

Next, we tag the media-video/mplayer package to use this content:

Code Listing 2.2: /etc/portage/package.env content

media-video/mplayer debug-cflags

6.c. Hooking In the Emerge Process

Using /etc/portage/bashrc and affiliated files

When Portage works with ebuilds, it uses a bash environment in which it calls the various build functions (like src_prepare, src_configure, pkg_postinst, etc.). But Portage also allows you to set up a bash environment yourself.

The advantage of using your own bash environment is that you can hook in the emerge process during each step it performs. This can be done for every emerge (through /etc/portage/bashrc) or by using per-package environments (through /etc/portage/env as discussed earlier).

To hook in the process, the bash environment can listen to the variables EBUILD_PHASE, CATEGORY as well as the variables that are always available during ebuild development (such as P, PF, ...). Based on the values of these variables, you can then execute additional steps.

Example: Updating File Databases

In this example, we'll use /etc/portage/bashrc to call some file database applications to ensure their databases are up to date with the system. The applications used in the example are aide (an intrusion detection tool) and updatedb (to use with locate), but these are meant as examples. Do not consider this as a HOWTO for AIDE ;-)

To use /etc/portage/bashrc for this case, we need to "hook" in the postrm (after removal of files) and postinst (after installation of files) functions, because that is when the files on the file system have been changed.

Code Listing 3.1: Example /etc/portage/bashrc

if [ "${EBUILD_PHASE}" == "postinst" ] || [ "${EBUILD_PHASE}" == "postrm" ];
  echo ":: Calling aide --update to update its database";
  aide --update;
  echo ":: Calling updatedb to update its database";

6.d. Executing Tasks After --sync

The /etc/portage/postsync.d location

Until now we've talked about hooking into the ebuild processes. However, Portage also has another important function: updating the Portage tree. In order to run tasks after updating the Portage tree, put a script inside /etc/portage/postsync.d and make sure it is marked as executable.

Example: Running eix-update

If you didn't use eix-sync to update the tree, you can still have its database updated after running emerge --sync (or emerge-webrsync) by putting a symlink to /usr/bin/eix called eix-update in /etc/portage/postsync.d.

Code Listing 4.1: Running eix-update after a sync operation

# ln -s /usr/bin/eix /etc/portage/postsync.d/eix-update

Note: If you rather use a different name, you will need to make a script that calls /usr/bin/eix-update instead. The eix binary looks at how it has been called to find out which function it has to execute. If you put in a symlink to eix that isn't called eix-update, it will not run correctly.

6.e. Overriding Profile Settings

The /etc/portage/profile location

By default, Gentoo uses the settings contained in the profile pointed to by /etc/portage/make.profile (a symbolic link to the right profile directory). These profiles define both specific settings as well as inherit settings from other profiles (through their parent file).

By using /etc/portage/profile, you can override profile settings such as packages (what packages are considered to be part of the system set), forced use flags and more.

Example: Adding nfs-utils to the System Set

If you use NFS-based file systems for rather critical file systems, you might want to have net-fs/nfs-utils "protected" as a system package, causing Portage to heavily warn you if it would be deleted.

To accomplish that, we add the package to /etc/portage/profile/packages, prepended with a *:

Code Listing 5.1: /etc/portage/profile/packages content


6.f. Applying Non-Standard Patches

Using epatch_user

To manage several ebuilds in a similar manner, ebuild developers use eclasses (sort-of shell libraries) that define commonly used functions. One of these eclasses is eutils.eclass which offers an interesting function called epatch_user.

The epatch_user function applies source code patches that are found in /etc/portage/patches/<category>/<package>[-<version>[-<revision>]], whatever directory is found first. Sadly, not all ebuilds automatically call this function so just putting your patch in this location might not always work.

Luckily, with the information provided above, you can call this function by hooking into, for instance, the prepare phase. The function can be called as many times as you like - it will only apply the patches once.

Example: Applying Patches to Firefox

The www-client/firefox package is one of the few that already call epatch_user from within the ebuild, so you do not need to override anything specific.

If you need to patch firefox (for instance because a developer provided you with a patch and asked you to check if it fixes the bug you reported), put the patch in /etc/portage/patches/www-client/firefox (probably best to use the full name, including version so that the patch does not interfere with later versions) and rebuild firefox.

[ << ] [ < ] [ Home ] [ > ] [ >> ]


View all

Page updated April 11, 2013

Summary: As times goes by, Portage evolves and matures further and further. Additional features are continuously being put in - many of these are only of use by more advanced users. This chapter will go into more detail of these specific features.

Sven Vermeulen

Grant Goodyear

Roy Marples

Daniel Robbins

Chris Houser

Jerry Alexandratos

Seemant Kulleen
Gentoo x86 Developer

Tavis Ormandy
Gentoo Alpha Developer

Jason Huebel
Gentoo AMD64 Developer

Guy Martin
Gentoo HPPA developer

Tim Yamin
Gentoo IA64 developer

Pieter Van den Abeele
Gentoo PPC developer

Joe Kallar
Gentoo SPARC developer

Mike Frysinger
Gentoo * developer

John P. Davis

Pierre-Henri Jondot

Eric Stockbridge

Rajiv Manglani

Jungmin Seo

Stoyan Zhekov

Jared Hudson

Colin Morey

Jorge Paulo

Carl Anderson

Jon Portnoy

Zack Gilburd

Jack Morgan

Benny Chuang


Joshua Kinard

Stuart Longland

Tobias Scherbaum

Xavier Neys

Joshua Saddler

Gerald J. Normandin Jr.

Donnie Berkholz

Ken Nowack

Lars Weiler

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.