aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-05 02:26:41 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-05 02:26:41 +0000
commitecf0dd5a32ab71fafbf748e28cc33db8b7255c18 (patch)
tree45def74fc07717fe25d28906f9485672df9156a8
parenta9eb6927559788f9b90f8fecaa9f9f61a06c02b7 (diff)
downloadpaludis-ecf0dd5a32ab71fafbf748e28cc33db8b7255c18.tar.gz
paludis-ecf0dd5a32ab71fafbf748e28cc33db8b7255c18.tar.xz
Document hooks
Diffstat
-rw-r--r--doc/Makefile.am19
-rw-r--r--doc/fetchers.html.skel179
-rw-r--r--doc/index.html.skel3
3 files changed, 195 insertions, 6 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6ef72a4..b519618 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -23,18 +23,20 @@ htmlfiles = \
configuration.html \
portagedifferences.html \
programmingwithpaludis.html \
- sets.html
+ sets.html \
+ hooks.html
EXTRA_DIST = doxygen.conf.in header.html footer.html paludis.css \
$(docfiles) $(tagfiles) htaccess \
news.html.skel index.html.skel changelog.html.skel licence.html.skel authors.html.skel \
faq.html.skel htmlheader.html htmlfooter.html migration.html.skel cachefiles.html.skel \
configuration.html.skel portagedifferences.html.skel programmingwithpaludis.html.skel \
- sets.html.skel
+ sets.html.skel hooks.html.skel
CLEANFILES = *~ news.html index.html changelog.html licence.html authors.html faq.html \
migration.html cachefiles.html configuration.html portagedifferences.html programmingwithpaludis.html \
- sets.html cleannews cleanchangelog cleanauthors cleanfaqtoc cleanbasiccppapp cleanbasicrubyapp
+ sets.html hooks.html.skel \
+ cleannews cleanchangelog cleanauthors cleanfaqtoc cleanbasiccppapp cleanbasicrubyapp
MAINTAINERCLEANFILES = Makefile.in $(tagfiles)
@@ -143,12 +145,19 @@ configuration.html : configuration.html.skel htmlheader.html htmlfooter.html
-e '/@FOOTER@/d' \
< $(srcdir)/configuration.html.skel > configuration.html
-sets.html :sets.html.skel htmlheader.html htmlfooter.html
+sets.html : sets.html.skel htmlheader.html htmlfooter.html
sed -e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
-e '/@FOOTER@/r htmlfooter.html' \
-e '/@FOOTER@/d' \
- < $(srcdir)/sets.html.skel >sets.html
+ < $(srcdir)/sets.html.skel > sets.html
+
+hooks.html : hooks.html.skel htmlheader.html htmlfooter.html
+ sed -e '/@HEADER@/r htmlheader.html' \
+ -e '/@HEADER@/d' \
+ -e '/@FOOTER@/r htmlfooter.html' \
+ -e '/@FOOTER@/d' \
+ < $(srcdir)/hooks.html.skel > hooks.html
migration.html : migration.html.skel htmlheader.html htmlfooter.html
sed -e '/@HEADER@/r htmlheader.html' \
diff --git a/doc/fetchers.html.skel b/doc/fetchers.html.skel
new file mode 100644
index 0000000..90238d6
--- /dev/null
+++ b/doc/fetchers.html.skel
@@ -0,0 +1,179 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html lang="en" xml:lang="en">
+<head>
+<title>Paludis, the Other Package Mangler</title>
+<link rel="stylesheet" href="paludis.css" type="text/css" />
+</head>
+<body>
+@HEADER@
+
+<h1>Paludis, the Other Package Mangler</h1>
+
+<h2>Hooks</h2>
+
+<h3>Overview</h3>
+
+<p>This document describes the Paludis hooks interface. A hook is a piece of code
+that is executed when a particular well defined action occurs.</p>
+
+<p>There are currently three categories of hook:</p>
+
+<ul>
+ <li>General hooks. These have access to a limited environment.</li>
+
+ <li>Ebuild phase hooks. These have <code>ebuild</code> in the hook name, and
+ have full access to the ebuild environment (including the ability to call
+ <code>die</code>), but are only used for ebuild-based activities.</li>
+
+ <li>Ebuild message hooks. These are special hooks that are called for
+ <code>einfo</code>, <code>ewarn</code> etc.</li>
+</ul>
+
+<h3>Available Hooks</h3>
+
+<h4>General Hooks</h4>
+
+<p>The following general normal hooks are available:</p>
+
+<ul>
+ <li><code>install_pre</code></li>
+ <li><code>install_fail</code></li>
+ <li><code>install_post</code></li>
+ <li><code>install_all_pre</code></li>
+ <li><code>install_all_post</code></li>
+ <li><code>install_pretend_pre</code></li>
+ <li><code>install_pretend_post</code></li>
+ <li><code>uninstall_pre</code></li>
+ <li><code>uninstall_fail</code></li>
+ <li><code>uninstall_post</code></li>
+ <li><code>uninstall_all_pre</code></li>
+ <li><code>uninstall_all_post</code></li>
+ <li><code>sync_pre</code></li>
+ <li><code>sync_fail</code></li>
+ <li><code>sync_post</code></li>
+ <li><code>sync_all_pre</code></li>
+ <li><code>sync_all_post</code></li>
+ <li><code>fetch_pre</code></li>
+ <li><code>fetch_post</code></li>
+ <li><code>fetch_all_pre</code></li>
+ <li><code>fetch_all_post</code></li>
+</ul>
+
+<p>In general, certain special environment variables will be set. <code>HOOK</code> will contain
+the name of the hook. For <code>all</code> hooks, <code>TARGETS</code> will contain the targets
+for the operation. For non-<code>all</code> hooks, <code>TARGET</code> will contain the current
+target.</p>
+
+<h4>Ebuild Hooks</h4>
+
+<p>The following ebuild hooks are available:</p>
+
+<ul>
+ <li><code>ebuild_metadata_pre</code></li>
+ <li><code>ebuild_metadata_fail</code></li>
+ <li><code>ebuild_metadata_post</code></li>
+ <li><code>ebuild_init_pre</code></li>
+ <li><code>ebuild_init_fail</code></li>
+ <li><code>ebuild_init_post</code></li>
+ <li><code>ebuild_fetch_pre</code></li>
+ <li><code>ebuild_fetch_fail</code></li>
+ <li><code>ebuild_fetch_post</code></li>
+ <li><code>ebuild_merge_pre</code></li>
+ <li><code>ebuild_merge_fail</code></li>
+ <li><code>ebuild_merge_post</code></li>
+ <li><code>ebuild_unmerge_pre</code></li>
+ <li><code>ebuild_unmerge_fail</code></li>
+ <li><code>ebuild_unmerge_post</code></li>
+ <li><code>ebuild_tidyup_pre</code></li>
+ <li><code>ebuild_tidyup_fail</code></li>
+ <li><code>ebuild_tidyup_post</code></li>
+ <li><code>ebuild_strip_pre</code></li>
+ <li><code>ebuild_strip_fail</code></li>
+ <li><code>ebuild_strip_post</code></li>
+ <li><code>ebuild_unpack_pre</code></li>
+ <li><code>ebuild_unpack_fail</code></li>
+ <li><code>ebuild_unpack_post</code></li>
+ <li><code>ebuild_compile_pre</code></li>
+ <li><code>ebuild_compile_fail</code></li>
+ <li><code>ebuild_compile_post</code></li>
+ <li><code>ebuild_install_pre</code></li>
+ <li><code>ebuild_install_fail</code></li>
+ <li><code>ebuild_install_post</code></li>
+ <li><code>ebuild_test_pre</code></li>
+ <li><code>ebuild_test_fail</code></li>
+ <li><code>ebuild_test_post</code></li>
+ <li><code>ebuild_setup_pre</code></li>
+ <li><code>ebuild_setup_fail</code></li>
+ <li><code>ebuild_setup_post</code></li>
+ <li><code>ebuild_config_pre</code></li>
+ <li><code>ebuild_config_fail</code></li>
+ <li><code>ebuild_config_post</code></li>
+ <li><code>ebuild_nofetch_pre</code></li>
+ <li><code>ebuild_nofetch_fail</code></li>
+ <li><code>ebuild_nofetch_post</code></li>
+ <li><code>ebuild_preinst_pre</code></li>
+ <li><code>ebuild_preinst_fail</code></li>
+ <li><code>ebuild_preinst_post</code></li>
+ <li><code>ebuild_postinst_pre</code></li>
+ <li><code>ebuild_postinst_fail</code></li>
+ <li><code>ebuild_postinst_post</code></li>
+ <li><code>ebuild_prerm_pre</code></li>
+ <li><code>ebuild_prerm_fail</code></li>
+ <li><code>ebuild_prerm_post</code></li>
+ <li><code>ebuild_postrm_pre</code></li>
+ <li><code>ebuild_postrm_fail</code></li>
+ <li><code>ebuild_postrm_post</code></li>
+</ul>
+
+<p>As well as the full ebuild environment, the <code>HOOK</code> environment variable
+will contain the name of the hook being called.</p>
+
+<h4>Ebuild Message Hooks</h4>
+
+<p>The following ebuild message hooks are available:</p>
+
+<ul>
+ <li><code>einfo</code></li>
+ <li><code>ewarn</code></li>
+ <li><code>eerror</code></li>
+ <li><code>elog</code></li>
+</ul>
+
+<p>The <code>HOOK</code> environment variable will contain the name of the hook
+being called, and the <code>MESSAGE</code> environment variable will contain the
+message being passed to the function.</p>
+
+<h3>User Defined Hooks</h3>
+
+<p>User defined hooks should be executable (<code>chmod a+x</code>) scripts named
+<code>*.bash</code>. They can live in two locations (or be symlinked there, to
+allow a single script to be shared between hooks):</p>
+
+<ul>
+ <li><code><em>confdir</em>/hooks/<em>hookname</em>/</code>, where
+ <code><em>confdir</em></code> is the directory in which <code>use.conf</code>
+ et al. reside.</li>
+
+ <li><code><em>DATADIR</em>/paludis/hooks/<em>hookname</em>/</code>. On most
+ systems, <code><em>DATADIR</em></code> is <code>/usr/share</code>.</li>
+</ul>
+
+<h3>Package Manager Defined Hooks</h3>
+
+<p>Paludis places some of its own hooks in
+<code><em>LIBEXECDIR</em>/hooks/<em>hookname</em></code>. These directories are
+not for end user use.</p>
+
+<h3>Example Hooks</h3>
+
+<p>Paludis ships certain example hooks that many users would find useful, but that
+are not suitably general to be enabled by default -- these live in
+<code>DATADIR/paludis/hooks/demos/</code>. You may also find the default
+hooks useful -- these live in various places in <code>LIBEXECDIR/paludis/hooks/</code>.</p>
+
+@FOOTER@
+</body>
+</html>
+
+
diff --git a/doc/index.html.skel b/doc/index.html.skel
index d78dd52..650e2c2 100644
--- a/doc/index.html.skel
+++ b/doc/index.html.skel
@@ -37,7 +37,8 @@
<li>There is <a href="configuration.html">documentation on the
configuration files</a> and <a href="cachefiles.html">the
various optional caches</a> used by Paludis. There is also documentation on
- <a href="sets.html">sets (including how user defined sets work)</a>.</li>
+ <a href="sets.html">sets (including how user defined sets work)</a> and
+ <a href="hooks.html">hooks (and how user defined hooks work)</a>.</li>
<li><strong>Support</strong> is available via <code>#paludis</code> on
<code>irc.freenode.net</code> or the <a
generated by cgit v1.0 at 2017-10-23 11:29:05 +0000