This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Handbook:Alpha/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:
user $man portage
user $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 to mention these when hitting a bug and opening a bug report.
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, it might be beneficial 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 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 /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, 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.
/etc/portage/env/debug-cflagsSpecific variables for debuggingCFLAGS="-O2 -ggdb -pipe" FEATURES="${FEATURES} nostrip"
Next, we tag the media-video/mplayer package to use this content:
/etc/portage/package.envUsing debug-cflags for the mplayer packagemedia-video/mplayer debug-cflags
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 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 /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, additional steps/functions can then be executed.
Example: Updating the file database
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 mlocate), but these are meant as examples. Do not consider this as a guide 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.
/etc/portage/bashrcHooking into the postinst and postrm phasesif [ "${EBUILD_PHASE}" == "postinst" ] || [ "${EBUILD_PHASE}" == "postrm" ]; then echo ":: Calling aide --update to update its database" aide --update echo ":: Calling updatedb to update its database" updatedb fi
Executing tasks after --sync
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 Gentoo repository. In order to run tasks after updating the Gentoo repository, put a script inside /etc/portage/postsync.d and make sure it is marked as executable.
Example: Running eix-update
If eix-sync was not used to update the tree, then it is still possible to update the eix database after running emerge --sync (or emerge-webrsync) by putting a symlink to /usr/bin/eix called eix-update in /etc/portage/postsync.d.
root #ln -s /usr/bin/eix /etc/portage/postsync.d/eix-updateIf a different name would be chosen, then it needs to be 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 a symlink would be created that points to eix yet isn't called eix-update, it will not run correctly.
Overriding profile settings
Using /etc/portage/profile
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, 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 net-fs/nfs-utils 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 /etc/portage/profile/packages, prepended with a *:
/etc/portage/profile/packagesMarking nfs-utils as a system package*net-fs/nfs-utils
Applying non-standard patches
Using epatch_user
The
epatch_user function is applicable to EAPIs less than or equal to 5, see the eapply_user function for EAPIs greater than or equal to 6.To manage several ebuilds in a similar manner, ebuild developers use eclasses (which are shell libraries) that define commonly used functions. One of these eclasses is epatch.eclass which offers a helpful 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 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 www-client/firefox 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 /etc/portage/patches/www-client/firefox (probably best to use the full name and version so that the patch does not interfere with later versions) and rebuild Firefox.