Handbook:Parts/Portage/Advanced

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 can then be bended to fit personal needs. More tweaks and tips can be found all over the Gentoo Wiki.

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

Finally, know that these are advanced features which, if not worked with correctly, can make debugging and troubleshooting very difficult. Make sure to mention these when hitting a bug and opening a bugreport.

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

The file contains the list of packages for which deviating environment variables are needed as well as a specific identifier that tells portage which changes to make. The identifier name is free format, and portage will look for the variables in the file.

Example: Using debugging for specific packages
As an example, we enable debugging for the package.

First of all, set the debugging variables in a file called. 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.

Next, we tag the package to use this content:

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 users to set up a specific bash environment.

The advantage of using a specific bash environment is that it allows users to hook in the emerge process during each step it performs. This can be done for every emerge (through ) or by using per-package environments (through 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, additional steps/functions can then be executed.

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

To use 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.

Using /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 and make sure it is marked as executable.

Example: Running eix-update
If  was not used to update the tree, then it is still possible to update the eix database after running   (or  ) by putting a symlink to  called  in.

Using /etc/portage/profile
By default, Gentoo uses the settings contained in the profile pointed to by (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, users 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
When using an NFS-based file systems for rather critical file systems, it might be necessary to mark as a system package, causing portage to heavily warn administrators if they would attempt to unmerge it.

To accomplish that, we add the package to, prepended with a *:

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 which offers an interesting function called epatch_user.

The epatch_user function applies source code patches that are found in, whatever directory is found first. Sadly, not all ebuilds automatically call this function so just putting a patch in this location might not always work.

Luckily, with the information provided earlier in this chapter, users can call this function by hooking into, for instance, the prepare phase. The function can be called as many times as necessary - it will only apply the patches once.

Example: Applying patches to firefox
The package is one of the many that already call epatch_user from within the ebuild, so there is no need to override anything specific.

If for some reason (for instance because a developer provided a patch and asked to check if it fixes the bug reported) patching firefox is wanted, all that is needed is to put the patch in (probably best to use the full name and version so that the patch does not interfere with later versions) and rebuild firefox.