diff options
| author |   André Erdmann <dywi@mailerd.de> | 2013-06-26 19:29:01 +0200 |
|---|---|---|
| committer | André Erdmann <dywi@mailerd.de> | 2013-06-26 19:29:01 +0200 |
| commit | 664ec1f39a920328e3ca4cf7f5f091eaa55d51d0 (patch) | |
| tree | e69b82531f0e4b4832c5278948a4d8381237244c /doc | |
| parent | doc/rst: "run hooks", "distmap" (diff) | |
| download | R_overlay-664ec1f39a920328e3ca4cf7f5f091eaa55d51d0.tar.gz R_overlay-664ec1f39a920328e3ca4cf7f5f091eaa55d51d0.tar.bz2 R_overlay-664ec1f39a920328e3ca4cf7f5f091eaa55d51d0.zip | |
doc/html: "run hooks", "distmap"
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/html/usage.html | 667 |
1 files 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 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 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 Using local directories</a></li> +<li><a class="reference internal" href="#distmap" id="id27">5.6 distmap</a></li> </ul> </li> -<li><a class="reference internal" href="#additions-directory" id="id27">6 Additions Directory</a><ul class="auto-toc"> -<li><a class="reference internal" href="#patching-ebuilds" id="id28">6.1 Patching ebuilds</a></li> -<li><a class="reference internal" href="#importing-ebuilds" id="id29">6.2 Importing ebuilds</a></li> +<li><a class="reference internal" href="#additions-directory" id="id28">6 Additions Directory</a><ul class="auto-toc"> +<li><a class="reference internal" href="#patching-ebuilds" id="id29">6.1 Patching ebuilds</a></li> +<li><a class="reference internal" href="#importing-ebuilds" id="id30">6.2 Importing ebuilds</a></li> </ul> </li> -<li><a class="reference internal" href="#dependency-rules" id="id30">7 Dependency Rules</a><ul class="auto-toc"> -<li><a class="reference internal" href="#simple-dependency-rules" id="id31">7.1 Simple Dependency Rules</a><ul class="auto-toc"> -<li><a class="reference internal" href="#rule-variants" id="id32">7.1.1 Rule Variants</a></li> -<li><a class="reference internal" href="#rule-types" id="id33">7.1.2 Rule types</a></li> -<li><a class="reference internal" href="#rule-file-examples" id="id34">7.1.3 Rule File Examples</a></li> -<li><a class="reference internal" href="#rule-file-syntax" id="id35">7.1.4 Rule File Syntax</a></li> +<li><a class="reference internal" href="#dependency-rules" id="id31">7 Dependency Rules</a><ul class="auto-toc"> +<li><a class="reference internal" href="#simple-dependency-rules" id="id32">7.1 Simple Dependency Rules</a><ul class="auto-toc"> +<li><a class="reference internal" href="#rule-variants" id="id33">7.1.1 Rule Variants</a></li> +<li><a class="reference internal" href="#rule-types" id="id34">7.1.2 Rule types</a></li> +<li><a class="reference internal" href="#rule-file-examples" id="id35">7.1.3 Rule File Examples</a></li> +<li><a class="reference internal" href="#rule-file-syntax" id="id36">7.1.4 Rule File Syntax</a></li> </ul> </li> </ul> </li> -<li><a class="reference internal" href="#package-rules" id="id36">8 Package Rules</a><ul class="auto-toc"> -<li><a class="reference internal" href="#package-rule-file-syntax" id="id37">8.1 Package Rule File Syntax</a><ul class="auto-toc"> -<li><a class="reference internal" href="#match-blocks" id="id38">8.1.1 Match Blocks</a><ul class="auto-toc"> -<li><a class="reference internal" href="#extended-match-block-syntax" id="id39">8.1.1.1 Extended Match Block Syntax</a></li> +<li><a class="reference internal" href="#package-rules" id="id37">8 Package Rules</a><ul class="auto-toc"> +<li><a class="reference internal" href="#package-rule-file-syntax" id="id38">8.1 Package Rule File Syntax</a><ul class="auto-toc"> +<li><a class="reference internal" href="#match-blocks" id="id39">8.1.1 Match Blocks</a><ul class="auto-toc"> +<li><a class="reference internal" href="#extended-match-block-syntax" id="id40">8.1.1.1 Extended Match Block Syntax</a></li> </ul> </li> -<li><a class="reference internal" href="#action-blocks" id="id40">8.1.2 Action Blocks</a><ul class="auto-toc"> -<li><a class="reference internal" href="#extended-action-block-syntax" id="id41">8.1.2.1 Extended Action Block Syntax</a></li> +<li><a class="reference internal" href="#action-blocks" id="id41">8.1.2 Action Blocks</a><ul class="auto-toc"> +<li><a class="reference internal" href="#extended-action-block-syntax" id="id42">8.1.2.1 Extended Action Block Syntax</a></li> </ul> </li> -<li><a class="reference internal" href="#package-rule-examples" id="id42">8.1.3 Package Rule Examples</a></li> +<li><a class="reference internal" href="#package-rule-examples" id="id43">8.1.3 Package Rule Examples</a></li> </ul> </li> </ul> </li> -<li><a class="reference internal" href="#configuration-reference" id="id43">9 Configuration Reference</a><ul class="auto-toc"> -<li><a class="reference internal" href="#misc-options" id="id44">9.1 misc options</a></li> -<li><a class="reference internal" href="#overlay-options" id="id45">9.2 overlay options</a></li> -<li><a class="reference internal" href="#other-config-files" id="id46">9.3 other config files</a></li> -<li><a class="reference internal" href="#logging" id="id47">9.4 logging</a><ul class="auto-toc"> -<li><a class="reference internal" href="#console-logging" id="id48">9.4.1 console logging</a></li> -<li><a class="reference internal" href="#file-logging" id="id49">9.4.2 file logging</a></li> +<li><a class="reference internal" href="#event-hooks" id="id44">9 Event Hooks</a><ul class="auto-toc"> +<li><a class="reference internal" href="#default-event-script" id="id45">9.1 Default event script</a><ul class="auto-toc"> +<li><a class="reference internal" href="#activating-a-hook-script" id="id46">9.1.1 Activating a hook script</a></li> +<li><a class="reference internal" href="#adding-a-new-hook-script" id="id47">9.1.2 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 options for debugging, manual dependency rule creation and testing</a></li> +<li><a class="reference internal" href="#event-policy" id="id48">9.2 Event Policy</a></li> +<li><a class="reference internal" href="#hook-environment" id="id49">9.3 Hook Environment</a></li> +<li><a class="reference internal" href="#adding-a-function-file" id="id50">9.4 Adding a function file</a></li> +<li><a class="reference internal" href="#adding-a-hook-event" id="id51">9.5 Adding a hook event</a></li> </ul> </li> -<li><a class="reference internal" href="#id3" id="id51">10 Other config files</a><ul class="auto-toc"> -<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id52">10.1 USE_EXPAND flag rename file</a></li> -<li><a class="reference internal" href="#field-definition-config" id="id53">10.2 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 Example: The default field definition file</a></li> +<li><a class="reference internal" href="#configuration-reference" id="id52">10 Configuration Reference</a><ul class="auto-toc"> +<li><a class="reference internal" href="#misc-options" id="id53">10.1 misc options</a></li> +<li><a class="reference internal" href="#overlay-options" id="id54">10.2 overlay options</a></li> +<li><a class="reference internal" href="#other-config-files" id="id55">10.3 other config files</a></li> +<li><a class="reference internal" href="#shell-environment-hooks" id="id56">10.4 shell environment / hooks</a></li> +<li><a class="reference internal" href="#logging" id="id57">10.5 logging</a><ul class="auto-toc"> +<li><a class="reference internal" href="#console-logging" id="id58">10.5.1 console logging</a></li> +<li><a class="reference internal" href="#file-logging" id="id59">10.5.2 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 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 Dependency Resolution Console</a></li> -<li><a class="reference internal" href="#implementation-overview" id="id56">12 Implementation Overview</a><ul class="auto-toc"> -<li><a class="reference internal" href="#packageinfo" id="id57">12.1 PackageInfo</a></li> -<li><a class="reference internal" href="#repository-management" id="id58">12.2 Repository Management</a><ul class="auto-toc"> -<li><a class="reference internal" href="#repository" id="id59">12.2.1 Repository</a><ul class="auto-toc"> -<li><a class="reference internal" href="#adding-new-repository-types" id="id60">12.2.1.1 Adding new repository types</a></li> +<li><a class="reference internal" href="#id3" id="id61">11 Other config files</a><ul class="auto-toc"> +<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id62">11.1 USE_EXPAND flag rename file</a></li> +<li><a class="reference internal" href="#field-definition-config" id="id63">11.2 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 Example: The default field definition file</a></li> </ul> </li> </ul> </li> -<li><a class="reference internal" href="#overlay" id="id61">12.3 Overlay</a><ul class="auto-toc"> -<li><a class="reference internal" href="#metadata-creation" id="id62">12.3.1 Metadata Creation</a></li> -<li><a class="reference internal" href="#manifest-creation" id="id63">12.3.2 Manifest Creation</a></li> +<li><a class="reference internal" href="#dependency-resolution-console" id="id65">12 Dependency Resolution Console</a></li> +<li><a class="reference internal" href="#implementation-overview" id="id66">13 Implementation Overview</a><ul class="auto-toc"> +<li><a class="reference internal" href="#packageinfo" id="id67">13.1 PackageInfo</a></li> +<li><a class="reference internal" href="#repository-management" id="id68">13.2 Repository Management</a><ul class="auto-toc"> +<li><a class="reference internal" href="#repository" id="id69">13.2.1 Repository</a><ul class="auto-toc"> +<li><a class="reference internal" href="#adding-new-repository-types" id="id70">13.2.1.1 Adding new repository types</a></li> </ul> </li> -<li><a class="reference internal" href="#ebuild-creation" id="id64">12.4 Ebuild Creation</a><ul class="auto-toc"> -<li><a class="reference internal" href="#ebuild-variables" id="id65">12.4.1 Ebuild Variables</a></li> </ul> </li> -<li><a class="reference internal" href="#overlay-creation" id="id66">12.5 Overlay Creation</a></li> -<li><a class="reference internal" href="#dependency-resolution" id="id67">12.6 Dependency Resolution</a><ul class="auto-toc"> -<li><a class="reference internal" href="#dependency-types" id="id68">12.6.1 Dependency types</a><ul class="auto-toc"> -<li><a class="reference internal" href="#description-file-dependency-fields" id="id69">12.6.1.1 DESCRIPTION file dependency fields</a></li> +<li><a class="reference internal" href="#overlay" id="id71">13.3 Overlay</a><ul class="auto-toc"> +<li><a class="reference internal" href="#metadata-creation" id="id72">13.3.1 Metadata Creation</a></li> +<li><a class="reference internal" href="#manifest-creation" id="id73">13.3.2 Manifest Creation</a></li> </ul> </li> -<li><a class="reference internal" href="#dependency-environments" id="id70">12.6.2 Dependency Environments</a></li> -<li><a class="reference internal" href="#ebuildjob-channel" id="id71">12.6.3 EbuildJob Channel</a></li> -<li><a class="reference internal" href="#dependency-rule-pools" id="id72">12.6.4 Dependency Rule Pools</a></li> -<li><a class="reference internal" href="#dependency-resolver-modules" id="id73">12.6.5 Dependency Resolver Modules</a></li> -<li><a class="reference internal" href="#dependency-resolver" id="id74">12.6.6 Dependency Resolver</a></li> +<li><a class="reference internal" href="#ebuild-creation" id="id74">13.4 Ebuild Creation</a><ul class="auto-toc"> +<li><a class="reference internal" href="#ebuild-variables" id="id75">13.4.1 Ebuild Variables</a></li> +</ul> +</li> +<li><a class="reference internal" href="#overlay-creation" id="id76">13.5 Overlay Creation</a></li> +<li><a class="reference internal" href="#dependency-resolution" id="id77">13.6 Dependency Resolution</a><ul class="auto-toc"> +<li><a class="reference internal" href="#dependency-types" id="id78">13.6.1 Dependency types</a><ul class="auto-toc"> +<li><a class="reference internal" href="#description-file-dependency-fields" id="id79">13.6.1.1 DESCRIPTION file dependency fields</a></li> +</ul> +</li> +<li><a class="reference internal" href="#dependency-environments" id="id80">13.6.2 Dependency Environments</a></li> +<li><a class="reference internal" href="#ebuildjob-channel" id="id81">13.6.3 EbuildJob Channel</a></li> +<li><a class="reference internal" href="#dependency-rule-pools" id="id82">13.6.4 Dependency Rule Pools</a></li> +<li><a class="reference internal" href="#dependency-resolver-modules" id="id83">13.6.5 Dependency Resolver Modules</a></li> +<li><a class="reference internal" href="#dependency-resolver" id="id84">13.6.6 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> </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> </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> </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 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 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 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 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/<event> that end with <em>.sh</em> +(<tt class="docutils literal"><span class="pre"><ADDITIONS_DIR>/hooks/<event>/*.sh</span></tt>)</li> +<li>all files <a class="reference internal" href="#additions-dir">ADDITIONS_DIR</a>/hooks that end with <em>.<event></em> +(<tt class="docutils literal"><span class="pre"><ADDITIONS_DIR>/hooks/*.<event></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 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 <real script> ${ADDITIONS_DIR}/hooks/<event>/<name>.sh +# or +ln -s <real script> ${ADDITIONS_DIR}/hooks/<name>.<event> +</pre> +</div> +<div class="section" id="adding-a-new-hook-script"> +<h3><a class="toc-backref" href="#contents">9.1.2 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">"${FUNCTIONS?}"</span> <span class="operator">||</span> <span class="name builtin">exit</span> + +<span class="comment">## load additional function files, if any +#$lf <name(s)> +</span> +<span class="comment"># script body +# +# when redirecting output to $DEVNULL, use ">>" instead of ">" as +# $DEVNULL could be a file +#ls >>${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 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> (-> 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> (-> 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 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> </td> +</tr> +<tr><td>LOGNAME</td> +<td>os.environ</td> +<td> </td> +</tr> +<tr><td>SHLVL</td> +<td>os.environ</td> +<td> </td> +</tr> +<tr><td>TERM</td> +<td>os.environ</td> +<td> </td> +</tr> +<tr><td>HOME</td> +<td>os.environ</td> +<td> </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 --- +# +# @noreturn die ( [message], [exit_code] ), raises exit() +# Lets the script die with the given message/exit code. +# +# @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 "which", 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 "yes", $YESNO_EMPTY if $word is empty +# and $YESNO_NO otherwise (if $word probably means "no"). +# +# ~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 >= 0, else 1. +# +# int is_positive ( word ) +# Returns 0 if $word is an integer >= 1, else 1. +# +# int is_negative ( word ) +# Returns 0 if $word is an integer < 0, else 1. +#</span> +</pre> +</div> +<div class="section" id="adding-a-function-file"> +<h2><a class="toc-backref" href="#contents">9.4 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 <name> with a unique identifier) +</span><span class="keyword">if</span> <span class="operator">[</span> -z <span class="literal string double">"${__HAVE_<name>__-}"</span> <span class="operator">]</span>; <span class="keyword">then +</span><span class="name builtin">readonly </span>__HAVE_<name>__<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"><ADDITIONS_DIR>/shlib</span></tt>.</p> +</div> +<div class="section" id="adding-a-hook-event"> +<h2><a class="toc-backref" href="#contents">9.5 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">"<event>"</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">"<another event>"</span> <span class="punctuation">)</span> +</pre> +</div> +</div> <div class="section" id="configuration-reference"> -<h1><a class="toc-backref" href="#contents">9 Configuration Reference</a></h1> +<h1><a class="toc-backref" href="#contents">10 Configuration Reference</a></h1> <p>The main config file uses '<option> = <value>' syntax, comment lines start with <strong>#</strong>. Variable substitution ("${X}") 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 misc options</a></h2> +<h2><a class="toc-backref" href="#contents">10.1 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"><<TODO: default value!>></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=<value>' to all rsync commands.</p> </dl> </div> <div class="section" id="overlay-options"> -<h2><a class="toc-backref" href="#contents">9.2 overlay options</a></h2> +<h2><a class="toc-backref" href="#contents">10.2 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=<value>' 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, "hardlink symlink".</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 <not set>, 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 other config files</a></h2> +<h2><a class="toc-backref" href="#contents">10.3 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 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 <libexec dir>/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"><event></tt>, <tt class="docutils literal">+<event></tt>) or +forbidden (<tt class="docutils literal"><span class="pre">-<event></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 <not set>, which is equivalent to <em>deny all</em>.</p> +<p class="last"><tt class="docutils literal"><span class="pre">EVENT_HOOK_RESTRICT="overlay_success"</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="*</span> <span class="pre">-overlay_success"</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 logging</a></h2> +<h2><a class="toc-backref" href="#contents">10.5 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 console logging</a></h3> +<h3><a class="toc-backref" href="#contents">10.5.1 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 file logging</a></h3> +<h3><a class="toc-backref" href="#contents">10.5.2 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 options for debugging, manual dependency rule creation and testing</a></h2> +<h2><a class="toc-backref" href="#contents">10.6 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 Other config files</a></h1> +<h1><a class="toc-backref" href="#contents">11 Other config files</a></h1> <div class="section" id="use-expand-flag-rename-file"> -<h2><a class="toc-backref" href="#contents">10.1 USE_EXPAND flag rename file</a></h2> +<h2><a class="toc-backref" href="#contents">11.1 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 Field Definition Config</a></h2> +<span id="id4"></span><h2><a class="toc-backref" href="#contents">11.2 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 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 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 Dependency Resolution Console</a></h1> +<span id="depres-console"></span><h1><a class="toc-backref" href="#contents">12 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 Implementation Overview</a></h1> +<h1><a class="toc-backref" href="#contents">13 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 PackageInfo</a></h2> +<h2><a class="toc-backref" href="#contents">13.1 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 Repository Management</a></h2> +<h2><a class="toc-backref" href="#contents">13.2 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 Repository</a></h3> +<h3><a class="toc-backref" href="#contents">13.2.1 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 Adding new repository types</a></h4> +<h4><a class="toc-backref" href="#contents">13.2.1.1 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 Overlay</a></h2> +<h2><a class="toc-backref" href="#contents">13.3 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 Metadata Creation</a></h3> +<h3><a class="toc-backref" href="#contents">13.3.1 Metadata Creation</a></h3> <p><em>metadata.xml</em> files are created with a tree structure that contains <em>metadata nodes</em>, e.g. '<pkgmetadata>...</pkgmetadata>' and '<use>...</use>' 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 Manifest Creation</a></h3> +<h3><a class="toc-backref" href="#contents">13.3.2 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 Ebuild Creation</a></h2> +<h2><a class="toc-backref" href="#contents">13.4 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 Ebuild Variables</a></h3> +<h3><a class="toc-backref" href="#contents">13.4.1 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 Overlay Creation</a></h2> +<h2><a class="toc-backref" href="#contents">13.5 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 -> Overlay (-> 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 Dependency Resolution</a></h2> +<h2><a class="toc-backref" href="#contents">13.6 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 "unresolvable" 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 Dependency types</a></h3> +<h3><a class="toc-backref" href="#contents">13.6.1 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>"package dependency only and optional"</em> type, whereas the <em>SystemRequirements</em> gets <em>"system dependency, but try others, and mandatory"</em>.</p> <div class="section" id="description-file-dependency-fields"> -<h4><a class="toc-backref" href="#contents">12.6.1.1 DESCRIPTION file dependency fields</a></h4> +<h4><a class="toc-backref" href="#contents">13.6.1.1 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 Dependency Environments</a></h3> +<h3><a class="toc-backref" href="#contents">13.6.2 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 EbuildJob Channel</a></h3> +<h3><a class="toc-backref" href="#contents">13.6.3 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 Dependency Rule Pools</a></h3> +<h3><a class="toc-backref" href="#contents">13.6.4 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 Dependency Resolver Modules</a></h3> +<h3><a class="toc-backref" href="#contents">13.6.5 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 Dependency Resolver</a></h3> +<h3><a class="toc-backref" href="#contents">13.6.6 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 "loop until resolver closes".</p> </div> <div class="footer"> <hr class="footer" /> -Generated on: 2013-06-18. +Generated on: 2013-06-26. </div> </body> |