&config_hooks;

<chapter id='config-hooks'>

	<title>Hooks Configuration</title>

	<sect1 id='config-hooks-locations'>

		<title>Hooks Locations</title>

		<para>

		If a hook directory exists, the bash scripts within each one

		wil either be executed before or after that particular stage, in

		alphabetical order. Each one will receive the environment of an

		ebuild, so they are capable of inherit, einfo, and other common

		commands (if you find them useful). Avoid commands that may

		trigger changes in the filesystem!

		</para>

		<para>

		All hooks are not allowed to directly alter portage's execution,

		but they can accomplish certain extra tasks at various points,

		which might indrectly alter portage's execution. Since hooks

		execute in a bash environment, they are told the parent process

		ID, which can be used to kill portage if absolutely needed. This

		might be useful if a hook handled the rest of a certain job,

		such as syncing, and portage's default behavior is undesired, or

		if a hook caught potential problems with the rest of portage's

		execution.

		</para>

		<para>

		A hook script is expected to understand the following usage:

		<cmdsynopsis>

			<command>/bin/bash <replaceable>...</replaceable></command><sbr/>

			<arg>--opt <replaceable>portage arguments, always translated to long form, given by user at the prompt, such as "--verbose" or "--newuse"</replaceable></arg><sbr/>

			<arg>--action <replaceable>a single action being performed by portage, such as "depclean", "sync", or an ebuild phase</replaceable></arg><sbr/>

			<arg>--target <replaceable>the thing to perform the action with or on</replaceable></arg>

		</cmdsynopsis>

		</para>

		<para>

		The following hook directories are supported. The standard hook

		script usage applies, except wherever described differently.

		</para>

		<itemizedlist>

			<listitem><para><filename>/etc/portage/hooks/pre-ebuild.d/</filename> - executed before every ebuild execution. Never receives --opt, and --target is set to the full path of the ebuild.</para></listitem>

			<listitem><para><filename>/etc/portage/hooks/post-ebuild.d/</filename> - executed after every ebuild execution. Never receives --opt, and --target is set to the full path of the ebuild.</para></listitem>

			<listitem><para><filename>/etc/portage/hooks/pre-run.d/</filename> - executed before portage considers most things, including proper permissions and validity of arguments.</para></listitem>

			<listitem><para><filename>/etc/portage/hooks/post-run.d/</filename> - executed after portage is done. It should run regardless of any errors or signals sent, but this cannot be guaranteed for certain scenarios (such as when the KILL signal is received). No information is available concerning the reason portage is exiting. This is a limitation of python itself.</para></listitem>

			<listitem><para><filename>/etc/portage/hooks/pre-sync.d/</filename> - executed before portage synchronizes the portage tree.</para></listitem>

			<listitem><para><filename>/etc/portage/hooks/post-sync.d/</filename> - executed after portage has successfully synchronized the portage tree. Presently you must use a combination of pre-sync and post-run to catch sync failures if desired.</para></listitem>

		</itemizedlist>

	</sect1>

	<sect1 id='config-hooks-skeleton-hook'>

		<title>Skeleton Hook</title>

		<para>

		Most hooks will parse the options at the beginning and look for

		specific things. This skeleton hook provides that functionality

		to get you started. Replace the colons with actual code where

		desired.

		</para>

		<para>

		It's highly recommended that --verbose, --debug, and --quiet be

		utilized for suppressing or adding to "regular" output. The

		following skeleton hook already has example code in place to

		handle these flags.

		</para>

		<programlisting>

		#!/bin/bash

		verbose_redirect="/dev/null"

		debug_redirect="/dev/null"

		while [[ "$1" != "" ]]; do

			if [[ "$1" == "--opt" ]]; then

				if [[ "$2" == "--verbose" ]]; then

					verbose_redirect="/dev/tty"

				fi

				if [[ "$2" == "--debug" ]]; then

					debug_redirect="/dev/tty"

				fi

				if [[ "$2" == "--quiet" ]]; then

					verbose_redirect="/dev/null"

					debug_redirect="/dev/null"

				fi

			elif [[ "$1" == "--action" ]]; then

				:

			elif [[ "$1" == "--target" ]]; then

				:

			else

				ewarn "Unknown hook option: $1 $2" > "${verbose_redirect}" 2>&1

			fi

			shift 2

		done

		einfo "This is an example hook." > "${verbose_redirect}" 2>&1

		einfo "This is debug output." > "${debug_redirect}" 2>&1

		</programlisting>

	</sect1>

</chapter>

	<!ENTITY config_hooks SYSTEM "config/hooks.docbook">

.BR /etc/portage/hooks/

portage pre/post hooks

.TP

.BR /etc/portage/hooks/

.RS

In this directory, portage hooks are executed before each ebuild phase,

before and after synchronization, and before and after portage runs

themselves. Please see the DocBook documentation for detailed

information.

.RE

.TP

from portage.hooks import HookDirectory

	HookDirectory(phase='pre-sync', settings=settings, myopts=myopts, myaction=myaction).execute()

	HookDirectory(phase='post-sync', settings=settings, myopts=myopts, myaction=myaction).execute()

import portage.hooks

import portage.process

	# Portage configured; let's let hooks run before we do anything more

	portage.hooks.HookDirectory(phase='pre-run', settings=settings, myopts=myopts, myaction=myaction, mytargets=myfiles).execute()

	settings, trees, mtimedb = load_emerge_config() # once more, since pre-run might've done something

	# Have post-run hooks executed whenever portage quits

	portage.process.atexit_register(portage.hooks.HookDirectory(phase='post-run', settings=settings, myopts=myopts, myaction=myaction, mytargets=myfiles).execute)

