[gentoo-commits] proj/R_overlay:master commit in: doc/html/

[André Erdmann]

commit:     664ec1f39a920328e3ca4cf7f5f091eaa55d51d0
Author:     André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jun 26 17:29:01 2013 +0000
Commit:     André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jun 26 17:29:01 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=664ec1f3

doc/html: "run hooks", "distmap"

---
 doc/html/usage.html | 667 +++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 586 insertions(+), 81 deletions(-)

diff --git a/doc/html/usage.html b/doc/html/usage.html
index 9206894..c4d90fc 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -361,88 +361,102 @@ ul.auto-toc {
 <li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id24">5.3&nbsp;&nbsp;&nbsp;Getting packages from a repository that supports http only</a></li>
 <li><a class="reference internal" href="#getting-packages-from-several-remotes-using-http-and-a-package-list" id="id25">5.4&nbsp;&nbsp;&nbsp;Getting packages from several remotes using http and a package list</a></li>
 <li><a class="reference internal" href="#using-local-directories" id="id26">5.5&nbsp;&nbsp;&nbsp;Using local directories</a></li>
+<li><a class="reference internal" href="#distmap" id="id27">5.6&nbsp;&nbsp;&nbsp;distmap</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#additions-directory" id="id27">6&nbsp;&nbsp;&nbsp;Additions Directory</a><ul class="auto-toc">
-<li><a class="reference internal" href="#patching-ebuilds" id="id28">6.1&nbsp;&nbsp;&nbsp;Patching ebuilds</a></li>
-<li><a class="reference internal" href="#importing-ebuilds" id="id29">6.2&nbsp;&nbsp;&nbsp;Importing ebuilds</a></li>
+<li><a class="reference internal" href="#additions-directory" id="id28">6&nbsp;&nbsp;&nbsp;Additions Directory</a><ul class="auto-toc">
+<li><a class="reference internal" href="#patching-ebuilds" id="id29">6.1&nbsp;&nbsp;&nbsp;Patching ebuilds</a></li>
+<li><a class="reference internal" href="#importing-ebuilds" id="id30">6.2&nbsp;&nbsp;&nbsp;Importing ebuilds</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#dependency-rules" id="id30">7&nbsp;&nbsp;&nbsp;Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#simple-dependency-rules" id="id31">7.1&nbsp;&nbsp;&nbsp;Simple Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#rule-variants" id="id32">7.1.1&nbsp;&nbsp;&nbsp;Rule Variants</a></li>
-<li><a class="reference internal" href="#rule-types" id="id33">7.1.2&nbsp;&nbsp;&nbsp;Rule types</a></li>
-<li><a class="reference internal" href="#rule-file-examples" id="id34">7.1.3&nbsp;&nbsp;&nbsp;Rule File Examples</a></li>
-<li><a class="reference internal" href="#rule-file-syntax" id="id35">7.1.4&nbsp;&nbsp;&nbsp;Rule File Syntax</a></li>
+<li><a class="reference internal" href="#dependency-rules" id="id31">7&nbsp;&nbsp;&nbsp;Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#simple-dependency-rules" id="id32">7.1&nbsp;&nbsp;&nbsp;Simple Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#rule-variants" id="id33">7.1.1&nbsp;&nbsp;&nbsp;Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id34">7.1.2&nbsp;&nbsp;&nbsp;Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id35">7.1.3&nbsp;&nbsp;&nbsp;Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id36">7.1.4&nbsp;&nbsp;&nbsp;Rule File Syntax</a></li>
 </ul>
 </li>
 </ul>
 </li>
-<li><a class="reference internal" href="#package-rules" id="id36">8&nbsp;&nbsp;&nbsp;Package Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#package-rule-file-syntax" id="id37">8.1&nbsp;&nbsp;&nbsp;Package Rule File Syntax</a><ul class="auto-toc">
-<li><a class="reference internal" href="#match-blocks" id="id38">8.1.1&nbsp;&nbsp;&nbsp;Match Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-match-block-syntax" id="id39">8.1.1.1&nbsp;&nbsp;&nbsp;Extended Match Block Syntax</a></li>
+<li><a class="reference internal" href="#package-rules" id="id37">8&nbsp;&nbsp;&nbsp;Package Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#package-rule-file-syntax" id="id38">8.1&nbsp;&nbsp;&nbsp;Package Rule File Syntax</a><ul class="auto-toc">
+<li><a class="reference internal" href="#match-blocks" id="id39">8.1.1&nbsp;&nbsp;&nbsp;Match Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-match-block-syntax" id="id40">8.1.1.1&nbsp;&nbsp;&nbsp;Extended Match Block Syntax</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#action-blocks" id="id40">8.1.2&nbsp;&nbsp;&nbsp;Action Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-action-block-syntax" id="id41">8.1.2.1&nbsp;&nbsp;&nbsp;Extended Action Block Syntax</a></li>
+<li><a class="reference internal" href="#action-blocks" id="id41">8.1.2&nbsp;&nbsp;&nbsp;Action Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-action-block-syntax" id="id42">8.1.2.1&nbsp;&nbsp;&nbsp;Extended Action Block Syntax</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#package-rule-examples" id="id42">8.1.3&nbsp;&nbsp;&nbsp;Package Rule Examples</a></li>
+<li><a class="reference internal" href="#package-rule-examples" id="id43">8.1.3&nbsp;&nbsp;&nbsp;Package Rule Examples</a></li>
 </ul>
 </li>
 </ul>
 </li>
-<li><a class="reference internal" href="#configuration-reference" id="id43">9&nbsp;&nbsp;&nbsp;Configuration Reference</a><ul class="auto-toc">
-<li><a class="reference internal" href="#misc-options" id="id44">9.1&nbsp;&nbsp;&nbsp;misc options</a></li>
-<li><a class="reference internal" href="#overlay-options" id="id45">9.2&nbsp;&nbsp;&nbsp;overlay options</a></li>
-<li><a class="reference internal" href="#other-config-files" id="id46">9.3&nbsp;&nbsp;&nbsp;other config files</a></li>
-<li><a class="reference internal" href="#logging" id="id47">9.4&nbsp;&nbsp;&nbsp;logging</a><ul class="auto-toc">
-<li><a class="reference internal" href="#console-logging" id="id48">9.4.1&nbsp;&nbsp;&nbsp;console logging</a></li>
-<li><a class="reference internal" href="#file-logging" id="id49">9.4.2&nbsp;&nbsp;&nbsp;file logging</a></li>
+<li><a class="reference internal" href="#event-hooks" id="id44">9&nbsp;&nbsp;&nbsp;Event Hooks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#default-event-script" id="id45">9.1&nbsp;&nbsp;&nbsp;Default event script</a><ul class="auto-toc">
+<li><a class="reference internal" href="#activating-a-hook-script" id="id46">9.1.1&nbsp;&nbsp;&nbsp;Activating a hook script</a></li>
+<li><a class="reference internal" href="#adding-a-new-hook-script" id="id47">9.1.2&nbsp;&nbsp;&nbsp;Adding a new hook script</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id50">9.5&nbsp;&nbsp;&nbsp;options for debugging, manual dependency rule creation and testing</a></li>
+<li><a class="reference internal" href="#event-policy" id="id48">9.2&nbsp;&nbsp;&nbsp;Event Policy</a></li>
+<li><a class="reference internal" href="#hook-environment" id="id49">9.3&nbsp;&nbsp;&nbsp;Hook Environment</a></li>
+<li><a class="reference internal" href="#adding-a-function-file" id="id50">9.4&nbsp;&nbsp;&nbsp;Adding a function file</a></li>
+<li><a class="reference internal" href="#adding-a-hook-event" id="id51">9.5&nbsp;&nbsp;&nbsp;Adding a hook event</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#id3" id="id51">10&nbsp;&nbsp;&nbsp;Other config files</a><ul class="auto-toc">
-<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id52">10.1&nbsp;&nbsp;&nbsp;USE_EXPAND flag rename file</a></li>
-<li><a class="reference internal" href="#field-definition-config" id="id53">10.2&nbsp;&nbsp;&nbsp;Field Definition Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id54">10.2.1&nbsp;&nbsp;&nbsp;Example: The default field definition file</a></li>
+<li><a class="reference internal" href="#configuration-reference" id="id52">10&nbsp;&nbsp;&nbsp;Configuration Reference</a><ul class="auto-toc">
+<li><a class="reference internal" href="#misc-options" id="id53">10.1&nbsp;&nbsp;&nbsp;misc options</a></li>
+<li><a class="reference internal" href="#overlay-options" id="id54">10.2&nbsp;&nbsp;&nbsp;overlay options</a></li>
+<li><a class="reference internal" href="#other-config-files" id="id55">10.3&nbsp;&nbsp;&nbsp;other config files</a></li>
+<li><a class="reference internal" href="#shell-environment-hooks" id="id56">10.4&nbsp;&nbsp;&nbsp;shell environment / hooks</a></li>
+<li><a class="reference internal" href="#logging" id="id57">10.5&nbsp;&nbsp;&nbsp;logging</a><ul class="auto-toc">
+<li><a class="reference internal" href="#console-logging" id="id58">10.5.1&nbsp;&nbsp;&nbsp;console logging</a></li>
+<li><a class="reference internal" href="#file-logging" id="id59">10.5.2&nbsp;&nbsp;&nbsp;file logging</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id60">10.6&nbsp;&nbsp;&nbsp;options for debugging, manual dependency rule creation and testing</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#dependency-resolution-console" id="id55">11&nbsp;&nbsp;&nbsp;Dependency Resolution Console</a></li>
-<li><a class="reference internal" href="#implementation-overview" id="id56">12&nbsp;&nbsp;&nbsp;Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#packageinfo" id="id57">12.1&nbsp;&nbsp;&nbsp;PackageInfo</a></li>
-<li><a class="reference internal" href="#repository-management" id="id58">12.2&nbsp;&nbsp;&nbsp;Repository Management</a><ul class="auto-toc">
-<li><a class="reference internal" href="#repository" id="id59">12.2.1&nbsp;&nbsp;&nbsp;Repository</a><ul class="auto-toc">
-<li><a class="reference internal" href="#adding-new-repository-types" id="id60">12.2.1.1&nbsp;&nbsp;&nbsp;Adding new repository types</a></li>
+<li><a class="reference internal" href="#id3" id="id61">11&nbsp;&nbsp;&nbsp;Other config files</a><ul class="auto-toc">
+<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id62">11.1&nbsp;&nbsp;&nbsp;USE_EXPAND flag rename file</a></li>
+<li><a class="reference internal" href="#field-definition-config" id="id63">11.2&nbsp;&nbsp;&nbsp;Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id64">11.2.1&nbsp;&nbsp;&nbsp;Example: The default field definition file</a></li>
 </ul>
 </li>
 </ul>
 </li>
-<li><a class="reference internal" href="#overlay" id="id61">12.3&nbsp;&nbsp;&nbsp;Overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#metadata-creation" id="id62">12.3.1&nbsp;&nbsp;&nbsp;Metadata Creation</a></li>
-<li><a class="reference internal" href="#manifest-creation" id="id63">12.3.2&nbsp;&nbsp;&nbsp;Manifest Creation</a></li>
+<li><a class="reference internal" href="#dependency-resolution-console" id="id65">12&nbsp;&nbsp;&nbsp;Dependency Resolution Console</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id66">13&nbsp;&nbsp;&nbsp;Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id67">13.1&nbsp;&nbsp;&nbsp;PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id68">13.2&nbsp;&nbsp;&nbsp;Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#repository" id="id69">13.2.1&nbsp;&nbsp;&nbsp;Repository</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id70">13.2.1.1&nbsp;&nbsp;&nbsp;Adding new repository types</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#ebuild-creation" id="id64">12.4&nbsp;&nbsp;&nbsp;Ebuild Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#ebuild-variables" id="id65">12.4.1&nbsp;&nbsp;&nbsp;Ebuild Variables</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#overlay-creation" id="id66">12.5&nbsp;&nbsp;&nbsp;Overlay Creation</a></li>
-<li><a class="reference internal" href="#dependency-resolution" id="id67">12.6&nbsp;&nbsp;&nbsp;Dependency Resolution</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id68">12.6.1&nbsp;&nbsp;&nbsp;Dependency types</a><ul class="auto-toc">
-<li><a class="reference internal" href="#description-file-dependency-fields" id="id69">12.6.1.1&nbsp;&nbsp;&nbsp;DESCRIPTION file dependency fields</a></li>
+<li><a class="reference internal" href="#overlay" id="id71">13.3&nbsp;&nbsp;&nbsp;Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id72">13.3.1&nbsp;&nbsp;&nbsp;Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id73">13.3.2&nbsp;&nbsp;&nbsp;Manifest Creation</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#dependency-environments" id="id70">12.6.2&nbsp;&nbsp;&nbsp;Dependency Environments</a></li>
-<li><a class="reference internal" href="#ebuildjob-channel" id="id71">12.6.3&nbsp;&nbsp;&nbsp;EbuildJob Channel</a></li>
-<li><a class="reference internal" href="#dependency-rule-pools" id="id72">12.6.4&nbsp;&nbsp;&nbsp;Dependency Rule Pools</a></li>
-<li><a class="reference internal" href="#dependency-resolver-modules" id="id73">12.6.5&nbsp;&nbsp;&nbsp;Dependency Resolver Modules</a></li>
-<li><a class="reference internal" href="#dependency-resolver" id="id74">12.6.6&nbsp;&nbsp;&nbsp;Dependency Resolver</a></li>
+<li><a class="reference internal" href="#ebuild-creation" id="id74">13.4&nbsp;&nbsp;&nbsp;Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id75">13.4.1&nbsp;&nbsp;&nbsp;Ebuild Variables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#overlay-creation" id="id76">13.5&nbsp;&nbsp;&nbsp;Overlay Creation</a></li>
+<li><a class="reference internal" href="#dependency-resolution" id="id77">13.6&nbsp;&nbsp;&nbsp;Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id78">13.6.1&nbsp;&nbsp;&nbsp;Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id79">13.6.1.1&nbsp;&nbsp;&nbsp;DESCRIPTION file dependency fields</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dependency-environments" id="id80">13.6.2&nbsp;&nbsp;&nbsp;Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id81">13.6.3&nbsp;&nbsp;&nbsp;EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id82">13.6.4&nbsp;&nbsp;&nbsp;Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id83">13.6.5&nbsp;&nbsp;&nbsp;Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id84">13.6.6&nbsp;&nbsp;&nbsp;Dependency Resolver</a></li>
 </ul>
 </li>
 </ul>
@@ -716,6 +730,11 @@ required.</p>
 can be used to rename USE_EXPAND flags. This option is not required.</p>
 <p class="last">Example: USE_EXPAND_RENAME = ~/roverlay/config/useflag_rename</p>
 </dd>
+<dt>CACHEDIR</dt>
+<dd><p class="first">Directory for generated files that do not belong to the overlay, e.g.
+the <em>distmap</em> file. This option is <strong>required</strong>.</p>
+<p class="last">Example: CACHEDIR = ~/roverlay/workdir/cache</p>
+</dd>
 <dt>OVERLAY_ECLASS</dt>
 <dd><p class="first">This option lists eclass files that should be imported into the overlay
 (into <em>OVERLAY_DIR</em>/eclass/) and inherited in all ebuilds.
@@ -799,6 +818,11 @@ to know in detail what <em>roverlay</em> does before running it.</p>
 </tr>
 <tr><td>&nbsp;</td><td>Disable downloading of R packages.</td></tr>
 <tr><td class="option-group" colspan="2">
+<kbd><span class="option">--distmap-verify</span></kbd></td>
+</tr>
+<tr><td>&nbsp;</td><td>Enforce verification of R packages in the package mirror directory.
+This also tries to recreate the distmap.</td></tr>
+<tr><td class="option-group" colspan="2">
 <kbd><span class="option">--no-incremental</span></kbd></td>
 </tr>
 <tr><td>&nbsp;</td><td>Force recreation of existing ebuilds</td></tr>
@@ -1345,6 +1369,18 @@ consider using one of the <strong>websync</strong> repo types, <a class="referen
 <a class="reference internal" href="#websync-pkglist">websync_pkglist</a>.</p>
 </div>
 </div>
+<div class="section" id="distmap">
+<h2><a class="toc-backref" href="#contents">5.6&nbsp;&nbsp;&nbsp;distmap</a></h2>
+<p><em>roverlay</em> uses a text file to store information about files in the package
+mirror directory (<a class="reference internal" href="#overlay-distdir-root">OVERLAY_DISTDIR_ROOT</a>). This is necessary for comparing
+package files from repos with files for which an ebuild has already been
+created (in previous runs).</p>
+<p>With the help of the <em>distmap file</em>, <em>roverlay</em> is able to determine whether
+upstream has changed a package file silently and creates a revision-bumped
+ebuild for the <em>new</em> package file.</p>
+<p>The <em>distmap file</em> can optionally be compressed (bzip2 or gzip), which
+reduces its size considerably.</p>
+</div>
 </div>
 <div class="section" id="additions-directory">
 <h1><a class="toc-backref" href="#contents">6&nbsp;&nbsp;&nbsp;Additions Directory</a></h1>
@@ -2137,8 +2173,392 @@ END;
 </div>
 </div>
 </div>
+<div class="section" id="event-hooks">
+<h1><a class="toc-backref" href="#contents">9&nbsp;&nbsp;&nbsp;Event Hooks</a></h1>
+<p><em>roverlay</em> is able to call a script when certain events occur, e.g. after
+successful overlay creation, which can be used to perform additional actions
+without touching <em>roverlay's</em> source code.</p>
+<p>To realize this, <em>roverlay</em> determines whether a given event is permitted
+(<a class="reference internal" href="#event-policy">event policy</a>) and, if so, creates a <a class="reference internal" href="#hook-environment">hook environment</a> and runs the
+script. Additionally, shell scripts can load <em>roverlay's</em> <em>$FUNCTIONS</em> file,
+which provides extra functionality.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last"><em>roverlay</em> waits until the script terminates and thus possibly waits
+forever.</p>
+</div>
+<div class="section" id="default-event-script">
+<h2><a class="toc-backref" href="#contents">9.1&nbsp;&nbsp;&nbsp;Default event script</a></h2>
+<p>The default event script (<tt class="docutils literal">mux.sh</tt>) loads <em>$FUNCTIONS</em> and then runs the
+following script files (by sourcing them), in order:</p>
+<ol class="arabic simple">
+<li>all files from <a class="reference internal" href="#additions-dir">ADDITIONS_DIR</a>/hooks/&lt;event&gt; that end with <em>.sh</em>
+(<tt class="docutils literal"><span class="pre">&lt;ADDITIONS_DIR&gt;/hooks/&lt;event&gt;/*.sh</span></tt>)</li>
+<li>all files <a class="reference internal" href="#additions-dir">ADDITIONS_DIR</a>/hooks that end with <em>.&lt;event&gt;</em>
+(<tt class="docutils literal"><span class="pre">&lt;ADDITIONS_DIR&gt;/hooks/*.&lt;event&gt;</span></tt>)</li>
+</ol>
+<p>So, there are two naming schemes for <em>hook scripts</em>.
+Either one is acceptable, but it is advised to stay consistent.
+Having the same script at both locations results in executing it twice.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">The default event script enables <em>nounset</em> behavior, which causes the
+shell command interpreter to exit abnormally if an unset variable is
+accessed.</p>
+</div>
+<div class="section" id="activating-a-hook-script">
+<h3><a class="toc-backref" href="#contents">9.1.1&nbsp;&nbsp;&nbsp;Activating a hook script</a></h3>
+<p>Activating a hook script can be done by symlinking it:</p>
+<pre class="code text literal-block">
+ln -s &lt;real script&gt; ${ADDITIONS_DIR}/hooks/&lt;event&gt;/&lt;name&gt;.sh
+# or
+ln -s &lt;real script&gt; ${ADDITIONS_DIR}/hooks/&lt;name&gt;.&lt;event&gt;
+</pre>
+</div>
+<div class="section" id="adding-a-new-hook-script">
+<h3><a class="toc-backref" href="#contents">9.1.2&nbsp;&nbsp;&nbsp;Adding a new hook script</a></h3>
+<p>As hinted before, <em>hook scripts</em> are simple shell scripts. The following
+template gives an idea of how to write them:</p>
+<pre class="code sh literal-block">
+<span class="comment">#!/bin/sh
+#set -u
+</span>
+<span class="comment"># load essential functions
+# (not necessary when using the default event script)
+</span>. <span class="literal string double">&quot;${FUNCTIONS?}&quot;</span> <span class="operator">||</span> <span class="name builtin">exit</span>
+
+<span class="comment">## load additional function files, if any
+#$lf &lt;name(s)&gt;
+</span>
+<span class="comment"># script body
+#
+# when redirecting output to $DEVNULL, use &quot;&gt;&gt;&quot; instead of &quot;&gt;&quot; as
+# $DEVNULL could be a file
+#ls &gt;&gt;${DEVNULL}
+#
+# ...
+</span>
+
+<span class="comment"># the script must not exit if everything went well (return is ok)
+</span><span class="keyword">return </span>0
+</pre>
+</div>
+</div>
+<div class="section" id="event-policy">
+<h2><a class="toc-backref" href="#contents">9.2&nbsp;&nbsp;&nbsp;Event Policy</a></h2>
+<p>The <em>event policy</em> controls whether a certain event actually triggers a script
+call or not.
+It is constructed by parsing the <a class="reference internal" href="#event-hook-restrict">EVENT_HOOK_RESTRICT</a> config option:</p>
+<ul class="simple">
+<li>a word prefixed by <tt class="docutils literal">-</tt> means <em>deny specific event</em> (-&gt; blacklist)</li>
+<li>the asterisk char <tt class="docutils literal">*</tt> (or <tt class="docutils literal">+*</tt>) sets the policy to
+<em>allow unless denied</em> (blacklist) or <em>allow all</em></li>
+<li>a word prefixed by <tt class="docutils literal">+</tt> or without a prefix char means
+<em>allow specific event</em> (-&gt; whitelist)</li>
+<li>the asterisk char with <tt class="docutils literal">-</tt> as prefix (<tt class="docutils literal"><span class="pre">-*</span></tt>) sets the policy to
+<em>deny unless allowed</em> (whitelist) or <em>deny all</em></li>
+</ul>
+<p>The policy defaults to <em>allow all</em> if <tt class="docutils literal">EVENT_HOOK_RESTRICT</tt> is not set in
+the config file. An empty string sets the policy to <em>deny all</em>.</p>
+</div>
+<div class="section" id="hook-environment">
+<h2><a class="toc-backref" href="#contents">9.3&nbsp;&nbsp;&nbsp;Hook Environment</a></h2>
+<table border="1" class="docutils">
+<caption>environment variables provided by <em>roverlay</em></caption>
+<colgroup>
+<col width="21%" />
+<col width="25%" />
+<col width="54%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">variable</th>
+<th class="head">source</th>
+<th class="head">notes / description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>PATH</td>
+<td>os.environ</td>
+<td>&nbsp;</td>
+</tr>
+<tr><td>LOGNAME</td>
+<td>os.environ</td>
+<td>&nbsp;</td>
+</tr>
+<tr><td>SHLVL</td>
+<td>os.environ</td>
+<td>&nbsp;</td>
+</tr>
+<tr><td>TERM</td>
+<td>os.environ</td>
+<td>&nbsp;</td>
+</tr>
+<tr><td>HOME</td>
+<td>os.environ</td>
+<td>&nbsp;</td>
+</tr>
+<tr><td>ROVERLAY_PHASE</td>
+<td>event</td>
+<td>event that caused the script to run</td>
+</tr>
+<tr><td>OVERLAY</td>
+<td>config</td>
+<td rowspan="3">overlay directory (<a class="reference internal" href="#overlay-dir">OVERLAY_DIR</a>),
+initial working directory</td>
+</tr>
+<tr><td>S</td>
+<td><em>$OVERLAY</em></td>
+</tr>
+<tr><td>PWD</td>
+<td><em>$OVERLAY</em></td>
+</tr>
+<tr><td>DISTROOT</td>
+<td>config</td>
+<td>package mirror directory
+(<a class="reference internal" href="#overlay-distdir-root">OVERLAY_DISTDIR_ROOT</a>)</td>
+</tr>
+<tr><td>TMPDIR</td>
+<td>os.environ,
+<em>fallback</em></td>
+<td rowspan="2">directory for temporary files</td>
+</tr>
+<tr><td>T</td>
+<td><em>$TMPDIR</em></td>
+</tr>
+<tr><td>ADDITIONS_DIR</td>
+<td>config</td>
+<td rowspan="2">directory with supplementary files
+(<a class="reference internal" href="#overlay-additions-dir">OVERLAY_ADDITIONS_DIR</a>)</td>
+</tr>
+<tr><td>FILESDIR</td>
+<td><em>$ADDITIONS_DIR</em></td>
+</tr>
+<tr><td>SHLIB</td>
+<td><em>$ADDITIONS_DIR</em>,
+<em>installed?</em></td>
+<td>A list of directories with shell
+function files
+(optional, only set if any dir exists)</td>
+</tr>
+<tr><td>FUNCTIONS</td>
+<td><em>$ADDITIONS_DIR</em>,
+<em>installed?</em></td>
+<td>file with essential shell functions
+(optional, only set if it exists)</td>
+</tr>
+<tr><td>DEBUG</td>
+<td>log level</td>
+<td><em>shbool</em> (<tt class="docutils literal">y</tt> or <tt class="docutils literal">n</tt>) that
+indicates whether debug messages should
+be printed</td>
+</tr>
+<tr><td>VERBOSE</td>
+<td>log level</td>
+<td><em>shbool</em></td>
+</tr>
+<tr><td>QUIET</td>
+<td>log level</td>
+<td><em>shbool</em> that indicates whether scripts
+should be quiet</td>
+</tr>
+<tr><td>NO_COLOR</td>
+<td><em>n/a</em></td>
+<td><em>shbool</em>. Always set to <em>y</em> since
+colored output should not be produced</td>
+</tr>
+<tr><td>NOSYNC</td>
+<td>config</td>
+<td><em>shbool</em> that indicates whether data
+transfers from/to remote machines is
+allowed (<a class="reference internal" href="#nosync">NOSYNC</a>)</td>
+</tr>
+<tr><td>EBUILD</td>
+<td>config</td>
+<td>the <em>ebuild</em> executable</td>
+</tr>
+<tr><td>GIT_EDITOR</td>
+<td><em>n/a</em></td>
+<td rowspan="2">set to <em>/bin/false</em></td>
+</tr>
+<tr><td>GIT_ASKPASS</td>
+<td><em>n/a</em></td>
+</tr>
+</tbody>
+</table>
+<p>The default <em>essential shell functions</em> file (<em>$FUNCTIONS</em>) makes,
+when included in the hook script, most of the enviroment variables readonly.</p>
+<table border="1" class="docutils">
+<caption>variables provided by <em>$FUNCTIONS</em></caption>
+<colgroup>
+<col width="24%" />
+<col width="76%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">variable</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>IFS_DEFAULT</td>
+<td>default <em>internal field separator</em></td>
+</tr>
+<tr><td>IFS_NEWLINE</td>
+<td><em>IFS</em> for iterating over text lines</td>
+</tr>
+<tr><td>DEVNULL</td>
+<td><em>/dev/null</em> target (could also be a file)</td>
+</tr>
+<tr><td>EX_ERR</td>
+<td>default error exit code</td>
+</tr>
+<tr><td>EX_ARG_ERR</td>
+<td>default exit code for arg errors</td>
+</tr>
+<tr><td>SCRIPT_FILENAME</td>
+<td>file name of the hook script</td>
+</tr>
+<tr><td>SCRIPT_NAME</td>
+<td>name of the hook script (without file extension)</td>
+</tr>
+<tr><td>lf</td>
+<td>reference to a function that loads additional shell
+function files</td>
+</tr>
+</tbody>
+</table>
+<p><em>$FUNCTIONS</em> also provides a number of shell functions:</p>
+<pre class="code sh literal-block">
+<span class="comment"># --- message ---
+#
+# void veinfo ( message )
+#  Prints a message to stdout if $DEBUG is set to 'y'.
+#
+# void einfo  ( message )
+#  Prints a message to stdout if $VERBOSE is set to 'y'.
+#
+# void ewarn  ( message )
+#  Prints a message to stderr unless $QUIET is set to 'y'.
+#
+# void eerror ( message )
+#  Prints a message to stderr.
+#
+#
+# --- core ---
+#
+# &#64;noreturn die ( [message], [exit_code] ), raises exit()
+#  Lets the script die with the given message/exit code.
+#
+# &#64;noreturn OUT_OF_BOUNDS(), raises die()
+#  Lets the script die due to insufficient arg count.
+#
+# int run_command ( *cmdv )
+#  Logs a command and runs it afterwards.
+#
+# int run_command_logged ( *cmdv )
+#  Logs a command, runs it and logs the result.
+#
+# void autodie ( *cmdv ), raises die()
+#  Runs a command. Lets the script die if the command fails.
+#
+#
+# void load_functions ( *filenames, **SHLIB ), raises die()
+#  Loads additional shell functions file(s) from $SHLIB.
+#  (Referenced by $lf.)
+#
+# void dont_run_as_root(), raises die()
+#  Lets the script die if it is run as root.
+#
+# int list_has ( word, *list_items )
+#  Returns 0 if $word is in the given list, else 1.
+#
+# int qwhich ( *command )
+#  Returns 0 if all listed commands are found by &quot;which&quot;, else 1.
+#
+#
+# --- fs ---
+#
+# int dodir ( *dir )
+#  Ensures that zero or more directories exist by creating them if
+#  necessary. Returns the number of directories that could not be created.
+#
+#
+# --- str ---
+#
+# int yesno ( word, **YESNO_YES=0, **YESNO_NO=1, **YESNO_EMPTY=2 )
+#  Returns $YESNO_YES if $word means &quot;yes&quot;, $YESNO_EMPTY if $word is empty
+#  and $YESNO_NO otherwise (if $word probably means &quot;no&quot;).
+#
+# ~int str_trim ( *args )
+#  Removes whitespace at the beginning and end of a string and replaces
+#  any whitespace sequence within the string with a single space char.
+#  Passes the return value of the underlying sed command.
+#
+# ~int str_upper ( *args )
+#  Echoes the uppercase variant of stdin or *args.
+#  Passes tr's return value.
+#
+# ~int str_lower ( *args )
+#  Echoes the lowercase variant of stdin or *args.
+#  Passes tr's return value.
+#
+# ~int str_field ( fieldspec, *args, **FIELD_SEPARATOR=' ' )
+#  Echoes the requested fields of stdin or *args.
+#  Passes cut's return value.
+#
+#
+# --- int ---
+#
+# int is_int ( word )
+#  Returns 0 if $word is an integer, else 1.
+#
+# int is_natural ( word )
+#  Returns 0 if $word is an integer &gt;= 0, else 1.
+#
+# int is_positive ( word )
+#  Returns 0 if $word is an integer &gt;= 1, else 1.
+#
+# int is_negative ( word )
+#  Returns 0 if $word is an integer &lt; 0, else 1.
+#</span>
+</pre>
+</div>
+<div class="section" id="adding-a-function-file">
+<h2><a class="toc-backref" href="#contents">9.4&nbsp;&nbsp;&nbsp;Adding a function file</a></h2>
+<p>Function files are shell script files that provide functions and variables.
+They should, however, not execute any code directly.</p>
+<p>The template below illustrates how to write function files:</p>
+<pre class="code sh literal-block">
+<span class="comment"># protect against repeated inclusion of this file
+# (replace &lt;name&gt; with a unique identifier)
+</span><span class="keyword">if</span> <span class="operator">[</span> -z <span class="literal string double">&quot;${__HAVE_&lt;name&gt;__-}&quot;</span> <span class="operator">]</span>; <span class="keyword">then
+</span><span class="name builtin">readonly </span>__HAVE_&lt;name&gt;__<span class="operator">=</span>y
+
+<span class="comment"># function file body
+# ...
+</span>
+<span class="keyword">fi</span>
+</pre>
+<p>Shell function files should be put into <tt class="docutils literal"><span class="pre">&lt;ADDITIONS_DIR&gt;/shlib</span></tt>.</p>
+</div>
+<div class="section" id="adding-a-hook-event">
+<h2><a class="toc-backref" href="#contents">9.5&nbsp;&nbsp;&nbsp;Adding a hook event</a></h2>
+<p>Adding a new event has to be done in <em>roverlay's</em> source code and is a rather
+trivial task. The <tt class="docutils literal">roverlay.hook</tt> module implements a function for running
+the event script:</p>
+<pre class="code python literal-block">
+<span class="comment"># import hook module</span>
+<span class="keyword namespace">import</span> <span class="name namespace">roverlay.hook</span>
+
+<span class="comment"># ...</span>
+<span class="comment"># then, somewhere in the code</span>
+<span class="name">roverlay</span><span class="operator">.</span><span class="name">hook</span><span class="operator">.</span><span class="name">run</span> <span class="punctuation">(</span> <span class="literal string">&quot;&lt;event&gt;&quot;</span> <span class="punctuation">)</span>
+<span class="comment"># ...</span>
+<span class="name">roverlay</span><span class="operator">.</span><span class="name">hook</span><span class="operator">.</span><span class="name">run</span> <span class="punctuation">(</span> <span class="literal string">&quot;&lt;another event&gt;&quot;</span> <span class="punctuation">)</span>
+</pre>
+</div>
+</div>
 <div class="section" id="configuration-reference">
-<h1><a class="toc-backref" href="#contents">9&nbsp;&nbsp;&nbsp;Configuration Reference</a></h1>
+<h1><a class="toc-backref" href="#contents">10&nbsp;&nbsp;&nbsp;Configuration Reference</a></h1>
 <p>The main config file uses '&lt;option&gt; = &lt;value&gt;' syntax, comment lines start
 with <strong>#</strong>. Variable substitution (&quot;${X}&quot;) is not supported. Quotes around
 the value are optional and allow to span long values over multiple lines.
@@ -2191,7 +2611,15 @@ restrictions. Commenting it out is safe.</dd>
 </dl>
 <p>The following sections will list all config entries.</p>
 <div class="section" id="misc-options">
-<h2><a class="toc-backref" href="#contents">9.1&nbsp;&nbsp;&nbsp;misc options</a></h2>
+<h2><a class="toc-backref" href="#contents">10.1&nbsp;&nbsp;&nbsp;misc options</a></h2>
+<dl class="docutils" id="cachedir">
+<dt>CACHEDIR</dt>
+<dd><p class="first">Directory for persistent files that don't belong to the overlay, e.g.
+the distmap file.</p>
+<p>This option is <strong>required</strong>.</p>
+<p class="last">&lt;&lt;TODO: default value!&gt;&gt;</p>
+</dd>
+</dl>
 <dl class="docutils" id="distfiles">
 <dt>DISTFILES</dt>
 <dd>Alias to <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
@@ -2217,6 +2645,13 @@ set.</p>
 <p class="last">Defaults to <em>ebuild</em>, which should be fine in most cases.</p>
 </dd>
 </dl>
+<dl class="docutils" id="nosync">
+<dt>NOSYNC</dt>
+<dd><p class="first">A <em>bool</em> that controls whether <em>syncing</em>, i.e. data transfers from/to
+remote machines, is allowed or forbidden.</p>
+<p class="last">Defaults to <em>no</em>.</p>
+</dd>
+</dl>
 <dl class="docutils" id="rsync-bwlimit">
 <dt>RSYNC_BWLIMIT</dt>
 <dd><p class="first">Set a max. average bandwidth usage in kilobytes per second.
@@ -2226,7 +2661,7 @@ This will pass '--bwlimit=&lt;value&gt;' to all rsync commands.</p>
 </dl>
 </div>
 <div class="section" id="overlay-options">
-<h2><a class="toc-backref" href="#contents">9.2&nbsp;&nbsp;&nbsp;overlay options</a></h2>
+<h2><a class="toc-backref" href="#contents">10.2&nbsp;&nbsp;&nbsp;overlay options</a></h2>
 <dl class="docutils" id="additions-dir">
 <dt>ADDITIONS_DIR:</dt>
 <dd>Alias to <a class="reference internal" href="#overlay-additions-dir">OVERLAY_ADDITIONS_DIR</a>.</dd>
@@ -2247,6 +2682,18 @@ This will pass '--bwlimit=&lt;value&gt;' to all rsync commands.</p>
 <dt>DISTDIR_STRATEGY</dt>
 <dd>Alias to <a class="reference internal" href="#overlay-distdir-strategy">OVERLAY_DISTDIR_STRATEGY</a>.</dd>
 </dl>
+<dl class="docutils" id="distdir-verify">
+<dt>DISTDIR_VERIFY</dt>
+<dd>Alias to <a class="reference internal" href="#overlay-distdir-verify">OVERLAY_DISTDIR_VERIFY</a>.</dd>
+</dl>
+<dl class="docutils" id="distmap-compression">
+<dt>DISTMAP_COMPRESSION</dt>
+<dd>Alias to <a class="reference internal" href="#overlay-distmap-compression">OVERLAY_DISTMAP_COMPRESSION</a>.</dd>
+</dl>
+<dl class="docutils" id="distmap-file">
+<dt>DISTMAP_FILE</dt>
+<dd>Alias to <a class="reference internal" href="#overlay-distmap-file">OVERLAY_DISTMAP_FILE</a>.</dd>
+</dl>
 <dl class="docutils" id="ebuild-use-expand-name">
 <dt>EBUILD_USE_EXPAND_NAME</dt>
 <dd>Name of the R_SUGGESTS USE_EXPAND variable. Defaults to <em>R_SUGGESTS</em>.</dd>
@@ -2349,6 +2796,27 @@ This method is not compatible with any of the above.</td>
 config file, &quot;hardlink symlink&quot;.</p>
 </dd>
 </dl>
+<dl class="docutils" id="overlay-distdir-verify">
+<dt>OVERLAY_DISTDIR_VERIFY</dt>
+<dd><p class="first">A <em>bool</em> that controls whether file integrity of <em>OVERLAY_DISTDIR_ROOT</em>
+should be checked on startup. This is an expensive operation since each
+file have to be read once.</p>
+<p class="last">Defaults to <em>no</em> as the verification is normally not needed.</p>
+</dd>
+</dl>
+<dl class="docutils" id="overlay-distmap-compression">
+<dt>OVERLAY_DISTMAP_COMPRESSION</dt>
+<dd><p class="first">Compression format for the distmap file. Choices are none, gzip/gz and
+bzip2/bz2.</p>
+<p class="last">Defaults to bzip2.</p>
+</dd>
+</dl>
+<dl class="docutils" id="overlay-distmap-file">
+<dt>OVERLAY_DISTMAP_FILE:</dt>
+<dd><p class="first">File path to the distmap file.</p>
+<p class="last">Defaults to &lt;not set&gt;, which results in <a class="reference internal" href="#cachedir">CACHEDIR</a>/distmap.db.</p>
+</dd>
+</dl>
 <dl class="docutils" id="overlay-eclass">
 <dt>OVERLAY_ECLASS</dt>
 <dd><p class="first">A list of eclass files that will be imported into the overlay and inherited
@@ -2398,7 +2866,7 @@ writing.</p>
 </dl>
 </div>
 <div class="section" id="other-config-files">
-<h2><a class="toc-backref" href="#contents">9.3&nbsp;&nbsp;&nbsp;other config files</a></h2>
+<h2><a class="toc-backref" href="#contents">10.3&nbsp;&nbsp;&nbsp;other config files</a></h2>
 <p>Some config config options are split from the main config file for various
 reasons:</p>
 <ul class="simple">
@@ -2476,8 +2944,45 @@ much without dependency resolution.</p>
 <dd>Alias to <a class="reference internal" href="#ebuild-use-expand-rename">EBUILD_USE_EXPAND_RENAME</a>.</dd>
 </dl>
 </div>
+<div class="section" id="shell-environment-hooks">
+<h2><a class="toc-backref" href="#contents">10.4&nbsp;&nbsp;&nbsp;shell environment / hooks</a></h2>
+<dl class="docutils" id="event-hook">
+<dt>EVENT_HOOK</dt>
+<dd><p class="first">A script that is called for handling <em>events</em> (see <a class="reference internal" href="#event-hooks">Event Hooks</a>).</p>
+<p class="last">Defaults to &lt;libexec dir&gt;/hooks/mux.sh if roverlay has been installed
+and <a class="reference internal" href="#additions-dir">ADDITIONS_DIR</a>/hooks/mux.sh otherwise.</p>
+</dd>
+</dl>
+<dl class="docutils" id="event-hook-restrict">
+<dt>EVENT_HOOK_RESTRICT</dt>
+<dd><p class="first">A list of <em>events</em> that are allowed (<tt class="docutils literal">&lt;event&gt;</tt>, <tt class="docutils literal">+&lt;event&gt;</tt>) or
+forbidden (<tt class="docutils literal"><span class="pre">-&lt;event&gt;</span></tt>). The asterisk wildcard character can be used to
+set the default policy to <em>allow unless forbidden</em> (<tt class="docutils literal">*</tt>) or
+<em>deny unless allowed</em> (<tt class="docutils literal"><span class="pre">-*</span></tt>).</p>
+<p>Defaults to &lt;not set&gt;, which is equivalent to <em>deny all</em>.</p>
+<p class="last"><tt class="docutils literal"><span class="pre">EVENT_HOOK_RESTRICT=&quot;overlay_success&quot;</span></tt> would allow the <tt class="docutils literal">overlay_success</tt>
+event only, whereas <tt class="docutils literal"><span class="pre">EVENT_HOOK_RESTRICT=&quot;*</span> <span class="pre">-overlay_success&quot;</span></tt> would
+allow any event except for <tt class="docutils literal">overlay_success</tt>. Also see <a class="reference internal" href="#event-policy">event policy</a>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="filter-shell-env">
+<dt>FILTER_SHELL_ENV</dt>
+<dd><p class="first">A <em>bool</em> that controls whether the hook environment should be filtered
+or not.</p>
+<p class="last">Defaults to <em>true</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="hook">
+<dt>HOOK</dt>
+<dd>Alias to <a class="reference internal" href="#event-hook">EVENT_HOOK</a>.</dd>
+</dl>
+<dl class="docutils" id="hook-restrict">
+<dt>HOOK_RESTRICT</dt>
+<dd>Alias to <a class="reference internal" href="#event-hook-restrict">EVENT_HOOK_RESTRICT</a>.</dd>
+</dl>
+</div>
 <div class="section" id="logging">
-<h2><a class="toc-backref" href="#contents">9.4&nbsp;&nbsp;&nbsp;logging</a></h2>
+<h2><a class="toc-backref" href="#contents">10.5&nbsp;&nbsp;&nbsp;logging</a></h2>
 <dl class="docutils" id="log-date-format">
 <dt>LOG_DATE_FORMAT</dt>
 <dd><p class="first">The date format (ISO8601) used in log messages.</p>
@@ -2502,7 +3007,7 @@ have  their own log level.</p>
 </dd>
 </dl>
 <div class="section" id="console-logging">
-<h3><a class="toc-backref" href="#contents">9.4.1&nbsp;&nbsp;&nbsp;console logging</a></h3>
+<h3><a class="toc-backref" href="#contents">10.5.1&nbsp;&nbsp;&nbsp;console logging</a></h3>
 <dl class="docutils" id="log-console">
 <dt>LOG_CONSOLE</dt>
 <dd><p class="first">Enables/Disables logging to console. The value has to be a <em>bool</em>.</p>
@@ -2523,7 +3028,7 @@ have  their own log level.</p>
 </dl>
 </div>
 <div class="section" id="file-logging">
-<h3><a class="toc-backref" href="#contents">9.4.2&nbsp;&nbsp;&nbsp;file logging</a></h3>
+<h3><a class="toc-backref" href="#contents">10.5.2&nbsp;&nbsp;&nbsp;file logging</a></h3>
 <dl class="docutils" id="log-file">
 <dt>LOG_FILE</dt>
 <dd><p class="first">Sets the log file. File logging will be disabled if this option does not
@@ -2582,7 +3087,7 @@ files will be kept.</p>
 </div>
 </div>
 <div class="section" id="options-for-debugging-manual-dependency-rule-creation-and-testing">
-<h2><a class="toc-backref" href="#contents">9.5&nbsp;&nbsp;&nbsp;options for debugging, manual dependency rule creation and testing</a></h2>
+<h2><a class="toc-backref" href="#contents">10.6&nbsp;&nbsp;&nbsp;options for debugging, manual dependency rule creation and testing</a></h2>
 <dl class="docutils" id="description-dir">
 <dt>DESCRIPTION_DIR</dt>
 <dd><p class="first">A directory where all description data read from an R package will be
@@ -2601,9 +3106,9 @@ on <em>roverlay</em> exit. Primarily useful for creating new rules.</p>
 </div>
 </div>
 <div class="section" id="id3">
-<h1><a class="toc-backref" href="#contents">10&nbsp;&nbsp;&nbsp;Other config files</a></h1>
+<h1><a class="toc-backref" href="#contents">11&nbsp;&nbsp;&nbsp;Other config files</a></h1>
 <div class="section" id="use-expand-flag-rename-file">
-<h2><a class="toc-backref" href="#contents">10.1&nbsp;&nbsp;&nbsp;USE_EXPAND flag rename file</a></h2>
+<h2><a class="toc-backref" href="#contents">11.1&nbsp;&nbsp;&nbsp;USE_EXPAND flag rename file</a></h2>
 <p>The <a class="reference internal" href="#use-expand-rename">USE_EXPAND_RENAME</a> file contains dictionary-like entries that assign
 <em>effective</em> flag names to flag names generated at runtime.</p>
 <p>The syntax is as follows:</p>
@@ -2637,7 +3142,7 @@ unpredictable results.</p>
 </div>
 </div>
 <div class="section" id="field-definition-config">
-<span id="id4"></span><h2><a class="toc-backref" href="#contents">10.2&nbsp;&nbsp;&nbsp;Field Definition Config</a></h2>
+<span id="id4"></span><h2><a class="toc-backref" href="#contents">11.2&nbsp;&nbsp;&nbsp;Field Definition Config</a></h2>
 <p>The field definition file uses <a class="reference external" href="http://docs.python.org/library/configparser.html">ConfigParser</a> syntax and defines
 how an R package's DESCRIPTION file is read.
 See the next section, <a class="reference internal" href="#default-field-definition-file">default field definition file</a>,  for an example.</p>
@@ -2719,7 +3224,7 @@ such a field is found.</dd>
 <p class="last">It is not checked whether a flag is known or not.</p>
 </div>
 <div class="section" id="example-the-default-field-definition-file">
-<span id="default-field-definition-file"></span><h3><a class="toc-backref" href="#contents">10.2.1&nbsp;&nbsp;&nbsp;Example: The default field definition file</a></h3>
+<span id="default-field-definition-file"></span><h3><a class="toc-backref" href="#contents">11.2.1&nbsp;&nbsp;&nbsp;Example: The default field definition file</a></h3>
 <p>This is the default field definition file (without any ignored fields):</p>
 <pre class="code ini literal-block">
 <span class="keyword">[Description]</span>
@@ -2756,7 +3261,7 @@ such a field is found.</dd>
 </div>
 </div>
 <div class="section" id="dependency-resolution-console">
-<span id="depres-console"></span><h1><a class="toc-backref" href="#contents">11&nbsp;&nbsp;&nbsp;Dependency Resolution Console</a></h1>
+<span id="depres-console"></span><h1><a class="toc-backref" href="#contents">12&nbsp;&nbsp;&nbsp;Dependency Resolution Console</a></h1>
 <p>As previously stated, the <em>DepRes Console</em> is only meant for <strong>testing</strong>.
 It is an interactive console with the following features:</p>
 <ul class="simple">
@@ -2914,13 +3419,13 @@ cmd % exit
 </dl>
 </div>
 <div class="section" id="implementation-overview">
-<h1><a class="toc-backref" href="#contents">12&nbsp;&nbsp;&nbsp;Implementation Overview</a></h1>
+<h1><a class="toc-backref" href="#contents">13&nbsp;&nbsp;&nbsp;Implementation Overview</a></h1>
 <p>This chapter gives an in-depth overview of how roverlay works.
 Code documentation is also available and html pages for it can be created
 with <tt class="docutils literal">make pydoc</tt> in the <em>R Overlay src directory</em> or by using pydoc
 directly.</p>
 <div class="section" id="packageinfo">
-<h2><a class="toc-backref" href="#contents">12.1&nbsp;&nbsp;&nbsp;PackageInfo</a></h2>
+<h2><a class="toc-backref" href="#contents">13.1&nbsp;&nbsp;&nbsp;PackageInfo</a></h2>
 <p><em>PackageInfo</em> is the data object that contains all information about an
 R package and is created by the owning repository.</p>
 <p>After initialization it contains data like</p>
@@ -2941,7 +3446,7 @@ for it. Otherwise, <em>p</em> is now part of the overlay and has to pass
 <em>ebuild creation</em>.</p>
 </div>
 <div class="section" id="repository-management">
-<h2><a class="toc-backref" href="#contents">12.2&nbsp;&nbsp;&nbsp;Repository Management</a></h2>
+<h2><a class="toc-backref" href="#contents">13.2&nbsp;&nbsp;&nbsp;Repository Management</a></h2>
 <p>Repositories are managed in a list-like object, <em>RepoList</em>. Its task is to
 provide R package input for overlay creation and implements the following
 functionality:</p>
@@ -2952,7 +3457,7 @@ functionality:</p>
 <li>create <em>PackageInfo</em> instances for R packages from all repositories</li>
 </ul>
 <div class="section" id="repository">
-<h3><a class="toc-backref" href="#contents">12.2.1&nbsp;&nbsp;&nbsp;Repository</a></h3>
+<h3><a class="toc-backref" href="#contents">13.2.1&nbsp;&nbsp;&nbsp;Repository</a></h3>
 <p>The functionality described above is an abstraction layer that calls the
 respective function for each repository and collects the result.
 So, while the <em>RepoList</em> object knows <em>what</em> to do for all repositories,
@@ -2993,7 +3498,7 @@ subclass-specifc <em>_sync()</em>/<em>_nosync()</em> functions if available.
 repository types, <em>rsync</em>, <em>websync_repo</em> and <em>websync_pkglist</em> derive from
 <em>BasicRepo</em>.</p>
 <div class="section" id="adding-new-repository-types">
-<h4><a class="toc-backref" href="#contents">12.2.1.1&nbsp;&nbsp;&nbsp;Adding new repository types</a></h4>
+<h4><a class="toc-backref" href="#contents">13.2.1.1&nbsp;&nbsp;&nbsp;Adding new repository types</a></h4>
 <p>Adding new repository types is best done by creating a new repo class
 that inherits <em>BasicRepo</em>. The table below shows <em>BasicRepo</em>'s subclass
 awareness concerning <em>sync()</em> and what may be changed if required.
@@ -3080,7 +3585,7 @@ to be accessible.</p>
 </div>
 </div>
 <div class="section" id="overlay">
-<h2><a class="toc-backref" href="#contents">12.3&nbsp;&nbsp;&nbsp;Overlay</a></h2>
+<h2><a class="toc-backref" href="#contents">13.3&nbsp;&nbsp;&nbsp;Overlay</a></h2>
 <p>The <em>overlay</em> is roverlay's central data structure that represents a <em>portage
 overlay</em>. It is organized in a tree structure (overlay root, categories,
 package directories) and implements all overlay-related functionality:</p>
@@ -3111,7 +3616,7 @@ level</p>
 </li>
 </ul>
 <div class="section" id="metadata-creation">
-<h3><a class="toc-backref" href="#contents">12.3.1&nbsp;&nbsp;&nbsp;Metadata Creation</a></h3>
+<h3><a class="toc-backref" href="#contents">13.3.1&nbsp;&nbsp;&nbsp;Metadata Creation</a></h3>
 <p><em>metadata.xml</em> files are created with a tree structure that contains <em>metadata
 nodes</em>, e.g. '&lt;pkgmetadata&gt;...&lt;/pkgmetadata&gt;' and '&lt;use&gt;...&lt;/use&gt;' are <em>nodes</em>.
 The current implementation writes the R package's full description
@@ -3120,7 +3625,7 @@ Metadata creation uses the latest package, i.e. highest version,
 for which an ebuild has been created.</p>
 </div>
 <div class="section" id="manifest-creation">
-<h3><a class="toc-backref" href="#contents">12.3.2&nbsp;&nbsp;&nbsp;Manifest Creation</a></h3>
+<h3><a class="toc-backref" href="#contents">13.3.2&nbsp;&nbsp;&nbsp;Manifest Creation</a></h3>
 <p>Manifest files are created by calling the <em>ebuild</em> executable for each
 package directory in a filtered environment where FETCHCOMMAND and
 RESUMECOMMAND are set to no-operation. The directories that contain the R
@@ -3129,7 +3634,7 @@ is set to <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a
 </div>
 </div>
 <div class="section" id="ebuild-creation">
-<h2><a class="toc-backref" href="#contents">12.4&nbsp;&nbsp;&nbsp;Ebuild Creation</a></h2>
+<h2><a class="toc-backref" href="#contents">13.4&nbsp;&nbsp;&nbsp;Ebuild Creation</a></h2>
 <p>Ebuild creation is the process centered around one <em>PackageInfo</em> instance <em>p</em>
 that tries to create an ebuild for it.</p>
 <p>It does the following steps:</p>
@@ -3148,7 +3653,7 @@ order to save memory etc.</li>
 as <em>ebuild successfully created</em></li>
 </ol>
 <div class="section" id="ebuild-variables">
-<h3><a class="toc-backref" href="#contents">12.4.1&nbsp;&nbsp;&nbsp;Ebuild Variables</a></h3>
+<h3><a class="toc-backref" href="#contents">13.4.1&nbsp;&nbsp;&nbsp;Ebuild Variables</a></h3>
 <p>Each ebuild variable is an object whose class is derived from the <em>EbuildVar</em>
 class. An <em>EbuildVar</em> defines its position in the ebuild and  how its text
 output should look like. Ebuild text is created by adding ebuild variables
@@ -3156,7 +3661,7 @@ to an <em>Ebuilder</em> that automatically sorts them and creates the ebuild.</p
 </div>
 </div>
 <div class="section" id="overlay-creation">
-<h2><a class="toc-backref" href="#contents">12.5&nbsp;&nbsp;&nbsp;Overlay Creation</a></h2>
+<h2><a class="toc-backref" href="#contents">13.5&nbsp;&nbsp;&nbsp;Overlay Creation</a></h2>
 <p>Overlay creation is the process of creating an overlay for many R packages
 and <em>roverlay</em>'s main task. More specifically, <em>OverlayCreation</em> is an
 <em>R packages -&gt; Overlay (-&gt; overlay in filesystem)</em> interface.
@@ -3170,7 +3675,7 @@ instead the event is logged. Running more than one <em>OverlayWorker</em> in par
 is possible.</p>
 </div>
 <div class="section" id="dependency-resolution">
-<h2><a class="toc-backref" href="#contents">12.6&nbsp;&nbsp;&nbsp;Dependency Resolution</a></h2>
+<h2><a class="toc-backref" href="#contents">13.6&nbsp;&nbsp;&nbsp;Dependency Resolution</a></h2>
 <p>Each ebuild creation process has access to the <em>dependency resolver</em> that
 accepts <em>dependency strings</em>, tries to resolve them and returns the result,
 either &quot;unresolvable&quot; or the resolving <em>dependency</em> as
@@ -3192,7 +3697,7 @@ all <em>required dependencies</em>. No ebuild can be created in that case.</li>
 <p>Details about dependency resolution like how <em>channels</em> work can be found
 in the following subsections.</p>
 <div class="section" id="dependency-types">
-<h3><a class="toc-backref" href="#contents">12.6.1&nbsp;&nbsp;&nbsp;Dependency types</a></h3>
+<h3><a class="toc-backref" href="#contents">13.6.1&nbsp;&nbsp;&nbsp;Dependency types</a></h3>
 <p>Every <em>dependency string</em> has a <em>dependency type</em> that declares how a
 dependency should be resolved. It has one or more of these properties:</p>
 <dl class="docutils">
@@ -3221,7 +3726,7 @@ The <em>Suggests</em> field, for example, gets the
 <em>&quot;package dependency only and optional&quot;</em> type, whereas the <em>SystemRequirements</em>
 gets <em>&quot;system dependency, but try others, and mandatory&quot;</em>.</p>
 <div class="section" id="description-file-dependency-fields">
-<h4><a class="toc-backref" href="#contents">12.6.1.1&nbsp;&nbsp;&nbsp;DESCRIPTION file dependency fields</a></h4>
+<h4><a class="toc-backref" href="#contents">13.6.1.1&nbsp;&nbsp;&nbsp;DESCRIPTION file dependency fields</a></h4>
 <p>The DESCRIPTION file of an R package contains several fields that list
 dependencies on R packages or other software like scientific libraries.
 This section describes which <em>dependency fields</em> are used and how.</p>
@@ -3280,7 +3785,7 @@ but optional dependencies during the <em>pkg_postinst()</em> ebuild phase.</p>
 </div>
 </div>
 <div class="section" id="dependency-environments">
-<h3><a class="toc-backref" href="#contents">12.6.2&nbsp;&nbsp;&nbsp;Dependency Environments</a></h3>
+<h3><a class="toc-backref" href="#contents">13.6.2&nbsp;&nbsp;&nbsp;Dependency Environments</a></h3>
 <p>A <em>dependency environment</em> is an object that reflects the whole dependency
 resolution process of a single <em>dependency string</em>. It usually contains
 the <em>dependency string</em>, its <em>dependency type</em>, information about its
@@ -3290,7 +3795,7 @@ resolving resolving <em>dependency</em>, if any.</p>
 <em>dependency resolver</em>.</p>
 </div>
 <div class="section" id="ebuildjob-channel">
-<h3><a class="toc-backref" href="#contents">12.6.3&nbsp;&nbsp;&nbsp;EbuildJob Channel</a></h3>
+<h3><a class="toc-backref" href="#contents">13.6.3&nbsp;&nbsp;&nbsp;EbuildJob Channel</a></h3>
 <p>The <em>EbuildJob Channel</em> is used by the ebuild creation to communicate with
 the <em>dependency resolver</em>. It is initialized by an ebuild creation process and
 realizes a greedy <em>string to string</em> dependency resolution.</p>
@@ -3327,7 +3832,7 @@ dependencies are unresolvable.</li>
 </ol>
 </div>
 <div class="section" id="dependency-rule-pools">
-<h3><a class="toc-backref" href="#contents">12.6.4&nbsp;&nbsp;&nbsp;Dependency Rule Pools</a></h3>
+<h3><a class="toc-backref" href="#contents">13.6.4&nbsp;&nbsp;&nbsp;Dependency Rule Pools</a></h3>
 <p>The <em>dependency resolver</em> does not know <em>how</em> to resolve a <em>dependency string</em>.
 Instead, it searches through a list of <em>dependency rule pools</em> that may be
 able to do this.</p>
@@ -3350,7 +3855,7 @@ R package dependencies.
 By convention, it will never resolve any system dependencies.</p>
 </div>
 <div class="section" id="dependency-resolver-modules">
-<h3><a class="toc-backref" href="#contents">12.6.5&nbsp;&nbsp;&nbsp;Dependency Resolver Modules</a></h3>
+<h3><a class="toc-backref" href="#contents">13.6.5&nbsp;&nbsp;&nbsp;Dependency Resolver Modules</a></h3>
 <p>The dependency resolver can be extended by modules. Two base types are
 available, <em>channels</em> and <em>listeners</em>.</p>
 <dl class="docutils">
@@ -3370,7 +3875,7 @@ resolution, wait for results, and send them to the other end.</p>
 </dl>
 </div>
 <div class="section" id="dependency-resolver">
-<h3><a class="toc-backref" href="#contents">12.6.6&nbsp;&nbsp;&nbsp;Dependency Resolver</a></h3>
+<h3><a class="toc-backref" href="#contents">13.6.6&nbsp;&nbsp;&nbsp;Dependency Resolver</a></h3>
 <p>The dependency resolver puts all parts of dependency resolution together,
 <em>rule pools</em>, <em>listeners</em> and <em>channels</em>. Its main task is a loop that
 processes all queued <em>dependency environments</em> and sends the result back to
@@ -3428,7 +3933,7 @@ becomes &quot;loop until resolver closes&quot;.</p>
 </div>
 <div class="footer">
 <hr class="footer" />
-Generated on: 2013-06-18.
+Generated on: 2013-06-26.
 
 </div>
 </body>