Line 0
Link Here
|
|
|
1 |
<chapter id='config-hooks'> |
2 |
<title id="config-hooks.title">Hooks Configuration</title> |
3 |
|
4 |
<sect1 id='config-hooks-execution'> |
5 |
<title id="config-hooks-execution.title">Hooks Execution</title> |
6 |
|
7 |
<para>Hooks are only executed if <quote>hooks</quote> is set in |
8 |
FEATURES.</para> |
9 |
|
10 |
<para> |
11 |
If a hook directory exists, the bash scripts within each one |
12 |
wil either be executed before or after that particular phase, in |
13 |
alphabetical order. Each one will receive the environment of an |
14 |
ebuild, so they are capable of inherit, einfo, and other common |
15 |
commands (if you find them useful). For non-ebuild hooks, avoid |
16 |
commands that may trigger changes in the filesystem! |
17 |
</para> |
18 |
|
19 |
<para> |
20 |
Ebuild hooks are executed within ebuild.sh, so they receive the |
21 |
same sandbox limitations as ebuilds. |
22 |
</para> |
23 |
|
24 |
<para> |
25 |
A hook script is expected to understand the following usage: |
26 |
<cmdsynopsis> |
27 |
<command>/bin/bash <replaceable>...</replaceable></command><sbr/> |
28 |
|
29 |
<arg>--opt <replaceable>portage arguments, always translated to long form, given by user at the prompt, such as "--verbose" or "--newuse"</replaceable></arg><sbr/> |
30 |
|
31 |
<arg>--action <replaceable>a single action being performed by portage, such as "depclean", "sync", or an ebuild phase</replaceable></arg><sbr/> |
32 |
|
33 |
<arg>--target <replaceable>the thing to perform the action with or on</replaceable></arg> |
34 |
</cmdsynopsis> |
35 |
</para> |
36 |
|
37 |
<para> |
38 |
Some hook types have slightly different usage. See <quote> |
39 |
<link linkend='config-hooks-locations' endterm="config-hooks-locations.title"/></quote> for more |
40 |
information. |
41 |
</para> |
42 |
|
43 |
</sect1> |
44 |
|
45 |
<sect1 id='config-hooks-locations'> |
46 |
<title id="config-hooks-locations.title">Hooks Locations</title> |
47 |
<para> |
48 |
The following hook directories are supported. Each directory |
49 |
corresponds to a specific type, such as <quote>ebuild</quote> or |
50 |
<quote>run</quote>. The standard hook script usage applies given |
51 |
in <link linkend='config-hooks-execution' endterm="config-hooks-execution.title"/>, |
52 |
except wherever described differently below. |
53 |
</para> |
54 |
|
55 |
<itemizedlist> |
56 |
<listitem><para><filename>/etc/portage/hooks/pre-ebuild.d/</filename> - executed before every ebuild phase execution, within ebuild.sh itself. Never receives --opt, and --target is set to the full path of the ebuild.</para></listitem> |
57 |
<listitem><para><filename>/etc/portage/hooks/post-ebuild.d/</filename> - executed after every ebuild phase execution. Never receives --opt, and --target is set to the full path of the ebuild.</para></listitem> |
58 |
<listitem><para><filename>/etc/portage/hooks/pre-run.d/</filename> - executed before portage considers most things, including proper permissions and validity of parsed arguments.</para></listitem> |
59 |
<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> |
60 |
<listitem><para><filename>/etc/portage/hooks/pre-sync.d/</filename> - executed before portage synchronizes the portage tree.</para></listitem> |
61 |
<listitem><para><filename>/etc/portage/hooks/post-sync.d/</filename> - executed after portage has <emphasis>successfully</emphasis> synchronized the portage tree. If you want to catch a sync failure, use post-run.</para></listitem> |
62 |
</itemizedlist> |
63 |
</sect1> |
64 |
|
65 |
<sect1 id='config-hooks-skeleton-hook'> |
66 |
<title id="config-hooks-skeleton-hook.title">Skeleton Hook</title> |
67 |
<para> |
68 |
Most hooks will parse the options at the beginning and look for |
69 |
specific things. This skeleton hook provides that functionality |
70 |
to get you started. |
71 |
</para> |
72 |
<para> |
73 |
It's highly recommended that --verbose, --debug, and --quiet be |
74 |
utilized for suppressing or adding to <quote>regular</quote> |
75 |
output. The following skeleton hook already has example code in |
76 |
place to handle these flags. |
77 |
</para> |
78 |
<programlisting> |
79 |
#!/bin/bash |
80 |
|
81 |
verbose_redirect="/dev/null" |
82 |
debug_redirect="/dev/null" |
83 |
while [[ "$1" != "" ]]; do |
84 |
if [[ "$1" == "--opt" ]]; then |
85 |
if [[ "$2" == "--verbose" ]]; then |
86 |
verbose_redirect="/dev/tty" |
87 |
fi |
88 |
if [[ "$2" == "--debug" ]]; then |
89 |
debug_redirect="/dev/tty" |
90 |
fi |
91 |
if [[ "$2" == "--quiet" ]]; then |
92 |
verbose_redirect="/dev/null" |
93 |
debug_redirect="/dev/null" |
94 |
fi |
95 |
elif [[ "$1" == "--action" ]]; then |
96 |
: # do nothing |
97 |
elif [[ "$1" == "--target" ]]; then |
98 |
: # do nothing |
99 |
else |
100 |
ewarn "Unknown hook option: $1 $2" &> "${verbose_redirect}" |
101 |
fi |
102 |
shift 2 |
103 |
done |
104 |
einfo "This is an example hook." &> "${verbose_redirect}" |
105 |
einfo "This is debug output." &> "${debug_redirect}" |
106 |
</programlisting> |
107 |
</sect1> |
108 |
</chapter> |