HOOKS_PATH               = USER_CONFIG_PATH + "/hooks"

# Copyright 1998-2010 Gentoo Foundation

# Distributed under the terms of the GNU General Public License v2

# $Id$

from portage.const import BASH_BINARY, HOOKS_PATH, PORTAGE_BIN_PATH

from portage import os

from portage import check_config_instance

from portage import normalize_path

from portage.exception import PortageException

from portage.exception import InvalidLocation

from portage.output import EOutput

from process import spawn

class HookDirectory(object):

	def __init__ (self, phase, settings, myopts=None, myaction=None, mytargets=None):

		self.myopts = myopts

		self.myaction = myaction

		self.mytargets = mytargets

		check_config_instance(settings)

		self.settings = settings

		self.path = os.path.join(settings["PORTAGE_CONFIGROOT"], HOOKS_PATH, phase + '.d')

		self.output = EOutput()

	def execute (self, path=None):

		if not path:

			path = self.path

		path = normalize_path(path)

		if not os.path.exists(path):

			if self.myopts and "--debug" in self.myopts:

				self.output.ewarn('This hook path could not be found; ignored: ' + path)

			return

		if os.path.isdir(path):

			for parent, dirs, files in os.walk(path):

				for dir in dirs:

					if self.myopts and "--debug" in self.myopts:

						self.output.ewarn('Directory within hook directory not allowed; ignored: ' + path+'/'+dir)

				for filename in files:

					HookFile(os.path.join(path, filename), self.settings, self.myopts, self.myaction, self.mytargets).execute()

		else:

			raise InvalidLocation('This hook path ought to be a directory: ' + path)

class HookFile (object):

	def __init__ (self, path, settings, myopts=None, myaction=None, mytargets=None):

		self.myopts = myopts

		self.myaction = myaction

		self.mytargets = mytargets

		check_config_instance(settings)

		self.path = normalize_path(path)

		self.settings = settings

		self.output = EOutput()

	def execute (self):

		if "hooks" not in self.settings['FEATURES']:

			return

		if not os.path.exists(self.path):

			raise InvalidLocation('This hook path could not be found: ' + self.path)

		if os.path.isfile(self.path):

			command=[self.path]

			if self.myopts:

				for myopt in self.myopts:

					command.extend(['--opt', myopt])

			if self.myaction:

				command.extend(['--action', self.myaction])

			if self.mytargets:

				for mytarget in self.mytargets:

					command.extend(['--target', mytarget])

			command=[BASH_BINARY, '-c', 'source ' + PORTAGE_BIN_PATH + '/isolated-functions.sh && source ' + ' '.join(command)]

			if self.myopts and "--verbose" in self.myopts:

				self.output.einfo('Executing hook "' + self.path + '"...')

			code = spawn(mycommand=command, env=self.settings.environ())

			if code: # if failure

				raise PortageException('!!! Hook %s failed with exit code %s' % (self.path, code))

		else:

			raise InvalidLocation('This hook path ought to be a file: ' + self.path)

from portage.hooks import HookDirectory

		HookDirectory(phase='pre-ebuild', settings=mysettings, myopts=None, myaction=mydo, mytargets=[mysettings["EBUILD"]]).execute()

		HookDirectory(phase='post-ebuild', settings=mysettings, myopts=None, myaction=mydo, mytargets=[mysettings["EBUILD"]]).execute()

# tests/portage/hooks/__init__.py -- Portage Unit Test functionality

# Copyright 2010 Gentoo Foundation

# Distributed under the terms of the GNU General Public License v2

# $Id$

# test_HookDirectory.py -- Portage Unit Testing Functionality

# Copyright 2010 Gentoo Foundation

# Distributed under the terms of the GNU General Public License v2

# $Id$

from portage import os

from portage.hooks import HookDirectory

from portage.package.ebuild.config import config

from portage.tests import TestCase

from tempfile import mkdtemp

from shutil import rmtree

# http://stackoverflow.com/questions/845058/how-to-get-line-count-cheaply-in-python

def file_len(fname):

    with open(fname) as f:

        for i, l in enumerate(f):

            pass

    return i + 1

class HookDirectoryTestCase(TestCase):

	def testHookDirectory(self):

		"""

		Tests to be sure a hook loads and reads the right settings

		Based on test_PackageKeywordsFile.py

		"""

		tmp_dir_path = self.BuildTmp('/etc/portage/hooks/test.d')

		try:

			settings = config()

			settings["PORTAGE_CONFIGROOT"] = tmp_dir_path

			settings["FEATURES"] += " hooks"

			hooks = HookDirectory('test', settings)

			hooks.execute()

			self.assert_(file_len(tmp_dir_path+'/output') == 1)

		finally:

			rmtree(tmp_dir_path)

	def BuildTmp(self, tmp_subdir):

		tmp_dir = mkdtemp()

		hooks_dir = tmp_dir + '/' + tmp_subdir

		os.makedirs(hooks_dir)

		f = open(hooks_dir+'/testhook', 'w')

		f.write('#!/bin/bash\n')

		f.write('echo hi > '+tmp_dir+'/output && exit 0\n')

		f.close()

		return tmp_dir