From Gentoo Wiki
< /etc/portage(Redirected from Bashrc)
Jump to:navigation Jump to:search

The /etc/portage/bashrc file is a global bashrc file referenced by Portage. It is similar to the bashrc files under /etc/portage/env/, except always sourced for every package. It can either be used to setup a global environment common to all ebuilds, or as an alternative to the /etc/portage/env files allowing Portage administrators to handle all the necessary conditional code manually.


  • It is important to note that this file will be sourced multiple times during the build, at least once per phase plus several other times. You must therefore control when your code is executed using e.g. EBUILD_PHASE, EBUILD_PHASE_FUNC (EAPI 5), or otherwise avoid using the global scope by only putting code into hook functions (e.g. pre_pkg_setup()). See bug 250240. It is especially important to restrict this in order to avoid unintentionally clobbering changes made throughout the ebuild. For example, if flag-o-matic code for a specific ebuild would normally overwrite default CFLAGS you've set, you wouldn't want to blindly squash those by repeatedly resetting them with each phase function (except on a per-package basis, when you know what you're doing).
  • The global bashrc isn't sourced for the first time until after dependency resolution. If run with --ask, bashrc is sourced for the first time shortly after interactive confirmation. Therefore, it isn't a complete replacement for the global make.conf. Anything that must be in the environment immediately can't be set by bashrc such as USE flags, FEATURES, etc. The portage documentation doesn't provide a complete list of contradictions, so be careful.
  • Portage doesn't save the initial environment prior to being mangled by Portage's global make.defaults and make.globals. You therefore have no direct way of determining whether an environment variable was supplied by the user (e.g. CFLAGS), or set by portage, so you can't guarantee using the environment by your bashrc to control behavior.


In order to execute self defined code during an ebuild, there are two distinct ways to hook into the ebuild process.

Environment variable

The environment variable EBUILD_PHASE changes during the ebuild process through the stages

  • clean
  • setup
  • unpack
  • prepare
  • configure
  • compile
  • test
  • install
  • instprep
  • preinst
  • prerm
  • cleanrm
  • postinst
  • clean

Similarly EBUILD_PHASE_FUNC runs through these stages during the ebuild process:

  • pkg_setup
  • src_unpack
  • src_prepare
  • src_configure
  • src_compile
  • src_test
  • src_install
  • pkg_preinst
  • pkg_prerm
  • pkg_postrm
  • pkg_postinst

In order to execute code at the setup stage, this could be put into bashrc for example:

FILE /etc/portage/bashrc
if [ "${EBUILD_PHASE}" == "setup" ]
  echo "your code here"

Hook functions

Portage automatically calls functions inside /etc/portage/bashrc if they are present. These functions bear the same name like the stages that EBUILD_PHASE_FUNC runs through, plus a prefix to determine when they run. The prefixes are "pre_" and "post_".

In order to execute the code at the beginning of the setup stage, this could be put into bashrc for example:

FILE /etc/portage/bashrc
function pre_pkg_setup() {
  echo "your code here"

Two additional hook functions are register_die_hook (called when an ebuild fails) and register_success_hook (called when an ebuild is successfully merged) which have a slightly different usage:

FILE /etc/portage/bashrc
register_success_hook mySuccessHook
function mySuccessHook {
    echo "success!"

register_die_hook myDieHook
function myDieHook {
    echo "failure!"

However, note that only an ebuild that is emerged completely flawless is considered a success enough to call the functions that are registered. For example a file collision detection during a build is enough for this function not to be called, even though emerge runs through the whole merge process successfully.

See also