&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, they will either be executed before

		or after that particular stage. The hooks inside each directory

		will be executed by bash. 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>

		A hook is presently not allowed to alter portage's execution,

		but they can supplement it with additional functionality. Since

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

		process ID, which can be used to kill the parent (nicely,

		please) if absolutely needed. This might be useful in a pre-sync

		script.

		</para>

		<para>

		When a hook is called, any of the following arguments are

		passed:

		<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>

		As of this writing, the following hook directories are

		supported. It can be assumed that the above arguments apply

		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> - yet to be implemented</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>

		<programlisting>

		#!/bin/bash

		einfo "This is an example hook."

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

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

				:

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

				:

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

				:

			else

				ewarn "Unknown hook option: $1 $2"

			fi

			shift 2

		done

		</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 a hook set everything up before we do anything more

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

	portage.hooks.HookDirectory(phase='pre-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$

# TODO: following may be harmful, but helpful for debugging

#import os, sys

#import os.path as osp

#sys.path.insert(0, osp.dirname(osp.dirname(osp.abspath(__file__))))

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)

if __name__ == "__main__": # TODO: debug

	from portage.package.ebuild.config import config

	HookDirectory('run', config()).execute()

from portage.hooks import HookDirectory

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

			return retval

			return retval

			return retval

# 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