diff options
authorAvatar David Leverton <levertond@googlemail.com> 2007-08-31 18:32:00 +0000
committerAvatar David Leverton <levertond@googlemail.com> 2007-08-31 18:32:00 +0000
commit0413aaced13e8c24a65b849580597e5d9041687d (patch)
parentb21a7c15fd1e96bd040ceabab608ad3d3a49eaf7 (diff)
Allow hooks in LIBDIR/paludis/hooks, and document .so hooks.
8 files changed, 95 insertions, 5 deletions
diff --git a/doc/hooks.html.skel b/doc/hooks.html.skel
index e83076f..430d22a 100644
--- a/doc/hooks.html.skel
+++ b/doc/hooks.html.skel
@@ -39,7 +39,7 @@ that is executed when a particular well defined action occurs.</p>
See <a href="#merger-hooks">Merger / Unmerger Hooks</a>.</li>
-<p>There are currently three categories of hook execution code:</p>
+<p>There are currently four categories of hook execution code:</p>
<li><code>.bash</code> hooks. These are simple <code>.bash</code> files that
@@ -52,6 +52,10 @@ that is executed when a particular well defined action occurs.</p>
upon other <code>.hook</code> files. See <a href="#hook-hooks">Hook Hooks</a>
for details.</li>
+ <li><code>.so</code> hooks. These are written in C++ and compiled into shared
+ libraries, and run inside the Paludis process. See <a href="#so-hooks">So Hooks</a>
+ for details.</li>
<li>Repository hooks. These are implemented internally by <code>Repository</code>
@@ -64,6 +68,7 @@ following table indicates availability:</p>
+ <th><code>.so</code></th>
@@ -71,24 +76,28 @@ following table indicates availability:</p>
+ <td>yes</td>
<th>Ebuild Phase</th>
+ <td></td>
<th>Ebuild Message</th>
+ <td></td>
+ <td>yes</td>
@@ -301,6 +310,9 @@ be symlinked there, to allow a single script to be shared between hooks):</p>
<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>
+ <li><code><em>LIBDIR</em>/paludis/hooks/<em>hookname</em>/</code>. On most
+ systems, <code><em>LIBDIR</em></code> is <code>/usr/lib</code> or <code>/usr/lib64</code>.</li>
<h4 id="bash-hooks">Bash Hooks</h4>
@@ -357,6 +369,40 @@ hook_after_install_all_post()
are cached, and are generally only called once per session, so the output should
not vary based upon outside parameters.</p>
+<h4 id="so-hooks">So Hooks</h4>
+<p>A <code>.so</code> hook is written in C++ and has full access to the Paludis public API.
+The hook takes the form of a shared library with a filename ending in <code>.so.<i>N</i></code>,
+where <i>N</i> is the first component of the Paludis version number multiplied by 100,
+plus the second component of the version number (for example, 26 for Paludis 0.26.x,
+or 102 for Paludis 1.2.y). The library must export a function with prototype
+<code>paludis::HookResult paludis_hook_run(const paludis::Environment *, const paludis::Hook &amp;)</code>
+that performs the action, and optionally one with prototype
+<code>void paludis_hook_add_dependencies(const paludis::Environment *, const paludis::Hook &amp;, paludis::DirectedGraph&lt;std::string, int&gt; &amp;)</code>
+if it needs to define ordering dependencies with other hooks. Both functions are
+declared in the header <code>&lt;paludis/hook.hh&gt;</code>, including any necessary
+<code>extern</code> or visibility declarations.</p>
+<p>The parameters and return values have the following meanings:</p>
+<dt><code>const paludis::Environment *</code></dt>
+<dd>The usual <code>Environment</code>, as used by all Paludis clients.</dd>
+<dt><code>const paludis::Hook &amp;</code></dt>
+<dd>Contains information about the hook being called. In <code>paludis_hook_add_dependencies</code>,
+the only useful member is <code>name()</code>.
+<dt><code>paludis::DirectedGraph&lt;std::string, int&gt; &amp;</code></dt>
+<dd>A graph containing, as nodes, all named hooks that will be executed along with
+this one. The <code>paludis_hook_add_dependencies</code> function should add any
+edges required to indicate its desired execution order relative to the other hooks,
+as follows: <code>g.add_edge("after", "before", 0);</code> (the 0 is not significant,
+but required by the <code>DirectedGraph</code> API).</dd>
+<dd>The <code>HookResult</code> constructor takes two arguments: an <code>int</code>,
+which should be zero if the hook is successful, or positive if not, and a <code>std::string</code>
+containing any information that should be passed back to the hook's caller (only
+used if the <code>Hook</code>'s <code>output_dest</code> member is <code>hod_grab</code>).</dd>
<h3>Package Manager Defined Hooks</h3>
<p>Paludis places some of its own hooks in
diff --git a/hooks/Makefile.am.m4 b/hooks/Makefile.am.m4
index 292c124..08d6a6f 100644
--- a/hooks/Makefile.am.m4
+++ b/hooks/Makefile.am.m4
@@ -54,7 +54,9 @@ EXTRA_DIST = \
define(`userhook', `
installuserhooks$1dir = $(datadir)/paludis/hooks/$1
-installuserhooks$1_DATA = .keep')
+installuserhooks$1_DATA = .keep
+installuserhooksplat$1dir = $(libdir)/paludis/hooks/$1
+installuserhooksplat$1_DATA = .keep')
diff --git a/paludis/environments/paludis/paludis_environment.cc b/paludis/environments/paludis/paludis_environment.cc
index 7167efe..67702f2 100644
--- a/paludis/environments/paludis/paludis_environment.cc
+++ b/paludis/environments/paludis/paludis_environment.cc
@@ -113,6 +113,7 @@ namespace paludis
add_one_hook(FSEntry(LIBEXECDIR) / "paludis" / "hooks", false);
add_one_hook(FSEntry(DATADIR) / "paludis" / "hooks", true);
+ add_one_hook(FSEntry(LIBDIR) / "paludis" / "hooks", true);
done_hooks = true;
diff --git a/paludis/hook.hh b/paludis/hook.hh
index aca5fec..2efbbb9 100644
--- a/paludis/hook.hh
+++ b/paludis/hook.hh
@@ -22,7 +22,9 @@
#include <paludis/hook-fwd.hh>
+#include <paludis/environment-fwd.hh>
#include <paludis/util/attributes.hh>
+#include <paludis/util/graph-fwd.hh>
#include <paludis/util/private_implementation_pattern.hh>
#include <paludis/util/operators.hh>
@@ -106,4 +108,9 @@ namespace paludis
+extern "C" paludis::HookResult PALUDIS_VISIBLE paludis_hook_run(
+ const paludis::Environment *, const paludis::Hook &);
+extern "C" void PALUDIS_VISIBLE paludis_hook_add_dependencies(
+ const paludis::Environment *, const paludis::Hook &, paludis::DirectedGraph<std::string, int> &);
diff --git a/paludis/sohooks_TEST.cc b/paludis/sohooks_TEST.cc
index d26be82..00df71a 100644
--- a/paludis/sohooks_TEST.cc
+++ b/paludis/sohooks_TEST.cc
@@ -57,7 +57,7 @@ namespace
-extern "C" HookResult PALUDIS_VISIBLE
paludis_hook_run(const Environment * env, const Hook & hook)
if ("so_hook" == hook.name())
@@ -70,7 +70,7 @@ paludis_hook_run(const Environment * env, const Hook & hook)
return HookResult(0, "");
-extern "C" void PALUDIS_VISIBLE
paludis_hook_add_dependencies(const Environment * env, const Hook & hook,
DirectedGraph<std::string, int> & graph)
diff --git a/paludis/util/files.m4 b/paludis/util/files.m4
index ad008d5..d2993c2 100644
--- a/paludis/util/files.m4
+++ b/paludis/util/files.m4
@@ -20,7 +20,7 @@ add(`fd_output_stream', `hh')
add(`future', `hh', `impl', `cc', `test')
add(`fs_entry', `hh', `cc', `fwd', `test', `testscript')
add(`fd_holder', `hh')
-add(`graph', `hh', `cc', `impl', `test')
+add(`graph', `hh', `cc', `fwd', `impl', `test')
add(`idle_action_pool', `hh', `cc', `se', `fwd', `test')
add(`iterator', `hh', `test')
add(`instantiation_policy', `hh', `impl', `test')
diff --git a/paludis/util/graph-fwd.hh b/paludis/util/graph-fwd.hh
new file mode 100644
index 0000000..e1ecac0
--- /dev/null
+++ b/paludis/util/graph-fwd.hh
@@ -0,0 +1,33 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+ * Copyright (c) 2007 David Leverton <levertond@googlemail.com>
+ *
+ * This file is part of the Paludis package manager. Paludis is free software;
+ * you can redistribute it and/or modify it under the terms of the GNU General
+ * Public License version 2, as published by the Free Software Foundation.
+ *
+ * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
+ * Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+namespace paludis
+ class GraphError;
+ class NoSuchGraphNodeError;
+ class NoSuchGraphEdgeError;
+ class NoGraphTopologicalOrderExistsError;
+ template <typename Node_, typename Edge_> class DirectedGraph;
diff --git a/paludis/util/graph.hh b/paludis/util/graph.hh
index aab2fc9..84e5723 100644
--- a/paludis/util/graph.hh
+++ b/paludis/util/graph.hh
@@ -20,6 +20,7 @@
+#include <paludis/util/graph-fwd.hh>
#include <paludis/util/private_implementation_pattern.hh>
#include <paludis/util/instantiation_policy.hh>
#include <paludis/util/exception.hh>