/etc/portage/bashrc

From Gentoo Wiki
< /etc‎ | portage(Redirected from Bashrc)
Jump to:navigation Jump to:search
Not to be confused with the ".bashrc" Bash configuration file.


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.

bashrc may be used to set up ebuild phase hooks, to perform specific actions at various stages of package installation, updates, or removal.

Caveats

Multiple calls

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. Therefore when code gets executed should be controlled by putting code into hook functions (e.g. pre_pkg_setup()).

Note
Do not rely on variables EBUILD_PHASE or EBUILD_PHASE_FUNC. Their value in global scope is not supposed to be the name of a phase; see bug #908552.

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, it should probably be avoided to blindly squash those by repeatedly resetting them with each phase function (except on a per-package basis, if this is really the desired bahviour).

Execution order

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.

Environment

Portage doesn't save the initial environment prior to being mangled by Portage's global make.defaults and make.globals. Therefore there is no direct way of determining whether an environment variable was supplied by the user (e.g. CFLAGS), or set by portage, so it can't be guaranteed using the environment by bashrc to control behavior.

Hooks

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
Important
Note that defining the pkg_postinst() function, for instance, would override the default expected eclass implementations. Instead create the pre_pkg_postinst() or post_pkg_postinst() functions, as an example.

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

Retrieved from "https://wiki.gentoo.org/index.php?title=/etc/portage/bashrc&oldid=1283090"