Handbook:Parts/Portage/Advanced

From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.
Warning
Do not try to follow instructions directly from the Handbook:Parts namespace (WHICH THIS PAGE!), or any of its sub-pages. The Handbook:Parts is a meta handbook used for transcluding text into other Handbooks. Use the architecture-specific Handbooks found in the Handbook list for complete installation instructions.
Parts Handbook
Installation
About the installation
Choosing the media
Configuring the network
Preparing the disks
Installing stage3
Installing base system
Configuring the kernel
Configuring the system
Installing tools
Configuring the bootloader
Finalizing
Working with Gentoo
Portage introduction
USE flags
Portage features
Initscript system
Environment variables
Working with Portage
Files and directories
Variables
Mixing software branches
Additional tools
Custom package repository
Advanced features
Network configuration
Getting started
Advanced configuration
Modular networking
Wireless
Adding functionality
Dynamic management


Introduction

For most readers, 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 customization purposes or are only applicable in specific corner cases.

Of course, with lots of flexibility comes a huge list of potential cases. It will not be possible to document them all here. Instead, the goal is to focus on some generic issues which can then be augmented to fit a particular niche. More tweaks and tips such as these can be found across the Gentoo wiki.

Most, if not all, of these additional features can be easily found by digging through the manual pages that are provided with Portage:

user $man portage
user $man make.conf

Finally, know that these are advanced features which, if not configured correctly, can make debugging and troubleshooting much more difficult. Be sure any of these sorts of customizations are explicitly mentioned when 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 others. In some cases, it is beneficial to provide different variables for specific packages. To do so, Portage supports the use of the /etc/portage/env directory and /etc/portage/package.env file.

The /etc/portage/package.env file contains a list of packages for which deviating environment variables are needed as well as a specific identifier that indicates to Portage which identifier file to apply. The identifier name is free format. Portage will look for a file with the exactly same case-sensitive name as the identifier. See the following example for more detail.

Example: Using debugging for specific packages

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

Set the debugging variables in a file called /etc/portage/env/debug-cflags. The filename is arbitrarily chosen, but of course the name reflects the purpose of the file, which should make it obvious if reviewing later why the file exists. The /etc/portage/env directory will need created if it does not yet exist:

root #mkdir /etc/portage/env
FILE /etc/portage/env/debug-cflagsSet specific variables for debugging
# Add -ggdb to CFLAGS for debugging 
CFLAGS="-O2 -ggdb -pipe"
FEATURES="${FEATURES} nostrip"

Next, the media-video/mplayer package is 'tagged' to use the new debug identifier in the package.env file:

FILE /etc/portage/package.envUse the debug-cflags identifier for the mplayer package
media-video/mplayer debug-cflags

Hooking into 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.). Portage allows system administrators to set up a specific bash environment.

The advantage of using a specific bash environment is that it allows for hooks into 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 and/or functions can be executed.

Example: Updating the file database

In this example, the /etc/portage/bashrc file will be used to call some file database applications in order 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.

FILE /etc/portage/bashrcHooking into the postinst and postrm phases
if [ "${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 ebuild repository syncs

Using /etc/portage/postsync.d location

In addition to hooking into the ebuild phases, Portage offers another option for hook functionality: postsync.d. These types of hooks are run after updating, also referred to as syncing, the Gentoo ebuild repository. In order to run tasks after updating the Gentoo repository, put scripts inside the /etc/portage/postsync.d directory. Be sure any files inside the directory have been marked as executable or they will not run.

Example: Running eix-update

If eix-sync was not used to update sync the repository, 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-update
Note
If 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 determine which function to execute. If a symlink would be created that points to eix yet is not 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, which is a symbolic link to the a target profile directory. These profiles define both specific settings as well as inherit settings from other profiles (through their parent files).

By using /etc/portage/profile, system administrators 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 critical file systems, it might be necessary to mark net-fs/nfs-utils as a system package, which will cause Portage to heavily warn administrators in the event they would attempt to unmerge it.

To accomplish this, the package must be added to the /etc/portage/profile/packages file, prepended with a * (asterisk symbol):

FILE /etc/portage/profile/packagesMarking net-fs/nfs-utils as a system package
*net-fs/nfs-utils

Applying non-standard patches

Using eapply_user

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 eapply_user function applies source code patches that are found in /etc/portage/patches/<category>/<package>[-<version>[-<revision>]], whatever directory is found first.

For legacy (pre-EAPI 6) ebuilds, 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 eapply_user (possibly implicitly) 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.