* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2012-08-10 15:16 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2012-08-10 15:16 UTC (permalink / raw
To: gentoo-commits
commit: 5f3b0a89628725c8d6d0fe0a683de1d53309d30b
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Aug 10 15:12:09 2012 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Aug 10 15:12:09 2012 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=5f3b0a89
usage guide as html doc
---
doc/html/usage.html | 1352 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 1352 insertions(+), 0 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
new file mode 100644
index 0000000..8027b22
--- /dev/null
+++ b/doc/html/usage.html
@@ -0,0 +1,1352 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.9: http://docutils.sourceforge.net/" />
+<title></title>
+<style type="text/css">
+
+/*
+:Author: David Goodger (goodger@python.org)
+:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+ border: 0 }
+
+table.borderless td, table.borderless th {
+ /* Override padding for "table.docutils td" with "! important".
+ The right padding separates the table cells. */
+ padding: 0 0.5em 0 0 ! important }
+
+.first {
+ /* Override more specific margin styles with "! important". */
+ margin-top: 0 ! important }
+
+.last, .with-subtitle {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dl.docutils dd {
+ margin-bottom: 0.5em }
+
+object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
+ overflow: hidden;
+}
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+ font-weight: bold }
+*/
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+ compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+ margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+ margin-top: 0.5em }
+*/
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+div.footer, div.header {
+ clear: both;
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin: 0 0 0.5em 1em ;
+ border: medium outset ;
+ padding: 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+ margin-top: 0.4em }
+
+h1.title {
+ text-align: center }
+
+h2.subtitle {
+ text-align: center }
+
+hr.docutils {
+ width: 75% }
+
+img.align-left, .figure.align-left, object.align-left {
+ clear: left ;
+ float: left ;
+ margin-right: 1em }
+
+img.align-right, .figure.align-right, object.align-right {
+ clear: right ;
+ float: right ;
+ margin-left: 1em }
+
+img.align-center, .figure.align-center, object.align-center {
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+.align-left {
+ text-align: left }
+
+.align-center {
+ clear: both ;
+ text-align: center }
+
+.align-right {
+ text-align: right }
+
+/* reset inner alignment in figures */
+div.align-right {
+ text-align: inherit }
+
+/* div.align-center * { */
+/* text-align: left } */
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font: inherit }
+
+pre.literal-block, pre.doctest-block, pre.math {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+span.section-subtitle {
+ /* font-size relative to parent (h1..h6 element) */
+ font-size: 80% }
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px }
+
+table.docinfo {
+ margin: 2em 4em }
+
+table.docutils {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.footnote {
+ border-left: solid 1px black;
+ margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap ;
+ padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+ font-size: 100% }
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document">
+
+
+<div class="contents topic" id="contents">
+<p class="topic-title first">Contents</p>
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#installation" id="id2">Installation</a><ul>
+<li><a class="reference internal" href="#prerequisites" id="id3">Prerequisites</a></li>
+<li><a class="reference internal" href="#via-emerge-gentoo" id="id4">via emerge (Gentoo)</a></li>
+<li><a class="reference internal" href="#manual-installation" id="id5">Manual Installation</a></li>
+<li><a class="reference internal" href="#using-roverlay-without-installation" id="id6">Using <em>roverlay</em> without installation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#running-roverlay" id="id7">Running Roverlay</a><ul>
+<li><a class="reference internal" href="#required-configuration-steps" id="id8">Required configuration steps</a></li>
+<li><a class="reference internal" href="#running-it" id="id9">Running it</a></li>
+<li><a class="reference internal" href="#providing-a-package-mirror" id="id10">Providing a package mirror</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#implementation-overview" id="id11">Implementation Overview</a><ul>
+<li><a class="reference internal" href="#repositories-getting-packages" id="id12">Repositories / Getting Packages</a><ul>
+<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id13">A word about repo config files</a></li>
+<li><a class="reference internal" href="#rsync-repos" id="id14">Rsync repos</a></li>
+<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id15">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="id16">Getting packages from several remotes using http and a package list</a></li>
+<li><a class="reference internal" href="#using-local-directories" id="id17">Using local directories</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dependency-rules-resolving-dependencies" id="id18">Dependency Rules / Resolving Dependencies</a><ul>
+<li><a class="reference internal" href="#dependency-types" id="id19">Dependency types</a></li>
+<li><a class="reference internal" href="#simple-dependency-rules" id="id20">Simple Dependency Rules</a><ul>
+<li><a class="reference internal" href="#rule-variants" id="id21">Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id22">Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id23">Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id24">Rule File Syntax</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id25">Expected Overlay Result / Structure of the generated overlay</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#configuration-reference" id="id26">Configuration Reference</a><ul>
+<li><a class="reference internal" href="#dependency-rules" id="id27">Dependency Rules</a></li>
+<li><a class="reference internal" href="#repositories" id="id28">Repositories</a></li>
+<li><a class="reference internal" href="#main-config" id="id29">Main Config</a></li>
+<li><a class="reference internal" href="#field-definition" id="id30">Field Definition</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#appendix" id="id31">Appendix</a><ul>
+<li><a class="reference internal" href="#default-field-definition-file" id="id32">Default Field Definition File</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h1><a class="toc-backref" href="#id1">Introduction</a></h1>
+<p><em>roverlay</em> is
+Automatically Generated Overlay of R packages;;
+GSoC Project;;
+<>;;</p>
+</div>
+<div class="section" id="installation">
+<h1><a class="toc-backref" href="#id2">Installation</a></h1>
+<div class="section" id="prerequisites">
+<h2><a class="toc-backref" href="#id3">Prerequisites</a></h2>
+<ul>
+<li><p class="first">python >= 2.7 (tested with python 2.7 and 3.2)</p>
+</li>
+<li><p class="first">argparse (<a class="reference external" href="http://code.google.com/p/argparse">http://code.google.com/p/argparse</a>)</p>
+</li>
+<li><p class="first">rsync (for using rsync repositories)</p>
+</li>
+<li><p class="first">for Manifest creation:</p>
+<ul class="simple">
+<li><em>ebuild</em> from portage</li>
+<li><em>true</em> or <em>echo</em> from coreutils or busybox for preventing
+package downloads during Manifest creation (optional)</li>
+</ul>
+</li>
+<li><p class="first">for generating documentation files: python docutils > 0.8.1</p>
+</li>
+<li><p class="first">hardware requirements (when the default configuration):</p>
+<blockquote>
+<dl class="docutils">
+<dt>disk</dt>
+<dd><ul class="first last simple">
+<li>a filesystem that supports symbolic links</li>
+<li>50-55GB disk space for the R packages when using the default
+R package hosts (CRAN with archive, BIOC, R-Forge and Omegahat)</li>
+<li><a lot of inodes for PORTAGE_RO_DISTDIR/__tmp__ and the overlay></li>
+</ul>
+</dd>
+<dt>memory</dt>
+<dd><p class="first last">up to 600MB which depends on the amount of processed packages and the
+write mechanism in use. The amount can be halved (approximately) when
+using a slower one.</p>
+</dd>
+<dt>other</dt>
+<dd><p class="first last">No other hardware requirements. <as a measurement for computing speed,
+i/o requirements:
+overlay creation takes 3-4h on modern desktop hardware with overlay
+writing to a tmpfs, most time is spent for Manifest creation></p>
+</dd>
+</dl>
+</blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="via-emerge-gentoo">
+<h2><a class="toc-backref" href="#id4">via emerge (Gentoo)</a></h2>
+<p>A live ebuild is available, <a class="reference external" href="http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=blob;f=roverlay-9999.ebuild;hb=refs/heads/master">roverlay-9999.ebuild</a>.
+Add it to your local overlay and run <tt class="docutils literal">emerge roverlay</tt>, which will also
+install all config files into <em>/etc/roverlay</em>.</p>
+</div>
+<div class="section" id="manual-installation">
+<h2><a class="toc-backref" href="#id5">Manual Installation</a></h2>
+<p>After installing the dependencies as listed in <a class="reference internal" href="#prerequisites">Prerequisites</a>,
+clone the <a class="reference external" href="http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=summary">roverlay git repo</a> and then
+install <em>roverlay</em> and its python modules:</p>
+<pre class="code sh literal-block">
+git clone git://git.overlays.gentoo.org/proj/R_overlay.git
+
+<span class="nb">cd </span>R_overlay <span class="o">&&</span> make install
+</pre>
+<p><tt class="docutils literal">make install</tt> also accepts some variables, namely:</p>
+<ul class="simple">
+<li><em>DESTDIR</em> defaults to ''</li>
+<li><em>BINDIR</em>, defaults to <em>DESTDIR</em>/usr/local/bin</li>
+<li><em>PYMOD_FILE_LIST</em>, which lists the installed python module files
+and defaults to './roverlay_files.list'</li>
+<li><em>PYTHON</em>, name of path of the python interpreter that will run 'setup.py',
+defaults to 'python'</li>
+</ul>
+<p><em>roverlay</em> can later be uninstalled with <tt class="docutils literal">make uninstall</tt>.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">Make sure to include <tt class="docutils literal"><span class="pre">--record</span> <span class="pre"><somewhere>/roverlay_files.list</span></tt>
+when running <tt class="docutils literal">./setup.py install</tt> manually,
+which can later be used to safely remove the python module files with
+<tt class="docutils literal">xargs rm <span class="pre">-vrf</span> < <span class="pre"><somewhere>/roverlay_files.list</span></tt>.
+The <em>make</em> targets take care of this.</p>
+</div>
+<div class="warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Support for this installation type is limited - it won't install/create
+any config files!</p>
+</div>
+</div>
+<div class="section" id="using-roverlay-without-installation">
+<h2><a class="toc-backref" href="#id6">Using <em>roverlay</em> without installation</a></h2>
+<p>This is possible, too. Make sure to meet the dependencies as listed
+in <a class="reference internal" href="#prerequisites">Prerequisites</a>.
+Then, simply clone the git repository to a local directory that
+will later be referenced as the <em>R Overlay src directory</em>.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>You'll have to cd into the <em>R Overlay src directory</em> before running
+<em>roverlay</em> to ensure that the python modules can be imported correctly.</p>
+<p>You can work around this by setting up a wrapper script:</p>
+<pre class="code sh last literal-block">
+<span class="c">#!/bin/sh
+# /usr/local/bin/roverlay.sh
+# example wrapper script for roverlay
+</span><span class="nb">cd</span> <span class="k">${</span><span class="nv">ROVERLAY_SRC</span><span class="k">:-</span><span class="p">~/roverlay/src</span><span class="k">}</span> <span class="o">&&</span> ./roverlay.py <span class="nv">$*</span>
+</pre>
+</div>
+</div>
+</div>
+<div class="section" id="running-roverlay">
+<h1><a class="toc-backref" href="#id7">Running Roverlay</a></h1>
+<div class="section" id="required-configuration-steps">
+<h2><a class="toc-backref" href="#id8">Required configuration steps</a></h2>
+<p><em>roverlay</em> needs a configuration file to run.</p>
+<p>If you've installed <em>roverlay</em> with <em>emerge</em>, it will look for the config
+file in that order:</p>
+<ol class="arabic simple">
+<li><em><current directory>/R-overlay.conf</em></li>
+<li><em>~/.R-overlay.conf</em></li>
+<li><em>/etc/roverlay/R-overlay.conf</em>,
+which is part of the installation but has to be modified.</li>
+</ol>
+<p>Otherwise, an example config file is available in the <em>R Overlay src directory</em>
+and <em>roverlay</em> will only look for <em>R-overlay.conf</em> in the current directory.</p>
+<p>The config file is a text file with '<option> = <value>' syntax.
+Some options accept multiple values (e.g. <option> = file1, file2), in which
+case the values have to be enclosed
+with quotes (-> <tt class="docutils literal"><option> = "file1 file2"</tt>).</p>
+<p>The following options should be set before running <em>roverlay</em>:</p>
+<blockquote>
+<dl class="docutils">
+<dt>OVERLAY_DIR</dt>
+<dd><p class="first">This sets the directory of the overlay that will be created.
+This option is <strong>required</strong> and can be overridden on the command line
+via <tt class="docutils literal"><span class="pre">--overlay</span> <directory></tt>.</p>
+<p class="last">Example: OVERLAY_DIR = ~/roverlay/overlay</p>
+</dd>
+<dt>DISTFILES</dt>
+<dd><p class="first">This sets the root directory of all per-repo package directories.
+This option is <strong>required</strong> and can be overridden on the command line
+via <tt class="docutils literal"><span class="pre">--distroot</span> <directory></tt>.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This directory will also contain a directory <em>__tmp__</em>
+with symlinks to all packages which can be used as package mirror,
+see <a class="reference internal" href="#providing-a-package-mirror">Providing a package mirror</a>.</p>
+</div>
+<p class="last">Example: DISTFILES = ~/roverlay/distfiles</p>
+</dd>
+<dt>LOG_FILE</dt>
+<dd><p class="first">This sets the log file.</p>
+<p class="last">Example: LOG_FILE = ~/roverlay/log/roverlay.log</p>
+</dd>
+<dt>LOG_LEVEL</dt>
+<dd><p class="first">This sets the global log level, which is used for all log formats
+that don't override this option. Valid log levels are
+<tt class="docutils literal">DEBUG</tt>, <tt class="docutils literal">INFO</tt>, <tt class="docutils literal">WARN</tt>/<tt class="docutils literal">WARNING</tt>, <tt class="docutils literal">ERROR</tt> and <tt class="docutils literal">CRITICAL</tt>.</p>
+<p class="last">Example: LOG_LEVEL = WARNING</p>
+</dd>
+<dt>LOG_LEVEL_CONSOLE</dt>
+<dd><p class="first">This sets the console log level.</p>
+<p class="last">Example: LOG_LEVEL_CONSOLE = INFO</p>
+</dd>
+<dt>LOG_LEVEL_FILE</dt>
+<dd><p class="first">This sets the log level for file logging.</p>
+<p class="last">Example: LOG_LEVEL_FILE = ERROR</p>
+</dd>
+</dl>
+</blockquote>
+<p>The following options should also be set (most of them are required), but
+have reasonable defaults if <em>roverlay</em> has been installed using <em>emerge</em>:</p>
+<blockquote>
+<dl class="docutils">
+<dt>SIMPLE_RULES_FILE</dt>
+<dd><p class="first">This option lists the dependency rules files that should be used
+for dependency resolution (see
+<a class="reference internal" href="#dependency-rules-resolving-dependencies">Dependency Rules / Resolving Dependencies</a>).
+Although not required, this option is <strong>recommended</strong> since ebuild
+creation without dependency rules fails for most R packages.</p>
+<p class="last">Example: SIMPLE_RULES_FILE = ~/roverlay/config/simple-deprules.d</p>
+</dd>
+<dt>REPO_CONFIG</dt>
+<dd><p class="first">A list with one or more files that list repositories
+(see <a class="reference internal" href="#repositories-getting-packages">Repositories / Getting Packages</a>).
+This option is <strong>required</strong> and can be overridden on the command line
+via one or more <tt class="docutils literal"><span class="pre">repo-config</span> <file></tt> statements.</p>
+<p class="last">Example: REPO_CONFIG = ~/roverlay/config/repo.list</p>
+</dd>
+<dt>FIELD_DEFINITION</dt>
+<dd><p class="first">The value of this option should point to a field definition file which
+controls how an R package's DESCRIPTION file is read.
+The file supplied by default should be fine.
+This option is <strong>required</strong> and can be overridden on the command line
+via <tt class="docutils literal"><span class="pre">--field-definition</span> <file></tt>.</p>
+<p class="last">Example: FIELD_DEFINITION = ~/roverlay/config/description_fields.conf</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.
+Specifying an eclass file that implements the ebuild phase functions
+(e.g. <em>src_install()</em>) is highly <strong>recommended</strong>. A default file
+named <em>R-packages.eclass</em> should be part of your installation.</p>
+<p class="last">Example: OVERLAY_ECLASS = ~/roverlay/eclass/R-packages.eclass</p>
+</dd>
+</dl>
+</blockquote>
+<p>For details and a full configuration reference, see <a class="reference internal" href="#configuration-reference">Configuration Reference</a>.</p>
+</div>
+<div class="section" id="running-it">
+<h2><a class="toc-backref" href="#id9">Running it</a></h2>
+<p>If you've installed <em>roverlay</em>, you can run it with <tt class="docutils literal">roverlay</tt>, otherwise
+you'll have to cd into the <em>R overlay src directory</em> and run <tt class="docutils literal">./roverlay.py</tt>.</p>
+<p>In any case, the basic <em>roverlay</em> script usage is</p>
+<pre class="code literal-block">
+roverlay --config <config file> [<options>] [<commands>]
+</pre>
+<p>or</p>
+<pre class="code literal-block">
+roverlay [<options>] [<commands>]
+</pre>
+<p>which will search for the config file
+as described in <a class="reference internal" href="#required-configuration-steps">Required configuration steps</a>.
+The default command is <em>create</em>, which downloads the R packages (unless
+explicitly forbidden to do so) and generates the overlay. This is the
+desired behavior in most cases, so simply running <tt class="docutils literal">roverlay</tt> should be
+fine.</p>
+<p><em>roverlay</em> also accepts some <strong>options</strong>, most notably:</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--nosync</span>, <span class="option">--no-sync</span></kbd></td>
+</tr>
+<tr><td> </td><td>Don't download R packages.</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>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--immediate-ebuild-writes</span></kbd></td>
+</tr>
+<tr><td> </td><td><p class="first">Immediately write ebuilds when they're ready.</p>
+<p>The default behavior is
+to wait for all ebuilds and then write them using ebuild write threads.
+The latter one is faster, but consumes more memory since ebuilds must be
+kept until all packages have been processed.
+Test results show that memory consumption increases by factor 2 when using
+the faster write mechanism (at ca. 95% ebuild creation success rate),
+<while ebuild write time decreases by ???>.</p>
+<p class="last">Summary: Expect 300 (slow) or 600MB (fast) memory consumption when using
+the default package repositories.</p>
+</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--config <var>file</var></span>, <span class="option">-c <var>file</var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Path to the config file</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--help</span>, <span class="option">-h</span></kbd></td>
+<td>Show all options</td></tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last"><em>--no-incremental</em> doesn't delete an existing overlay, it will merely
+ignores and, potentially, overwrites existing ebuilds.
+Use <em>rm -rf <overlay></em> to do that.</p>
+</div>
+<p>For <strong>testing</strong> <em>roverlay</em>, these <strong>options</strong> may be convenient:</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--no-manifest</span></kbd></td>
+<td><p class="first">Skip Manifest file creation.</p>
+<p class="last">This saves a considerable amount of time
+(>100min when using the default package repositories) at the expense of
+an overlay that is not suitable for production usage.</p>
+</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--no-write</span></kbd></td>
+<td>Don't write the overlay</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--show</span></kbd></td>
+<td>Print all ebuilds and metadata to console</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--repo-config <var>file</var></span>, <span class="option">-R <var>file</var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Repo config file to use. Can be specified more than once.
+This disables all repo files configured in the main config file.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--distdir <var>directory</var></span>, <span class="option">--from <var>directory</var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Create an overlay using the packages found in <em>directory</em>. This disables
+all other repositories. The <em>SRC_URI</em> ebuild variable will be invalid!</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--overlay <var>directory</var></span>, <span class="option">-O <var>directory</var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Create the overlay at the given position.</td></tr>
+</tbody>
+</table>
+<p>For reference, these <strong>commands</strong> are accepted by <em>roverlay</em>:</p>
+<dl class="docutils">
+<dt>create</dt>
+<dd>As described above, this will run ebuild, metadata creation, including
+overlay and Manifest file writing.
+This command implies the <strong>sync</strong> command unless the <em>--nosync</em> option
+is specified.</dd>
+<dt>sync</dt>
+<dd>This will download all packages from the configured remotes.</dd>
+<dt>depres_console, depres</dt>
+<dd><p class="first">Starts an interactive dependency resolution console that supports rule
+creation/deletion, loading rules from files, writing rules to files
+and resolving dependencies.</p>
+<p class="last">Meant for <strong>testing only</strong>.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="providing-a-package-mirror">
+<h2><a class="toc-backref" href="#id10">Providing a package mirror</a></h2>
+<p><No recommendations at this time. The current ManifestCreation implementation
+creates a directory <em><distfiles root>/__tmp__</em> with symlinks to all packages,
+which could be used for providing packages, but this may change
+in near future since external Manifest creation is too slow
+(takes >60% of overlay creation time).></p>
+</div>
+</div>
+<div class="section" id="implementation-overview">
+<h1><a class="toc-backref" href="#id11">Implementation Overview</a></h1>
+<p>This section gives a basic overview of how <em>roverlay</em> works.</p>
+<p><how <em>roverlay</em> basically works:></p>
+<ol class="arabic simple">
+<li><strong>sync</strong> - get R packages using various methods
+(rsync, http, local directory)</li>
+<li>scan the R Overlay directory (if it exists) for valid ebuilds</li>
+<li>queue all R packages for ebuild creation<ul>
+<li>all repositories are asked to list their packages which are then added
+to a queue</li>
+<li>packages may be declined by the overlay creator if they already have
+an ebuild</li>
+</ul>
+</li>
+<li><strong>create</strong> - process each package <em>p</em> from the package queue
+(thread-able on a per package basis)</li>
+</ol>
+<blockquote>
+<ul class="simple">
+<li>read <em>p</em>'s DESCRIPTION file that contains information fields
+like 'Depends', 'Description' and 'Suggests'</li>
+<li>resolve <em>p</em>'s dependencies<ul>
+<li>differentiate between <em>required</em> and <em>optional</em> dependencies
+(for example, dependencies from the 'Depends' field are required,
+while those from 'Suggests' are optional)</li>
+<li><strong>immediately stop</strong> processing <em>p</em> if a <em>required</em> dependency
+cannot be resolved in which case a valid ebuild cannot be created</li>
+</ul>
+</li>
+<li>create an ebuild for <em>p</em> by using the dependency resolution results
+and a few information fields like 'Description'</li>
+<li><strong>done</strong> with <em>p</em> - the overlay creator takes control over <em>p</em>
+and may decide to write <em>p</em>'s ebuild now (or later)</li>
+</ul>
+</blockquote>
+<ol class="arabic simple" start="5">
+<li>write the overlay<ul>
+<li>write all ebuilds
+(thread-able on a per package basis)</li>
+<li>write the <em>metadata.xml</em> files
+(thread-able on a per package basis)<ul>
+<li>this uses the latest created ebuild available for a package</li>
+</ul>
+</li>
+<li>write the <em>Manifest</em> files
+(not thread-able)<ul>
+<li>this uses all ebuilds availabe for a package</li>
+</ul>
+</li>
+</ul>
+</li>
+</ol>
+<div class="section" id="repositories-getting-packages">
+<h2><a class="toc-backref" href="#id12">Repositories / Getting Packages</a></h2>
+<p><em>roverlay</em> is capable of downloading R packages via rsync and http,
+and is able to use any packages locally available. The concrete method used
+to get and use the packages is determined by the concrete
+<strong>type of a repository</strong> and that's what this section is about.</p>
+<div class="section" id="a-word-about-repo-config-files">
+<h3><a class="toc-backref" href="#id13">A word about repo config files</a></h3>
+<p>Repo config files use <a class="reference external" href="http://docs.python.org/library/configparser.html">ConfigParser</a> syntax (known from ini files).</p>
+<p>Each repo entry section is introduced with <tt class="docutils literal">[<repo name>]</tt> and defines</p>
+<ul class="simple">
+<li>how <em>roverlay</em> can download the R packages from a repo
+and where they should be stored</li>
+<li>how ebuilds can download the packages (-> <em>SRC_URI</em>)</li>
+<li>repo type specific options, e.g. whether the repo supports package file
+verification</li>
+</ul>
+<p>Such options are declared with <tt class="docutils literal"><option> = <value></tt> in the repo entry.</p>
+<p>The common options for repository entries are:</p>
+<ul>
+<li><p class="first"><em>type</em>, which declares the repository type. Available types are:</p>
+<blockquote>
+<ul class="simple">
+<li><a class="reference internal" href="#rsync">rsync</a></li>
+<li><a class="reference internal" href="#websync-repo">websync_repo</a></li>
+<li><a class="reference internal" href="#websync-pkglist">websync_pkglist</a></li>
+<li><a class="reference internal" href="#local">local</a></li>
+</ul>
+</blockquote>
+<p>Defaults to <em>rsync</em></p>
+</li>
+<li><p class="first"><em>src_uri</em>, which declares how ebuilds can download the packages. Some repo
+types use this for downloading, too.</p>
+</li>
+<li><p class="first"><em>directory</em>, which explicitly sets the package directory to use.
+The default behavior is to use <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>/<repo name></p>
+</li>
+</ul>
+<div class="hint">
+<p class="first admonition-title">Hint</p>
+<p class="last">Repo names are allowed contain slashes, which will be respected when
+creating the default directory.</p>
+</div>
+</div>
+<div class="section" id="rsync-repos">
+<span id="rsync"></span><h3><a class="toc-backref" href="#id14">Rsync repos</a></h3>
+<p>Runs <em>rsync</em> to download packages. Automatic sync retries are supported if
+<em>rsync</em>'s exit codes indicates chances of success.
+For example, up to 3 retries are granted if <em>rsync</em> returns
+<em>Partial transfer due to vanished source files</em> which likely happens when
+syncing big repositories like CRAN.</p>
+<p>This repo type extends the default options by:</p>
+<ul class="simple">
+<li><em>rsync_uri</em> (<strong>required</strong>), which specifies the uri used for syncing</li>
+<li><em>recursive</em> (optional), which passes <tt class="docutils literal"><span class="pre">--recursive</span></tt> to <em>rsync</em> if set to
+'yes'</li>
+<li><em>extra_rsync_opts</em> (optional), which passes arbitrary options to <em>rsync</em>.
+This can be used include/exclude files or to show progress during transfer.
+Options with whitespace are not supported.</li>
+</ul>
+<p>Examples:</p>
+<ul>
+<li><p class="first">CRAN</p>
+<blockquote>
+<pre class="code ini literal-block">
+<span class="k">[CRAN]</span>
+<span class="na">type</span> <span class="o">=</span> <span class="s">rsync</span>
+<span class="na">rsync_uri</span> <span class="o">=</span> <span class="s">cran.r-project.org::CRAN/src/contrib</span>
+<span class="na">src_uri</span> <span class="o">=</span> <span class="s">http://cran.r-project.org/src/contrib</span>
+<span class="na">extra_rsync_opts</span> <span class="o">=</span> <span class="s">--progress --exclude=PACKAGES --exclude=PACKAGES.gz</span>
+</pre>
+</blockquote>
+</li>
+<li><p class="first">CRAN's archive:</p>
+<blockquote>
+<pre class="code ini literal-block">
+<span class="k">[CRAN-Archive]</span>
+<span class="na">type</span> <span class="o">=</span> <span class="s">rsync</span>
+<span class="na">rsync_uri</span> <span class="o">=</span> <span class="s">cran.r-project.org::CRAN/src/contrib/Archive</span>
+<span class="na">src_uri</span> <span class="o">=</span> <span class="s">http://cran.r-project.org/src/contrib/Archive</span>
+<span class="na">extra_rsync_opts</span> <span class="o">=</span> <span class="s">--progress</span>
+<span class="na">recursive</span> <span class="o">=</span> <span class="s">yes</span>
+</pre>
+</blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="getting-packages-from-a-repository-that-supports-http-only">
+<span id="websync-repo"></span><h3><a class="toc-backref" href="#id15">Getting packages from a repository that supports http only</a></h3>
+<p>This is your best bet if the remote is a repository but doesn't offer
+rsync access. Basic digest verification is supported (MD5).
+The remote has to have a package list file, typically named
+<em>PACKAGES</em>, with a special syntax (debian control file syntax).</p>
+<p>A package list example,
+excerpt from <a class="reference external" href="http://www.omegahat.org/R/src/contrib/PACKAGES">omegahat's PACKAGES file</a> (as of Aug 2012):</p>
+<pre class="code control literal-block">
+<span class="err">...</span>
+<span class="k">Package</span><span class="w">: </span><span class="s">CGIwithR</span>
+<span class="k">Version</span>: <span class="m">0.73-0</span>
+<span class="k">Suggests</span><span class="w">: </span><span class="s">GDD</span>
+<span class="k">License</span><span class="w">: </span><span class="s">GPL (>= 2)</span>
+<span class="k">MD5sum</span><span class="w">: </span><span class="s">50b1f48209c9e66909c7afb3a4b8af5e</span>
+
+<span class="k">Package</span><span class="w">: </span><span class="s">CodeDepends</span>
+<span class="k">Version</span>: <span class="m">0.2-1</span>
+<span class="k">Depends</span>: <span class="nf">methods</span>
+<span class="k">Imports</span><span class="w">: </span><span class="s">codetools, XML</span>
+<span class="k">Suggests</span><span class="w">: </span><span class="s">graph, Rgraphviz</span>
+<span class="k">License</span><span class="w">: </span><span class="s">GPL</span>
+<span class="k">MD5sum</span><span class="w">: </span><span class="s">e2ec3505f9db1a96919a72f07673a2d8</span>
+<span class="err">...</span>
+</pre>
+<p>An example repo config entry for omegahat:</p>
+<pre class="code ini literal-block">
+<span class="k">[omegahat]</span>
+<span class="na">type</span> <span class="o">=</span> <span class="s">websync_repo</span>
+<span class="na">src_uri</span> <span class="o">=</span> <span class="s">http://www.omegahat.org/R/src/contrib</span>
+<span class="na">digest</span> <span class="o">=</span> <span class="s">md5</span>
+<span class="c">#digest = none</span>
+</pre>
+<p>This repo type extends the default options by:</p>
+<ul class="simple">
+<li><em>digest</em>, which declares that the remote supports digest based package file
+verification. Accepted values are 'md5' and 'none'. Defaults to 'none',
+which disables verification.</li>
+<li><em>pkglist_file</em>, which sets the name of the package list file and defaults
+to PACKAGES</li>
+<li><em>pkglist_uri</em>, which explicitly sets the uri of the package list file.
+Defaults to <em>src_uri</em>/<em>pkglist_file</em></li>
+</ul>
+<p>None of these options are required.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">The content type of the remote's package list file has to be exactly
+<em>text/plain</em>, compressed files are not supported.</p>
+</div>
+</div>
+<div class="section" id="getting-packages-from-several-remotes-using-http-and-a-package-list">
+<span id="websync-pkglist"></span><h3><a class="toc-backref" href="#id16">Getting packages from several remotes using http and a package list</a></h3>
+<p>This is not a real repository type, instead it creates a <em>local</em> repository
+by downloading single R packages from different remotes.
+Its only requirement is that a package is downloadable via http.
+Apart from an entry in the repo config file, it also needs a file that lists
+one package uri per line:</p>
+<pre class="code text literal-block">
+...
+http://cran.r-project.org/src/contrib/seewave_1.6.4.tar.gz
+http://download.r-forge.r-project.org/src/contrib/zoo_1.7-7.tar.gz
+http://www.omegahat.org/R/src/contrib/Aspell_0.2-0.tar.gz
+...
+</pre>
+<p>Comments are not supported. Assuming that such a package list exists as <at?>
+<em>~/roverlay/config/http_packages.list</em>, an example entry in the repo config
+file would be:</p>
+<pre class="code ini literal-block">
+<span class="k">[http-packages]</span>
+<span class="na">type</span> <span class="o">=</span> <span class="s">websync_pkglist</span>
+<span class="na">pkglist</span> <span class="o">=</span> <span class="s">~/roverlay/config/http_packages.list</span>
+</pre>
+<p>This repo type extends the default options by:</p>
+<ul class="simple">
+<li><em>pkglist</em>, which sets the package list file. This option is <strong>required</strong>.</li>
+</ul>
+</div>
+<div class="section" id="using-local-directories">
+<span id="local"></span><h3><a class="toc-backref" href="#id17">Using local directories</a></h3>
+<p>Using local package directories is possible, too.</p>
+<p>Example:</p>
+<pre class="code ini literal-block">
+<span class="k">[local-packages]</span>
+<span class="na">type</span> <span class="o">=</span> <span class="s">local</span>
+<span class="na">directory</span> <span class="o">=</span> <span class="s">/var/local/R-packages</span>
+<span class="na">src_uri</span> <span class="o">=</span> <span class="s">http://localhost/R-packages</span>
+</pre>
+<p>This will use all packages from <em>/var/local/R-packages</em> and assumes
+that they're available via <em>http://localhost/R-packages</em>.</p>
+<p>A local directory will never be modified.</p>
+<div class="important">
+<p class="first admonition-title">Important</p>
+<p class="last">Using this repo type is <strong>not recommended for production usage</strong> because
+the <em>SRC_URI</em> variable in created ebuilds will be invalid unless you've
+downloaded all packages from the same remote in which case
+you should consider using one of the <strong>websync</strong> repo types,
+<a class="reference internal" href="#websync-repo">websync_repo</a> and <a class="reference internal" href="#websync-pkglist">websync_pkglist</a>.</p>
+</div>
+</div>
+</div>
+<div class="section" id="dependency-rules-resolving-dependencies">
+<h2><a class="toc-backref" href="#id18">Dependency Rules / Resolving Dependencies</a></h2>
+<div class="section" id="dependency-types">
+<h3><a class="toc-backref" href="#id19">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">
+<dt>Mandatory</dt>
+<dd>Ebuild creation fails if the <em>dependency string</em> in question cannot
+be resolved.</dd>
+<dt>Optional</dt>
+<dd>The opposite of <em>Mandatory</em>, ebuild creation keeps going even if the
+<em>dependency string</em> is unresolvable.</dd>
+<dt>Package Dependency</dt>
+<dd>This declares that the <em>dependency string</em> could be another R package.</dd>
+<dt>System Dependency</dt>
+<dd>This declares that the <em>dependency string</em> could be a system dependency,
+e.g. a scientific library or a video encoder.</dd>
+<dt>Try other dependency types</dt>
+<dd>This declares that the <em>dependency string</em> can be resolved by ignoring its
+dependency type partially. This property allows to resolve
+package dependencies as system dependencies and vice versa.</dd>
+</dl>
+<p><em>Mandatory</em> and <em>Option</em> are mutually exclusive.</p>
+<p>The <em>dependency type</em> of a <em>dependency string</em> is determined by the its origin,
+i.e. info field in the package's DESCRIPTION file.
+The <em>Suggests</em> field, for example,
+gets the <em>"package dependency and optional"</em> type,
+whereas the <em>SystemRequirements</em> gets <em>"system dependency and mandatory"</em>.</p>
+</div>
+<div class="section" id="simple-dependency-rules">
+<h3><a class="toc-backref" href="#id20">Simple Dependency Rules</a></h3>
+<p><em>Simple dependency rules</em> use a dictionary and string transformations
+to resolve dependencies. <em>Fuzzy simple dependency rules</em> extend these by
+a set of regexes, which allows to resolve many dependency strings that
+minimally differ (e.g. only in the required version and/or comments:
+<cite>R (>= 2.10)</cite> and <cite>R [2.14] from http://www.r-project.org/</cite>) with a single
+dictionary entry.</p>
+<p>This is the only rule implementation currently available.</p>
+<div class="section" id="rule-variants">
+<h4><a class="toc-backref" href="#id21">Rule Variants</a></h4>
+<dl class="docutils">
+<dt>default</dt>
+<dd>The expected behavior of a dictionary-based rule: It matches one or more
+<em>dependency strings</em> and resolves them as a <em>dependency</em></dd>
+<dt>ignore</dt>
+<dd>This variant will ignore <em>dependency strings</em>. Technically, it will
+resolve them as <strong>nothing</strong>.</dd>
+</dl>
+</div>
+<div class="section" id="rule-types">
+<h4><a class="toc-backref" href="#id22">Rule types</a></h4>
+<dl class="docutils">
+<dt>Simple Rules</dt>
+<dd><p class="first">A simple rule resolves <strong>exact string matches</strong> (case-insensitive).</p>
+<p>Example:
+Given a rule <em>R</em> that says "resolve 'R' and 'the R programming language'
+as 'dev-lang/R'", any of these <em>dependency strings</em> will be resolved
+as dev-lang/R:</p>
+<ul class="last simple">
+<li>r</li>
+<li>THE R PROGRAMMING LanGuAgE</li>
+<li>R</li>
+</ul>
+</dd>
+<dt>Fuzzy Rules</dt>
+<dd><p class="first">Fuzzy Rules are <strong>extended Simple Rules</strong>. If the basic lookup
+as described above fails for a <em>dependency string</em>,
+they will <em>try</em> to resolve it as a <strong>version-relative match</strong>.</p>
+<p>To do this, the <em>dependency string</em> will be split into components like
+<em>dependency name</em>, <em>dependency version</em> and useless comments, which are
+discarded.
+Then, if the <em>dependency name</em> matches a dictionary entry, a resolving
+<em>dependency</em> will be created.</p>
+<dl class="last docutils">
+<dt>Example:</dt>
+<dd><p class="first">Given the same rule as in the Simple Rules example, but as fuzzy rule
+"fuzzy-resolve 'R' and 'the R programming language' as 'dev-lang/R'",
+it will resolve any of these <em>dependency strings</em>:</p>
+<ul class="last simple">
+<li>"r" as "dev-lang/R"</li>
+<li>"R 2.12" as ">=dev-lang/R-2.12"</li>
+<li>"The R PROGRAMMING LANGUAGE [<2.14] from <a class="reference external" href="http://www.r-project.org/">http://www.r-project.org/</a>"
+as "<dev-lang/R-2.14"</li>
+<li>"R ( !2.10 )" as "( dev-lang/R !=dev-lang/R-2.10 )"</li>
+</ul>
+</dd>
+</dl>
+</dd>
+</dl>
+</div>
+<div class="section" id="rule-file-examples">
+<h4><a class="toc-backref" href="#id23">Rule File Examples</a></h4>
+<p>This sections lists some rule file examples.
+See <a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a> for a formal<precise,..?> description.</p>
+<dl class="docutils">
+<dt>Example 1 - <em>default</em> fuzzy rule</dt>
+<dd><p class="first">A rule that matches many dependencies on dev-lang/R, for example
+"r 2.12", "R(>= 2.14)", "R [<2.10]", "r{ !2.12 }", and "R", and
+resolves them as '>=dev-lang/R-2.12', '>=dev-lang/R-2.14',
+'<dev-lang/R-2.10', etc.:</p>
+<pre class="code text last literal-block">
+~dev-lang/R :: R
+</pre>
+</dd>
+<dt>Example 2 - <em>default</em> simple rule stub</dt>
+<dd><p class="first">A rule that case-insensitively matches 'zoo' and resolves it as 'sci-R/zoo',
+assuming the OVERLAY_CATEGORY is set to 'sci-R':</p>
+<pre class="code text last literal-block">
+zoo
+</pre>
+</dd>
+<dt>Example 3 - <em>default</em> simple rule</dt>
+<dd><p class="first">A rule that matches several <em>dependency strings</em> and resolves them
+as "sci-libs/gdal and sci-libs/proj":</p>
+<pre class="code text last literal-block">
+( sci-libs/gdal sci-libs/proj ) {
+ for building from source: GDAL >= 1.3.1 && GDAL < 1.6.0 (until tested) library and PROJ.4 (proj >= 4.4.9)
+ for building from source: GDAL >= 1.3.1 library and PROJ.4 (proj >= 4.4.9)
+ for building from source: GDAL >= 1.3.1 library and PROJ.4(proj >= 4.4.9)
+ for building from source: GDAL >= 1.6.0 library and PROJ.4(proj >= 4.4.9)
+}
+</pre>
+</dd>
+<dt>Example 4 - <em>ignore</em> simple rule</dt>
+<dd><p class="first">A rule that matches text that should be ignored.
+This is a good way to deal with free-style text found
+in some R package DESCRIPTION files.</p>
+<pre class="code text last literal-block">
+! {
+ see README
+ read INSTALL
+ Will use djmrgl or rgl packages for rendering if present
+}
+</pre>
+</dd>
+</dl>
+<p>Please see the default rule files for more extensive examples that cover
+other aspects like limiting a rule to certain dependency types.
+They're found in <em>/etc/roverlay/simple-deprules.d</em>
+if you've installed <em>roverlay</em> with <em>emerge</em>,
+else in <em><R Overlay src directory>/simple-deprules.d</em>.</p>
+</div>
+<div class="section" id="rule-file-syntax">
+<h4><a class="toc-backref" href="#id24">Rule File Syntax</a></h4>
+<p>Simple dependency rule files have a special syntax. Each rule is introduced
+with the resolving <em>dependency</em> prefixed by a <em>keychar</em> that sets the rule
+type if required. The <em>dependency strings</em> resolved by this rule are listed
+after a rule separator or within a rule block. Leading/trailing whitespace
+is ignored.</p>
+<dl class="docutils">
+<dt>Ignore rules</dt>
+<dd>have only a keychar but no <em>dependency</em>.</dd>
+<dt>Keychars</dt>
+<dd><p class="first">set the rule type.</p>
+<ul class="simple">
+<li><strong>!</strong> introduces a <em>ignore</em> simple rule</li>
+<li><strong>~</strong> introduces a <em>default</em> fuzzy rule</li>
+<li><strong>%</strong> introduces a <em>ignore</em> fuzzy rule</li>
+</ul>
+<p class="last">Anything else is not treated as keychar and thus introduces a <em>default</em>
+simple rule.</p>
+</dd>
+<dt>Keywords</dt>
+<dd><p class="first">There are two keywords that control how a rule file is read.</p>
+<p>The important one is the <em>#deptype <dependency type></em> directive that
+defines that all rules until the next <em>deptype</em> directory or end of file,
+whatever comes first, will only match <em>dependency strings</em>
+with the specified <em>dependency type</em>.</p>
+<p>Available dependency types choices are</p>
+<ul class="simple">
+<li><em>all</em> (no type restrictions)</li>
+<li><em>pkg</em> (resolve only R package dependencies)</li>
+<li><em>sys</em> (resolve only system dependencies)</li>
+</ul>
+<p class="last">The other keyword is <em>#! NOPARSE</em> which stops parsing of a rule file.</p>
+</dd>
+<dt>Dependencies</dt>
+<dd><p class="first">are strings that are recognized by portage as <strong>Dynamic DEPENDs</strong>
+(see the ebuild(5) man page).</p>
+<p>Examples:</p>
+<blockquote>
+<ul class="simple">
+<li>dev-lang/R</li>
+<li>( media-libs/tiff >=sci-libs/fftw-3 )</li>
+<li>>=x11-drivers/nvidia-drivers-270</li>
+</ul>
+</blockquote>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">The fuzzy rule types support <strong>DEPEND Atom Bases</strong> only.</p>
+</div>
+<div class="warning last">
+<p class="first admonition-title">Warning</p>
+<p class="last">Dependency strings cannot start with <em>~</em> as it is a keychar.
+Use braces <em>( ~... )</em> to work around that.</p>
+</div>
+</dd>
+<dt>Single line rules</dt>
+<dd><p class="first">resolve exactly one <em>dependency string</em>. Their rule separator is ' :: '.</p>
+<dl class="last docutils">
+<dt>Syntax:</dt>
+<dd><pre class="code text first last literal-block">
+[<keychar>]<dependency> :: <dependency string>
+</pre>
+</dd>
+</dl>
+</dd>
+<dt>Multi line rules</dt>
+<dd><p class="first">resolve several <em>dependency strings</em>.
+Their rule block begins with '{' + newline, followed by one
+<em>dependency string</em> per line, and ends with '}'.</p>
+<dl class="last docutils">
+<dt>Syntax:</dt>
+<dd><pre class="code text first last literal-block">
+[<keychar>]<dependency> {
+ <dependency string>
+ [<dependency string>]
+ ...
+}
+</pre>
+</dd>
+</dl>
+</dd>
+<dt>Rule Stubs</dt>
+<dd><p class="first">There's a shorter syntax for dependencies that are resolved within the
+created overlay. For example, if your OVERLAY_CATEGORY is
+<em>sci-R</em>, <em>zoo</em> should be resolved as <em>sci-R/zoo</em>.
+This rule can be written as a single word, <em>zoo</em>. Such stubs are called
+<strong>selfdeps</strong>.</p>
+<dl class="last docutils">
+<dt>Syntax:</dt>
+<dd><pre class="code text first last literal-block">
+[<keychar>]<short dependency>
+</pre>
+</dd>
+</dl>
+</dd>
+<dt>Comments</dt>
+<dd>start with <strong>#</strong>. There are a few exceptions to that, the <em>#deptype</em> and
+<em>#! NOPARSE</em> keywords. Comments inside rule blocks are not allowed and
+will be read as normal <em>dependency strings</em>.</dd>
+</dl>
+</div>
+</div>
+</div>
+<div class="section" id="expected-overlay-result-structure-of-the-generated-overlay">
+<h2><a class="toc-backref" href="#id25">Expected Overlay Result / Structure of the generated overlay</a></h2>
+<p>Assuming that you're using the default configuration (where possible) and
+the <em>R-packages</em> eclass file, the result should look like:</p>
+<pre class="code text literal-block">
+<overlay root>/
+<overlay root>/eclass
+<overlay root>/eclass/R-packages.eclass
+<overlay root>/profiles
+<overlay root>/profiles/categories
+<overlay root>/profiles/repo_name
+<overlay root>/profiles/use.desc
+<overlay root>/sci-R/<many directories per R package>
+<overlay root>/sci-R/seewave/
+<overlay root>/sci-R/seewave/Manifest
+<overlay root>/sci-R/seewave/metadata.xml
+<overlay root>/sci-R/seewave/seewave-1.5.9.ebuild
+<overlay root>/sci-R/seewave/seewave-1.6.4.ebuild
+</pre>
+</div>
+</div>
+<div class="section" id="configuration-reference">
+<h1><a class="toc-backref" href="#id26">Configuration Reference</a></h1>
+<div class="section" id="dependency-rules">
+<h2><a class="toc-backref" href="#id27">Dependency Rules</a></h2>
+<p><merge with basic..overview::deprules></p>
+</div>
+<div class="section" id="repositories">
+<h2><a class="toc-backref" href="#id28">Repositories</a></h2>
+<p><merge with basic..overview::repo></p>
+</div>
+<div class="section" id="main-config">
+<h2><a class="toc-backref" href="#id29">Main Config</a></h2>
+<dl class="docutils" id="distfiles-root">
+<dt>DISTFILES_ROOT</dt>
+<dd><></dd>
+</dl>
+<p>The main config file uses shell syntax.</p>
+</div>
+<div class="section" id="field-definition">
+<h2><a class="toc-backref" href="#id30">Field Definition</a></h2>
+<p>The field definition file uses <a class="reference external" href="http://docs.python.org/library/configparser.html">ConfigParser</a> syntax. For an example, see
+<a class="reference internal" href="#default-field-definition-file">default field definition file</a>.</p>
+<p>Each information field has its own section which declares a set of options
+and flags. Flags are case-insensivitve options
+without a value - they're enabled by listing them.</p>
+<p id="field-options"><span id="field-option"></span>Known field options:</p>
+<blockquote>
+<dl class="docutils" id="field-option-default-value">
+<dt>default_value</dt>
+<dd>Sets the default value for a field, which implies that any read
+DESCRIPTION file will contain this field, either with the value read
+from the file or (as fallback) the default value.
+Disables the <a class="reference internal" href="#mandatory-field-flag">'mandatory' field flag</a>.</dd>
+</dl>
+<dl class="docutils" id="field-option-allowed-value">
+<dt>allowed_value</dt>
+<dd>Declares that a field has a value whitelist and adds the value to that
+list (preserves whitespace).</dd>
+</dl>
+<dl class="docutils" id="field-option-allowed-values">
+<dt>allowed_values</dt>
+<dd>Declares that a field has a value whitelist and adds the values to
+that list (values are separated by whitespace).</dd>
+</dl>
+<dl class="docutils" id="field-option-alias">
+<span id="field-option-alias-withcase"></span><dt>alias_withcase, alias</dt>
+<dd>Declares case-sensitive field name aliases. This can be used to fix
+'typos', e.g. <em>Suggest</em> and <em>Suggests</em> both mean <em>Suggests</em>.</dd>
+</dl>
+<dl class="docutils" id="field-option-alias-nocase">
+<dt>alias_nocase</dt>
+<dd>Same as <a class="reference internal" href="#field-option-alias">field option: alias</a>, but aliases are case-insensitive.</dd>
+</dl>
+<dl class="docutils" id="field-option-flags">
+<dt>flags</dt>
+<dd>List of <a class="reference internal" href="#field-flags">field flags</a>. Note that any option without a value is treated
+as flag.</dd>
+</dl>
+</blockquote>
+<p id="field-flag"><span id="field-flags"></span>Known field flags:</p>
+<blockquote>
+<dl class="docutils" id="field-flag-joinvalues">
+<dt>joinValues</dt>
+<dd>Declares that a field's value is one string even if it spans over
+multiple lines.
+The lines will be joined with a single space character ' '.
+The default behavior is to merge lines.</dd>
+</dl>
+<dl class="docutils" id="field-flag-islist">
+<dt>isList</dt>
+<dd>Declares that a field's value is a list whose values are separated by
+by ',' or ';'.</dd>
+</dl>
+<dl class="docutils" id="field-flag-iswhitespacelist">
+<dt>isWhitespaceList</dt>
+<dd>Declares that a field's value is a list whose values are separated by
+whitespace. Has no effect if <cite>field flag: isList</cite> is set.</dd>
+</dl>
+<dl class="docutils" id="mandatory-field-flag">
+<span id="field-flag-mandatory"></span><dt>mandatory</dt>
+<dd>Declares that a field is required in <em>all</em> DESCRIPTION files.
+This means that R packages without that field are considered as unusable,
+i.e. ebuild creation fails early.
+This flag is (effectively) useless in conjunction with
+<a class="reference internal" href="#field-option-default-value">field option: default_value</a> unless the default value evaluates to
+False (e.g. is an empty string).</dd>
+</dl>
+<dl class="docutils" id="field-flag-ignore">
+<dt>ignore</dt>
+<dd>Declares that a field is known but entirely ignored. Unknown fields
+are ignored, too, the main difference is the log message.</dd>
+</dl>
+</blockquote>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">It won't be checked whether a flag is known or not.</p>
+</div>
+</div>
+</div>
+<div class="section" id="appendix">
+<h1><a class="toc-backref" href="#id31">Appendix</a></h1>
+<div class="section" id="default-field-definition-file">
+<h2><a class="toc-backref" href="#id32">Default Field Definition File</a></h2>
+<p>This is the default field definition file (without any ignored fields):</p>
+<pre class="code ini literal-block">
+<span class="k">[Description]</span>
+<span class="err">joinValues</span>
+
+<span class="k">[Title]</span>
+<span class="err">joinValues</span>
+
+<span class="k">[Suggests]</span>
+<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">Suggests, Suggest, %Suggests, Suggets, Recommends</span>
+<span class="err">isList</span>
+
+<span class="k">[Depends]</span>
+<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">Depends, Dependencies, Dependes, %Depends, Depents, Require, Requires</span>
+<span class="err">isList</span>
+
+<span class="k">[Imports]</span>
+<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">Imports, Import</span>
+<span class="err">isList</span>
+
+<span class="k">[LinkingTo]</span>
+<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">LinkingTo, LinkingdTo, LinkinTo</span>
+<span class="err">isList</span>
+
+<span class="k">[SystemRequirements]</span>
+<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">SystemRequirements, SystemRequirement</span>
+<span class="err">isList</span>
+
+<span class="k">[OS_Type]</span>
+<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">OS_TYPE</span>
+<span class="na">allowed_values</span> <span class="o">=</span> <span class="s">unix</span>
+</pre>
+</div>
+</div>
+</div>
+</body>
+</html>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2012-08-10 17:56 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2012-08-10 17:56 UTC (permalink / raw
To: gentoo-commits
commit: 6d38ed2962e1fa1cd42217c55edb6b5d138c0384
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Aug 10 17:56:23 2012 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Aug 10 17:56:23 2012 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=6d38ed29
usage guide, html: numbered sections
---
doc/html/usage.html | 130 +++++++++++++++++++++++++-------------------------
1 files changed, 65 insertions(+), 65 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 8027b22..37e3c27 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -319,68 +319,68 @@ ul.auto-toc {
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
-<ul class="simple">
-<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
-<li><a class="reference internal" href="#installation" id="id2">Installation</a><ul>
-<li><a class="reference internal" href="#prerequisites" id="id3">Prerequisites</a></li>
-<li><a class="reference internal" href="#via-emerge-gentoo" id="id4">via emerge (Gentoo)</a></li>
-<li><a class="reference internal" href="#manual-installation" id="id5">Manual Installation</a></li>
-<li><a class="reference internal" href="#using-roverlay-without-installation" id="id6">Using <em>roverlay</em> without installation</a></li>
+<ul class="auto-toc simple">
+<li><a class="reference internal" href="#introduction" id="id1">1 Introduction</a></li>
+<li><a class="reference internal" href="#installation" id="id2">2 Installation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#prerequisites" id="id3">2.1 Prerequisites</a></li>
+<li><a class="reference internal" href="#via-emerge-gentoo" id="id4">2.2 via emerge (Gentoo)</a></li>
+<li><a class="reference internal" href="#manual-installation" id="id5">2.3 Manual Installation</a></li>
+<li><a class="reference internal" href="#using-roverlay-without-installation" id="id6">2.4 Using <em>roverlay</em> without installation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-roverlay" id="id7">Running Roverlay</a><ul>
-<li><a class="reference internal" href="#required-configuration-steps" id="id8">Required configuration steps</a></li>
-<li><a class="reference internal" href="#running-it" id="id9">Running it</a></li>
-<li><a class="reference internal" href="#providing-a-package-mirror" id="id10">Providing a package mirror</a></li>
+<li><a class="reference internal" href="#running-roverlay" id="id7">3 Running Roverlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#required-configuration-steps" id="id8">3.1 Required configuration steps</a></li>
+<li><a class="reference internal" href="#running-it" id="id9">3.2 Running it</a></li>
+<li><a class="reference internal" href="#providing-a-package-mirror" id="id10">3.3 Providing a package mirror</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#implementation-overview" id="id11">Implementation Overview</a><ul>
-<li><a class="reference internal" href="#repositories-getting-packages" id="id12">Repositories / Getting Packages</a><ul>
-<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id13">A word about repo config files</a></li>
-<li><a class="reference internal" href="#rsync-repos" id="id14">Rsync repos</a></li>
-<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id15">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="id16">Getting packages from several remotes using http and a package list</a></li>
-<li><a class="reference internal" href="#using-local-directories" id="id17">Using local directories</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id11">4 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#repositories-getting-packages" id="id12">4.1 Repositories / Getting Packages</a><ul class="auto-toc">
+<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id13">4.1.1 A word about repo config files</a></li>
+<li><a class="reference internal" href="#rsync-repos" id="id14">4.1.2 Rsync repos</a></li>
+<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id15">4.1.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="id16">4.1.4 Getting packages from several remotes using http and a package list</a></li>
+<li><a class="reference internal" href="#using-local-directories" id="id17">4.1.5 Using local directories</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-rules-resolving-dependencies" id="id18">Dependency Rules / Resolving Dependencies</a><ul>
-<li><a class="reference internal" href="#dependency-types" id="id19">Dependency types</a></li>
-<li><a class="reference internal" href="#simple-dependency-rules" id="id20">Simple Dependency Rules</a><ul>
-<li><a class="reference internal" href="#rule-variants" id="id21">Rule Variants</a></li>
-<li><a class="reference internal" href="#rule-types" id="id22">Rule types</a></li>
-<li><a class="reference internal" href="#rule-file-examples" id="id23">Rule File Examples</a></li>
-<li><a class="reference internal" href="#rule-file-syntax" id="id24">Rule File Syntax</a></li>
+<li><a class="reference internal" href="#dependency-rules-resolving-dependencies" id="id18">4.2 Dependency Rules / Resolving Dependencies</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id19">4.2.1 Dependency types</a></li>
+<li><a class="reference internal" href="#simple-dependency-rules" id="id20">4.2.2 Simple Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#rule-variants" id="id21">4.2.2.1 Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id22">4.2.2.2 Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id23">4.2.2.3 Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id24">4.2.2.4 Rule File Syntax</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id25">Expected Overlay Result / Structure of the generated overlay</a></li>
+<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id25">4.3 Expected Overlay Result / Structure of the generated overlay</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#configuration-reference" id="id26">Configuration Reference</a><ul>
-<li><a class="reference internal" href="#dependency-rules" id="id27">Dependency Rules</a></li>
-<li><a class="reference internal" href="#repositories" id="id28">Repositories</a></li>
-<li><a class="reference internal" href="#main-config" id="id29">Main Config</a></li>
-<li><a class="reference internal" href="#field-definition" id="id30">Field Definition</a></li>
+<li><a class="reference internal" href="#configuration-reference" id="id26">5 Configuration Reference</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-rules" id="id27">5.1 Dependency Rules</a></li>
+<li><a class="reference internal" href="#repositories" id="id28">5.2 Repositories</a></li>
+<li><a class="reference internal" href="#main-config" id="id29">5.3 Main Config</a></li>
+<li><a class="reference internal" href="#field-definition" id="id30">5.4 Field Definition</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#appendix" id="id31">Appendix</a><ul>
-<li><a class="reference internal" href="#default-field-definition-file" id="id32">Default Field Definition File</a></li>
+<li><a class="reference internal" href="#appendix" id="id31">6 Appendix</a><ul class="auto-toc">
+<li><a class="reference internal" href="#default-field-definition-file" id="id32">6.1 Default Field Definition File</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
-<h1><a class="toc-backref" href="#id1">Introduction</a></h1>
+<h1><a class="toc-backref" href="#id1">1 Introduction</a></h1>
<p><em>roverlay</em> is
Automatically Generated Overlay of R packages;;
GSoC Project;;
<>;;</p>
</div>
<div class="section" id="installation">
-<h1><a class="toc-backref" href="#id2">Installation</a></h1>
+<h1><a class="toc-backref" href="#id2">2 Installation</a></h1>
<div class="section" id="prerequisites">
-<h2><a class="toc-backref" href="#id3">Prerequisites</a></h2>
+<h2><a class="toc-backref" href="#id3">2.1 Prerequisites</a></h2>
<ul>
<li><p class="first">python >= 2.7 (tested with python 2.7 and 3.2)</p>
</li>
@@ -425,13 +425,13 @@ writing to a tmpfs, most time is spent for Manifest creation></p>
</ul>
</div>
<div class="section" id="via-emerge-gentoo">
-<h2><a class="toc-backref" href="#id4">via emerge (Gentoo)</a></h2>
+<h2><a class="toc-backref" href="#id4">2.2 via emerge (Gentoo)</a></h2>
<p>A live ebuild is available, <a class="reference external" href="http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=blob;f=roverlay-9999.ebuild;hb=refs/heads/master">roverlay-9999.ebuild</a>.
Add it to your local overlay and run <tt class="docutils literal">emerge roverlay</tt>, which will also
install all config files into <em>/etc/roverlay</em>.</p>
</div>
<div class="section" id="manual-installation">
-<h2><a class="toc-backref" href="#id5">Manual Installation</a></h2>
+<h2><a class="toc-backref" href="#id5">2.3 Manual Installation</a></h2>
<p>After installing the dependencies as listed in <a class="reference internal" href="#prerequisites">Prerequisites</a>,
clone the <a class="reference external" href="http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=summary">roverlay git repo</a> and then
install <em>roverlay</em> and its python modules:</p>
@@ -465,7 +465,7 @@ any config files!</p>
</div>
</div>
<div class="section" id="using-roverlay-without-installation">
-<h2><a class="toc-backref" href="#id6">Using <em>roverlay</em> without installation</a></h2>
+<h2><a class="toc-backref" href="#id6">2.4 Using <em>roverlay</em> without installation</a></h2>
<p>This is possible, too. Make sure to meet the dependencies as listed
in <a class="reference internal" href="#prerequisites">Prerequisites</a>.
Then, simply clone the git repository to a local directory that
@@ -485,9 +485,9 @@ will later be referenced as the <em>R Overlay src directory</em>.</p>
</div>
</div>
<div class="section" id="running-roverlay">
-<h1><a class="toc-backref" href="#id7">Running Roverlay</a></h1>
+<h1><a class="toc-backref" href="#id7">3 Running Roverlay</a></h1>
<div class="section" id="required-configuration-steps">
-<h2><a class="toc-backref" href="#id8">Required configuration steps</a></h2>
+<h2><a class="toc-backref" href="#id8">3.1 Required configuration steps</a></h2>
<p><em>roverlay</em> needs a configuration file to run.</p>
<p>If you've installed <em>roverlay</em> with <em>emerge</em>, it will look for the config
file in that order:</p>
@@ -584,7 +584,7 @@ named <em>R-packages.eclass</em> should be part of your installation.</p>
<p>For details and a full configuration reference, see <a class="reference internal" href="#configuration-reference">Configuration Reference</a>.</p>
</div>
<div class="section" id="running-it">
-<h2><a class="toc-backref" href="#id9">Running it</a></h2>
+<h2><a class="toc-backref" href="#id9">3.2 Running it</a></h2>
<p>If you've installed <em>roverlay</em>, you can run it with <tt class="docutils literal">roverlay</tt>, otherwise
you'll have to cd into the <em>R overlay src directory</em> and run <tt class="docutils literal">./roverlay.py</tt>.</p>
<p>In any case, the basic <em>roverlay</em> script usage is</p>
@@ -695,7 +695,7 @@ and resolving dependencies.</p>
</dl>
</div>
<div class="section" id="providing-a-package-mirror">
-<h2><a class="toc-backref" href="#id10">Providing a package mirror</a></h2>
+<h2><a class="toc-backref" href="#id10">3.3 Providing a package mirror</a></h2>
<p><No recommendations at this time. The current ManifestCreation implementation
creates a directory <em><distfiles root>/__tmp__</em> with symlinks to all packages,
which could be used for providing packages, but this may change
@@ -704,7 +704,7 @@ in near future since external Manifest creation is too slow
</div>
</div>
<div class="section" id="implementation-overview">
-<h1><a class="toc-backref" href="#id11">Implementation Overview</a></h1>
+<h1><a class="toc-backref" href="#id11">4 Implementation Overview</a></h1>
<p>This section gives a basic overview of how <em>roverlay</em> works.</p>
<p><how <em>roverlay</em> basically works:></p>
<ol class="arabic simple">
@@ -757,13 +757,13 @@ and may decide to write <em>p</em>'s ebuild now (or later)</li>
</li>
</ol>
<div class="section" id="repositories-getting-packages">
-<h2><a class="toc-backref" href="#id12">Repositories / Getting Packages</a></h2>
+<h2><a class="toc-backref" href="#id12">4.1 Repositories / Getting Packages</a></h2>
<p><em>roverlay</em> is capable of downloading R packages via rsync and http,
and is able to use any packages locally available. The concrete method used
to get and use the packages is determined by the concrete
<strong>type of a repository</strong> and that's what this section is about.</p>
<div class="section" id="a-word-about-repo-config-files">
-<h3><a class="toc-backref" href="#id13">A word about repo config files</a></h3>
+<h3><a class="toc-backref" href="#id13">4.1.1 A word about repo config files</a></h3>
<p>Repo config files use <a class="reference external" href="http://docs.python.org/library/configparser.html">ConfigParser</a> syntax (known from ini files).</p>
<p>Each repo entry section is introduced with <tt class="docutils literal">[<repo name>]</tt> and defines</p>
<ul class="simple">
@@ -801,7 +801,7 @@ creating the default directory.</p>
</div>
</div>
<div class="section" id="rsync-repos">
-<span id="rsync"></span><h3><a class="toc-backref" href="#id14">Rsync repos</a></h3>
+<span id="rsync"></span><h3><a class="toc-backref" href="#id14">4.1.2 Rsync repos</a></h3>
<p>Runs <em>rsync</em> to download packages. Automatic sync retries are supported if
<em>rsync</em>'s exit codes indicates chances of success.
For example, up to 3 retries are granted if <em>rsync</em> returns
@@ -844,7 +844,7 @@ Options with whitespace are not supported.</li>
</ul>
</div>
<div class="section" id="getting-packages-from-a-repository-that-supports-http-only">
-<span id="websync-repo"></span><h3><a class="toc-backref" href="#id15">Getting packages from a repository that supports http only</a></h3>
+<span id="websync-repo"></span><h3><a class="toc-backref" href="#id15">4.1.3 Getting packages from a repository that supports http only</a></h3>
<p>This is your best bet if the remote is a repository but doesn't offer
rsync access. Basic digest verification is supported (MD5).
The remote has to have a package list file, typically named
@@ -894,7 +894,7 @@ Defaults to <em>src_uri</em>/<em>pkglist_file</em></li>
</div>
</div>
<div class="section" id="getting-packages-from-several-remotes-using-http-and-a-package-list">
-<span id="websync-pkglist"></span><h3><a class="toc-backref" href="#id16">Getting packages from several remotes using http and a package list</a></h3>
+<span id="websync-pkglist"></span><h3><a class="toc-backref" href="#id16">4.1.4 Getting packages from several remotes using http and a package list</a></h3>
<p>This is not a real repository type, instead it creates a <em>local</em> repository
by downloading single R packages from different remotes.
Its only requirement is that a package is downloadable via http.
@@ -921,7 +921,7 @@ file would be:</p>
</ul>
</div>
<div class="section" id="using-local-directories">
-<span id="local"></span><h3><a class="toc-backref" href="#id17">Using local directories</a></h3>
+<span id="local"></span><h3><a class="toc-backref" href="#id17">4.1.5 Using local directories</a></h3>
<p>Using local package directories is possible, too.</p>
<p>Example:</p>
<pre class="code ini literal-block">
@@ -944,9 +944,9 @@ you should consider using one of the <strong>websync</strong> repo types,
</div>
</div>
<div class="section" id="dependency-rules-resolving-dependencies">
-<h2><a class="toc-backref" href="#id18">Dependency Rules / Resolving Dependencies</a></h2>
+<h2><a class="toc-backref" href="#id18">4.2 Dependency Rules / Resolving Dependencies</a></h2>
<div class="section" id="dependency-types">
-<h3><a class="toc-backref" href="#id19">Dependency types</a></h3>
+<h3><a class="toc-backref" href="#id19">4.2.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">
@@ -974,7 +974,7 @@ gets the <em>"package dependency and optional"</em> type,
whereas the <em>SystemRequirements</em> gets <em>"system dependency and mandatory"</em>.</p>
</div>
<div class="section" id="simple-dependency-rules">
-<h3><a class="toc-backref" href="#id20">Simple Dependency Rules</a></h3>
+<h3><a class="toc-backref" href="#id20">4.2.2 Simple Dependency Rules</a></h3>
<p><em>Simple dependency rules</em> use a dictionary and string transformations
to resolve dependencies. <em>Fuzzy simple dependency rules</em> extend these by
a set of regexes, which allows to resolve many dependency strings that
@@ -983,7 +983,7 @@ minimally differ (e.g. only in the required version and/or comments:
dictionary entry.</p>
<p>This is the only rule implementation currently available.</p>
<div class="section" id="rule-variants">
-<h4><a class="toc-backref" href="#id21">Rule Variants</a></h4>
+<h4><a class="toc-backref" href="#id21">4.2.2.1 Rule Variants</a></h4>
<dl class="docutils">
<dt>default</dt>
<dd>The expected behavior of a dictionary-based rule: It matches one or more
@@ -994,7 +994,7 @@ resolve them as <strong>nothing</strong>.</dd>
</dl>
</div>
<div class="section" id="rule-types">
-<h4><a class="toc-backref" href="#id22">Rule types</a></h4>
+<h4><a class="toc-backref" href="#id22">4.2.2.2 Rule types</a></h4>
<dl class="docutils">
<dt>Simple Rules</dt>
<dd><p class="first">A simple rule resolves <strong>exact string matches</strong> (case-insensitive).</p>
@@ -1035,7 +1035,7 @@ as "<dev-lang/R-2.14"</li>
</dl>
</div>
<div class="section" id="rule-file-examples">
-<h4><a class="toc-backref" href="#id23">Rule File Examples</a></h4>
+<h4><a class="toc-backref" href="#id23">4.2.2.3 Rule File Examples</a></h4>
<p>This sections lists some rule file examples.
See <a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a> for a formal<precise,..?> description.</p>
<dl class="docutils">
@@ -1087,7 +1087,7 @@ if you've installed <em>roverlay</em> with <em>emerge</em>,
else in <em><R Overlay src directory>/simple-deprules.d</em>.</p>
</div>
<div class="section" id="rule-file-syntax">
-<h4><a class="toc-backref" href="#id24">Rule File Syntax</a></h4>
+<h4><a class="toc-backref" href="#id24">4.2.2.4 Rule File Syntax</a></h4>
<p>Simple dependency rule files have a special syntax. Each rule is introduced
with the resolving <em>dependency</em> prefixed by a <em>keychar</em> that sets the rule
type if required. The <em>dependency strings</em> resolved by this rule are listed
@@ -1190,7 +1190,7 @@ will be read as normal <em>dependency strings</em>.</dd>
</div>
</div>
<div class="section" id="expected-overlay-result-structure-of-the-generated-overlay">
-<h2><a class="toc-backref" href="#id25">Expected Overlay Result / Structure of the generated overlay</a></h2>
+<h2><a class="toc-backref" href="#id25">4.3 Expected Overlay Result / Structure of the generated overlay</a></h2>
<p>Assuming that you're using the default configuration (where possible) and
the <em>R-packages</em> eclass file, the result should look like:</p>
<pre class="code text literal-block">
@@ -1211,17 +1211,17 @@ the <em>R-packages</em> eclass file, the result should look like:</p>
</div>
</div>
<div class="section" id="configuration-reference">
-<h1><a class="toc-backref" href="#id26">Configuration Reference</a></h1>
+<h1><a class="toc-backref" href="#id26">5 Configuration Reference</a></h1>
<div class="section" id="dependency-rules">
-<h2><a class="toc-backref" href="#id27">Dependency Rules</a></h2>
+<h2><a class="toc-backref" href="#id27">5.1 Dependency Rules</a></h2>
<p><merge with basic..overview::deprules></p>
</div>
<div class="section" id="repositories">
-<h2><a class="toc-backref" href="#id28">Repositories</a></h2>
+<h2><a class="toc-backref" href="#id28">5.2 Repositories</a></h2>
<p><merge with basic..overview::repo></p>
</div>
<div class="section" id="main-config">
-<h2><a class="toc-backref" href="#id29">Main Config</a></h2>
+<h2><a class="toc-backref" href="#id29">5.3 Main Config</a></h2>
<dl class="docutils" id="distfiles-root">
<dt>DISTFILES_ROOT</dt>
<dd><></dd>
@@ -1229,7 +1229,7 @@ the <em>R-packages</em> eclass file, the result should look like:</p>
<p>The main config file uses shell syntax.</p>
</div>
<div class="section" id="field-definition">
-<h2><a class="toc-backref" href="#id30">Field Definition</a></h2>
+<h2><a class="toc-backref" href="#id30">5.4 Field Definition</a></h2>
<p>The field definition file uses <a class="reference external" href="http://docs.python.org/library/configparser.html">ConfigParser</a> syntax. For an example, see
<a class="reference internal" href="#default-field-definition-file">default field definition file</a>.</p>
<p>Each information field has its own section which declares a set of options
@@ -1310,9 +1310,9 @@ are ignored, too, the main difference is the log message.</dd>
</div>
</div>
<div class="section" id="appendix">
-<h1><a class="toc-backref" href="#id31">Appendix</a></h1>
+<h1><a class="toc-backref" href="#id31">6 Appendix</a></h1>
<div class="section" id="default-field-definition-file">
-<h2><a class="toc-backref" href="#id32">Default Field Definition File</a></h2>
+<h2><a class="toc-backref" href="#id32">6.1 Default Field Definition File</a></h2>
<p>This is the default field definition file (without any ignored fields):</p>
<pre class="code ini literal-block">
<span class="k">[Description]</span>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2012-08-16 16:28 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2012-08-16 16:28 UTC (permalink / raw
To: gentoo-commits
commit: 961ebb5758d419464398faaa33ebebfa9cabee27
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Thu Aug 16 16:28:19 2012 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Thu Aug 16 16:28:19 2012 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=961ebb57
doc: html version
---
doc/html/usage.html | 970 +++++++++++++++++++++++++++++++--------------------
1 files changed, 585 insertions(+), 385 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index bc9cb85..8326ec4 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -314,6 +314,10 @@ ul.auto-toc {
</style>
</head>
<body>
+<div class="header">
+Automatically Generated Overlay of R packages - Manual (Aug 16 2012)
+<hr class="header"/>
+</div>
<div class="document">
@@ -329,70 +333,108 @@ ul.auto-toc {
</ul>
</li>
<li><a class="reference internal" href="#running-roverlay" id="id9">3 Running Roverlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#required-configuration-steps" id="id10">3.1 Required configuration steps</a></li>
-<li><a class="reference internal" href="#running-it" id="id11">3.2 Running it</a></li>
-<li><a class="reference internal" href="#providing-a-package-mirror" id="id12">3.3 Providing a package mirror</a></li>
+<li><a class="reference internal" href="#required-configuration-steps" id="id10">3.1 Required configuration steps</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id11">3.1.1 Extended Configuration / Where to go from here?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#running-it" id="id12">3.2 Running it</a></li>
+<li><a class="reference internal" href="#providing-a-package-mirror" id="id13">3.3 Providing a package mirror</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#implementation-overview" id="id13">4 Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#repositories-getting-packages" id="id14">4.1 Repositories / Getting Packages</a><ul class="auto-toc">
-<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id15">4.1.1 A word about repo config files</a></li>
-<li><a class="reference internal" href="#rsync-repos" id="id16">4.1.2 Rsync repos</a></li>
-<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id17">4.1.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="id18">4.1.4 Getting packages from several remotes using http and a package list</a></li>
-<li><a class="reference internal" href="#using-local-directories" id="id19">4.1.5 Using local directories</a></li>
+<li><a class="reference internal" href="#basic-implementation-overview" id="id14">4 Basic Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#how-roverlay-works" id="id15">4.1 How <em>roverlay</em> works</a></li>
+<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id16">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#expected-ebuild-result" id="id17">4.2.1 Expected Ebuild Result</a></li>
+<li><a class="reference internal" href="#expected-metadata-xml-result" id="id18">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-rules-resolving-dependencies" id="id20">4.2 Dependency Rules / Resolving Dependencies</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id21">4.2.1 Dependency types</a></li>
-<li><a class="reference internal" href="#simple-dependency-rules" id="id22">4.2.2 Simple Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#rule-variants" id="id23">4.2.2.1 Rule Variants</a></li>
-<li><a class="reference internal" href="#rule-types" id="id24">4.2.2.2 Rule types</a></li>
-<li><a class="reference internal" href="#rule-file-examples" id="id25">4.2.2.3 Rule File Examples</a></li>
-<li><a class="reference internal" href="#rule-file-syntax" id="id26">4.2.2.4 Rule File Syntax</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#repositories-getting-packages" id="id19">5 Repositories / Getting Packages</a><ul class="auto-toc">
+<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id20">5.1 A word about repo config files</a></li>
+<li><a class="reference internal" href="#rsync-repos" id="id21">5.2 Rsync repos</a></li>
+<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id22">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="id23">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="id24">5.5 Using local directories</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id27">4.3 Expected Overlay Result / Structure of the generated overlay</a></li>
+<li><a class="reference internal" href="#dependency-rules" id="id25">6 Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#simple-dependency-rules" id="id26">6.1 Simple Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#rule-variants" id="id27">6.1.1 Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id28">6.1.2 Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id29">6.1.3 Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id30">6.1.4 Rule File Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#depres-console" id="id28">5 DepRes Console</a></li>
-<li><a class="reference internal" href="#configuration-reference" id="id29">6 Configuration Reference</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-rules" id="id30">6.1 Dependency Rules</a></li>
-<li><a class="reference internal" href="#repositories" id="id31">6.2 Repositories</a></li>
-<li><a class="reference internal" href="#main-config" id="id32">6.3 Main Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#misc-options" id="id33">6.3.1 misc options</a></li>
-<li><a class="reference internal" href="#overlay-options" id="id34">6.3.2 overlay options</a></li>
-<li><a class="reference internal" href="#other-config-files" id="id35">6.3.3 other config files</a></li>
-<li><a class="reference internal" href="#logging" id="id36">6.3.4 logging</a><ul class="auto-toc">
-<li><a class="reference internal" href="#console-logging" id="id37">6.3.4.1 console logging</a></li>
-<li><a class="reference internal" href="#file-logging" id="id38">6.3.4.2 file logging</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id39">6.3.5 options for debugging, manual dependency rule creation and testing</a></li>
+<li><a class="reference internal" href="#configuration-reference" id="id31">7 Configuration Reference</a><ul class="auto-toc">
+<li><a class="reference internal" href="#misc-options" id="id32">7.1 misc options</a></li>
+<li><a class="reference internal" href="#overlay-options" id="id33">7.2 overlay options</a></li>
+<li><a class="reference internal" href="#other-config-files" id="id34">7.3 other config files</a></li>
+<li><a class="reference internal" href="#logging" id="id35">7.4 logging</a><ul class="auto-toc">
+<li><a class="reference internal" href="#console-logging" id="id36">7.4.1 console logging</a></li>
+<li><a class="reference internal" href="#file-logging" id="id37">7.4.2 file logging</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#id2" id="id40">6.4 Field Definition</a></li>
+<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id38">7.5 options for debugging, manual dependency rule creation and testing</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#appendix" id="id41">7 Appendix</a><ul class="auto-toc">
-<li><a class="reference internal" href="#default-field-definition-file" id="id42">7.1 Default Field Definition File</a></li>
+<li><a class="reference internal" href="#field-definition-config" id="id39">8 Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id40">8.1 Example: The default field definition file</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#dependency-resolution-console" id="id41">9 Dependency Resolution Console</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id42">10 Implementation Overview</a></li>
</ul>
</div>
<div class="section" id="introduction">
-<h1><a class="toc-backref" href="#id3">1 Introduction</a></h1>
-<p><em>roverlay</em> is
-Automatically Generated Overlay of R packages;;
-GSoC Project;;
-<>;;</p>
+<h1><a class="toc-backref" href="#contents">1 Introduction</a></h1>
+<p><em>roverlay</em> is an application that aims to provide integration of R packages
+in Gentoo by creating a portage overlay for them.
+Naturally, this also requires proper dependency resolution, especially on the
+system level which cannot be done by <em>install.packages()</em> in R.</p>
+<p>The project associated with <em>roverlay</em> is called
+<em>Automatically generated overlay of R packages</em>, the initial work has been
+done during the <em>Google Summer of Code 2012</em>.</p>
+<p>At its current state, <em>roverlay</em> is capable of creating a complete overlay
+with metadata and Manifest files by reading R packages.
+It's also able to work incrementally, i.e. update an existing <em>R Overlay</em>.
+Most aspects of overlay creation are configurable with text files.</p>
+<p><em>roverlay</em> is written in python. There's no homepage available, only a
+<a class="reference external" href="http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=summary">git repository</a> that contains the source code.</p>
+<p>This document is targeted at</p>
+<blockquote>
+<ul>
+<li><p class="first">overlay maintainers who <strong>use roverlay</strong> to create the R Overlay</p>
+<p>The most relevant chapters are <a class="reference internal" href="#installation">Installation</a> (2) and
+<a class="reference internal" href="#running-roverlay">Running Roverlay</a> (3). Additionally, have a look at
+<a class="reference internal" href="#basic-implementation-overview">Basic Implementation Overview</a> (4) if you want to know what <em>roverlay</em>
+does and what to expect from the generated overlay.</p>
+</li>
+<li><p class="first"><em>roverlay</em> maintainers who <strong>control and test overlay creation</strong>,
+e.g. configure which R packages will be part of the generated overlay</p>
+<p>Depending on what you want to configure, chapters 5-8 are relevant,
+namely <a class="reference internal" href="#repositories-getting-packages">Repositories / Getting Packages</a>, <a class="reference internal" href="#dependency-rules">Dependency Rules</a>,
+<a class="reference internal" href="#configuration-reference">Configuration Reference</a> and <a class="reference internal" href="#field-definition-config">Field Definition Config</a>.</p>
+<p>There's another chapter that is only interesting for testing, the
+<a class="reference internal" href="#dependency-resolution-console">Dependency Resolution Console</a> (9), which can be used to interactively
+test dependency rules.</p>
+</li>
+<li><p class="first"><em>roverlay</em> code maintainers who want to know <strong>how roverlay works</strong> for
+code improvements etc.</p>
+<p>The most important chapter is <a class="reference internal" href="#implementation-overview">Implementation Overview</a> (10) which has
+references to other chapters (4-8) where required.</p>
+</li>
+</ul>
+</blockquote>
+<p>It's expected that you already know about <em>R packages</em> (basically a tarball)
+and some portage basics, e.g. <em>Depend Atoms</em> and what an overlay is.</p>
</div>
<div class="section" id="installation">
-<h1><a class="toc-backref" href="#id4">2 Installation</a></h1>
+<h1><a class="toc-backref" href="#contents">2 Installation</a></h1>
<div class="section" id="prerequisites">
-<h2><a class="toc-backref" href="#id5">2.1 Prerequisites</a></h2>
+<h2><a class="toc-backref" href="#contents">2.1 Prerequisites</a></h2>
<ul>
<li><p class="first">python >= 2.7 (tested with python 2.7 and 3.2)</p>
</li>
@@ -407,17 +449,18 @@ GSoC Project;;
package downloads during Manifest creation (optional)</li>
</ul>
</li>
-<li><p class="first">for generating documentation files: python docutils > 0.8.1</p>
+<li><p class="first">for generating documentation files: python docutils >= 0.9</p>
</li>
-<li><p class="first">hardware requirements (when the default configuration):</p>
+<li><p class="first">hardware requirements (when using the default configuration):</p>
<blockquote>
<dl class="docutils">
<dt>disk</dt>
<dd><ul class="first last simple">
+<li>50-55GB disk space for the R packages</li>
<li>a filesystem that supports symbolic links</li>
-<li>50-55GB disk space for the R packages when using the default
-R package hosts (CRAN with archive, BIOC, R-Forge and Omegahat)</li>
-<li><a lot of inodes for PORTAGE_RO_DISTDIR/__tmp__ and the overlay></li>
+<li>there will be many small-sized files (ebuilds),
+so a filesystem with lots of inodes and a small block size
+may be advantageous</li>
</ul>
</dd>
<dt>memory</dt>
@@ -425,11 +468,8 @@ R package hosts (CRAN with archive, BIOC, R-Forge and Omegahat)</li>
write mechanism in use. The amount can be halved (approximately) when
using a slower one.</p>
</dd>
-<dt>other</dt>
-<dd><p class="first last">No other hardware requirements. <as a measurement for computing speed,
-i/o requirements:
-overlay creation takes 3-4h on modern desktop hardware with overlay
-writing to a tmpfs, most time is spent for Manifest creation></p>
+<dt>time</dt>
+<dd><p class="first last">Expect 3-6h execution time, depending on computing and I/O speed.</p>
</dd>
</dl>
</blockquote>
@@ -437,13 +477,13 @@ writing to a tmpfs, most time is spent for Manifest creation></p>
</ul>
</div>
<div class="section" id="via-emerge-gentoo">
-<h2><a class="toc-backref" href="#id6">2.2 via emerge (Gentoo)</a></h2>
+<h2><a class="toc-backref" href="#contents">2.2 via emerge (Gentoo)</a></h2>
<p>A live ebuild is available, <a class="reference external" href="http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=blob;f=roverlay-9999.ebuild;hb=refs/heads/master">roverlay-9999.ebuild</a>.
-Add it to your local overlay and run <tt class="docutils literal">emerge roverlay</tt>, which will also
-install all config files into <em>/etc/roverlay</em>.</p>
+Add it to your local overlay and run <tt class="docutils literal">emerge roverlay</tt>, which also installs
+all necessary config files into <em>/etc/roverlay</em>.</p>
</div>
<div class="section" id="manual-installation">
-<h2><a class="toc-backref" href="#id7">2.3 Manual Installation</a></h2>
+<h2><a class="toc-backref" href="#contents">2.3 Manual Installation</a></h2>
<p>After installing the dependencies as listed in <a class="reference internal" href="#prerequisites">Prerequisites</a>,
clone the <a class="reference external" href="http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=summary">roverlay git repo</a> and then
install <em>roverlay</em> and its python modules:</p>
@@ -454,12 +494,12 @@ git clone git://git.overlays.gentoo.org/proj/R_overlay.git
</pre>
<p><tt class="docutils literal">make install</tt> also accepts some variables, namely:</p>
<ul class="simple">
-<li><em>DESTDIR</em> defaults to ''</li>
+<li><em>DESTDIR</em></li>
<li><em>BINDIR</em>, defaults to <em>DESTDIR</em>/usr/local/bin</li>
<li><em>PYMOD_FILE_LIST</em>, which lists the installed python module files
and defaults to './roverlay_files.list'</li>
-<li><em>PYTHON</em>, name of path of the python interpreter that will run 'setup.py',
-defaults to 'python'</li>
+<li><em>PYTHON</em>, name or path of the python interpreter that is used to run
+'setup.py', defaults to 'python'</li>
</ul>
<p><em>roverlay</em> can later be uninstalled with <tt class="docutils literal">make uninstall</tt>.</p>
<div class="note">
@@ -472,19 +512,19 @@ The <em>make</em> targets take care of this.</p>
</div>
<div class="warning">
<p class="first admonition-title">Warning</p>
-<p class="last">Support for this installation type is limited - it won't install/create
+<p class="last">Support for this installation type is limited - it doesn't create/install
any config files!</p>
</div>
</div>
<div class="section" id="using-roverlay-without-installation">
-<h2><a class="toc-backref" href="#id8">2.4 Using <em>roverlay</em> without installation</a></h2>
-<p>This is possible, too. Make sure to meet the dependencies as listed
-in <a class="reference internal" href="#prerequisites">Prerequisites</a>.
-Then, simply clone the git repository to a local directory that
-will later be referenced as the <em>R Overlay src directory</em>.</p>
+<h2><a class="toc-backref" href="#contents">2.4 Using <em>roverlay</em> without installation</a></h2>
+<p>This is possible, too.
+Make sure to meet the dependencies as listed in <a class="reference internal" href="#prerequisites">Prerequisites</a>.
+Then, simply clone the git repository to a local directory that is referenced
+as the <em>R Overlay src directory</em> from now on.</p>
<div class="note">
<p class="first admonition-title">Note</p>
-<p>You'll have to cd into the <em>R Overlay src directory</em> before running
+<p>You have to <em>cd</em> into the <em>R Overlay src directory</em> before running
<em>roverlay</em> to ensure that the python modules can be imported correctly.</p>
<p>You can work around this by setting up a wrapper script:</p>
<pre class="code sh last literal-block">
@@ -497,11 +537,11 @@ will later be referenced as the <em>R Overlay src directory</em>.</p>
</div>
</div>
<div class="section" id="running-roverlay">
-<h1><a class="toc-backref" href="#id9">3 Running Roverlay</a></h1>
+<h1><a class="toc-backref" href="#contents">3 Running Roverlay</a></h1>
<div class="section" id="required-configuration-steps">
-<h2><a class="toc-backref" href="#id10">3.1 Required configuration steps</a></h2>
-<p><em>roverlay</em> needs a configuration file to run.</p>
-<p>If you've installed <em>roverlay</em> with <em>emerge</em>, it will look for the config
+<h2><a class="toc-backref" href="#contents">3.1 Required configuration steps</a></h2>
+<p><em>roverlay</em> needs a configuration file to run.
+If you've installed <em>roverlay</em> with <em>emerge</em>, it will look for the config
file in that order:</p>
<ol class="arabic simple">
<li><em><current directory>/R-overlay.conf</em></li>
@@ -537,7 +577,7 @@ see <a class="reference internal" href="#providing-a-package-mirror">Providing a
<p class="last">Example: DISTFILES = ~/roverlay/distfiles</p>
</dd>
<dt>LOG_FILE</dt>
-<dd><p class="first">This sets the log file.</p>
+<dd><p class="first">This sets the log file. An empty value disables file logging.</p>
<p class="last">Example: LOG_FILE = ~/roverlay/log/roverlay.log</p>
</dd>
<dt>LOG_LEVEL</dt>
@@ -545,8 +585,8 @@ see <a class="reference internal" href="#providing-a-package-mirror">Providing a
that don't override this option. Valid log levels are
<tt class="docutils literal">DEBUG</tt>, <tt class="docutils literal">INFO</tt>, <tt class="docutils literal">WARN</tt>/<tt class="docutils literal">WARNING</tt>, <tt class="docutils literal">ERROR</tt> and <tt class="docutils literal">CRITICAL</tt>.</p>
<p>Example: LOG_LEVEL = WARNING</p>
-<div class="caution last">
-<p class="first admonition-title">Caution!</p>
+<div class="note last">
+<p class="first admonition-title">Note</p>
<p class="last">Be careful with low log levels, especially <em>DEBUG</em>.
They produce a lot of messages that you probably don't want to see
and increase the size of log files dramatically.</p>
@@ -568,15 +608,13 @@ have reasonable defaults if <em>roverlay</em> has been installed using <em>emerg
<dl class="docutils">
<dt>SIMPLE_RULES_FILE</dt>
<dd><p class="first">This option lists dependency rule files and/or directories with
-such files that should be used for dependency resolution (see
-<a class="reference internal" href="#dependency-rules-resolving-dependencies">Dependency Rules / Resolving Dependencies</a>).
+such files that should be used for dependency resolution.
Although not required, this option is <strong>recommended</strong> since ebuild
creation without dependency rules fails for most R packages.</p>
<p class="last">Example: SIMPLE_RULES_FILE = ~/roverlay/config/simple-deprules.d</p>
</dd>
<dt>REPO_CONFIG</dt>
-<dd><p class="first">A list with one or more files that list repositories
-(see <a class="reference internal" href="#repositories-getting-packages">Repositories / Getting Packages</a>).
+<dd><p class="first">A list with one or more files that list repositories.
This option is <strong>required</strong> and can be overridden on the command line
via one or more <tt class="docutils literal"><span class="pre">repo-config</span> <file></tt> statements.</p>
<p class="last">Example: REPO_CONFIG = ~/roverlay/config/repo.list</p>
@@ -602,10 +640,31 @@ named <em>R-packages.eclass</em> should be part of your installation.</p>
<p>There's another option that is useful if you want to create new dependency
rules, <a class="reference internal" href="#log-file-unresolvable">LOG_FILE_UNRESOLVABLE</a>, which will write all unresolvable dependencies
to the specified file (one dependency string per line).</p>
-<p>For details and a full configuration reference, see <a class="reference internal" href="#configuration-reference">Configuration Reference</a>.</p>
+<div class="section" id="extended-configuration-where-to-go-from-here">
+<h3><a class="toc-backref" href="#contents">3.1.1 Extended Configuration / Where to go from here?</a></h3>
+<p>Proceed with <a class="reference internal" href="#running-it">Running it</a> if you're fine with the default configuration
+and the changes you've already made, otherwise the following chapters are
+relevant and should provide you with the knowledge to determine the ideal
+configuration.</p>
+<dl class="docutils">
+<dt>Repositories</dt>
+<dd>See <a class="reference internal" href="#repositories-getting-packages">Repositories / Getting Packages</a>, which describes how repositories
+can be configured.</dd>
+<dt>Dependency Rules</dt>
+<dd>See <a class="reference internal" href="#dependency-rules">Dependency Rules</a>, which explains how dependency rules work and
+how they're written.</dd>
+<dt>Main Config</dt>
+<dd>See <a class="reference internal" href="#configuration-reference">Configuration Reference</a> for all main config options like log file
+rotation and assistance for writing new <em>dependency rules</em>.</dd>
+<dt>Field Definition</dt>
+<dd>Refer to <a class="reference internal" href="#id2">Field Definition</a> in case you want to change <em>how</em> R packages
+are being read, e.g. if you want the 'Depents' information field (obviously
+a typo) to be understood as 'Depends'.</dd>
+</dl>
+</div>
</div>
<div class="section" id="running-it">
-<h2><a class="toc-backref" href="#id11">3.2 Running it</a></h2>
+<h2><a class="toc-backref" href="#contents">3.2 Running it</a></h2>
<p>If you've installed <em>roverlay</em>, you can run it with <tt class="docutils literal">roverlay</tt>, otherwise
you'll have to cd into the <em>R overlay src directory</em> and run <tt class="docutils literal">./roverlay.py</tt>.</p>
<p>In any case, the basic <em>roverlay</em> script usage is</p>
@@ -621,7 +680,8 @@ as described in <a class="reference internal" href="#required-configuration-step
The default command is <em>create</em>, which downloads the R packages (unless
explicitly forbidden to do so) and generates the overlay. This is the
desired behavior in most cases, so simply running <tt class="docutils literal">roverlay</tt> should be
-fine.</p>
+fine. See <a class="reference internal" href="#basic-implementation-overview">Basic Implementation Overview</a> if you'd rather like to know
+in detail what <em>roverlay</em> does before running it.</p>
<p><em>roverlay</em> also accepts some <strong>options</strong>, most notably:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
@@ -645,7 +705,7 @@ The latter one is faster, but consumes more memory since ebuilds must be
kept until all packages have been processed.
Test results show that memory consumption increases by factor 2 when using
the faster write mechanism (at ca. 95% ebuild creation success rate),
-<while ebuild write time decreases by ???>.</p>
+<<while ebuild write time decreases by ???>>.</p>
<p class="last">Summary: Expect 300 (slow) or 600MB (fast) memory consumption when using
the default package repositories.</p>
</td></tr>
@@ -717,18 +777,19 @@ and resolving dependencies.</p>
</dl>
</div>
<div class="section" id="providing-a-package-mirror">
-<h2><a class="toc-backref" href="#id12">3.3 Providing a package mirror</a></h2>
-<p><No recommendations at this time. The current ManifestCreation implementation
-creates a directory <em><distfiles root>/__tmp__</em> with symlinks to all packages,
-which could be used for providing packages, but this may change
-in near future since external Manifest creation is too slow
-(takes >60% of overlay creation time).></p>
+<h2><a class="toc-backref" href="#contents">3.3 Providing a package mirror</a></h2>
+<p>No recommendations available at this time.
+The current ManifestCreation implementation creates a directory
+<em><distfiles root>/__tmp__</em> with symlinks to all packages, which could be used
+for providing packages, but this may change in near future since external
+Manifest creation is too slow (takes >60% of overlay creation time).</p>
</div>
</div>
-<div class="section" id="implementation-overview">
-<h1><a class="toc-backref" href="#id13">4 Implementation Overview</a></h1>
-<p>This section gives a basic overview of how <em>roverlay</em> works.</p>
-<p><how <em>roverlay</em> basically works:></p>
+<div class="section" id="basic-implementation-overview">
+<h1><a class="toc-backref" href="#contents">4 Basic Implementation Overview</a></h1>
+<div class="section" id="how-roverlay-works">
+<h2><a class="toc-backref" href="#contents">4.1 How <em>roverlay</em> works</a></h2>
+<p>These are the steps that <em>roverlay</em> performs:</p>
<ol class="arabic simple">
<li><strong>sync</strong> - get R packages using various methods
(rsync, http, local directory)</li>
@@ -744,21 +805,28 @@ an ebuild</li>
(thread-able on a per package basis)</li>
</ol>
<blockquote>
-<ul class="simple">
-<li>read <em>p</em>'s DESCRIPTION file that contains information fields
-like 'Depends', 'Description' and 'Suggests'</li>
-<li>resolve <em>p</em>'s dependencies<ul>
-<li>differentiate between <em>required</em> and <em>optional</em> dependencies
+<ul>
+<li><p class="first">read <em>p</em>'s DESCRIPTION file that contains information fields
+like 'Depends', 'Description' and 'Suggests'</p>
+</li>
+<li><p class="first">resolve <em>p</em>'s dependencies</p>
+<ul>
+<li><p class="first">differentiate between <em>required</em> and <em>optional</em> dependencies
(for example, dependencies from the 'Depends' field are required,
-while those from 'Suggests' are optional)</li>
-<li><strong>immediately stop</strong> processing <em>p</em> if a <em>required</em> dependency
-cannot be resolved in which case a valid ebuild cannot be created</li>
+while those from 'Suggests' are optional)</p>
+</li>
+<li><p class="first"><strong>immediately stop</strong> processing <em>p</em> if a <em>required</em> dependency
+cannot be resolved in which case a valid ebuild cannot be created</p>
+<p>See also: <a class="reference internal" href="#dependency-resolution">Dependency Resolution</a></p>
+</li>
</ul>
</li>
-<li>create an ebuild for <em>p</em> by using the dependency resolution results
-and a few information fields like 'Description'</li>
-<li><strong>done</strong> with <em>p</em> - the overlay creator takes control over <em>p</em>
-and may decide to write <em>p</em>'s ebuild now (or later)</li>
+<li><p class="first">create an ebuild for <em>p</em> by using the dependency resolution results
+and a few information fields like 'Description'</p>
+</li>
+<li><p class="first"><strong>done</strong> with <em>p</em> - the overlay creator takes control over <em>p</em>
+and may decide to write <em>p</em>'s ebuild now (or later)</p>
+</li>
</ul>
</blockquote>
<ol class="arabic simple" start="5">
@@ -778,14 +846,166 @@ and may decide to write <em>p</em>'s ebuild now (or later)</li>
</ul>
</li>
</ol>
+</div>
+<div class="section" id="expected-overlay-result-structure-of-the-generated-overlay">
+<h2><a class="toc-backref" href="#contents">4.2 Expected Overlay Result / Structure of the generated overlay</a></h2>
+<p>Assuming that you're using the default configuration (where possible) and
+the <em>R-packages</em> eclass file, the result should look like:</p>
+<pre class="code text literal-block">
+<overlay root>/
+<overlay root>/eclass
+<overlay root>/eclass/R-packages.eclass
+<overlay root>/profiles
+<overlay root>/profiles/categories
+<overlay root>/profiles/repo_name
+<overlay root>/profiles/use.desc
+<overlay root>/sci-R/<many directories per R package>
+<overlay root>/sci-R/seewave/
+<overlay root>/sci-R/seewave/Manifest
+<overlay root>/sci-R/seewave/metadata.xml
+<overlay root>/sci-R/seewave/seewave-1.5.9.ebuild
+<overlay root>/sci-R/seewave/seewave-1.6.4.ebuild
+</pre>
+<div class="section" id="expected-ebuild-result">
+<h3><a class="toc-backref" href="#contents">4.2.1 Expected Ebuild Result</a></h3>
+<dl class="docutils">
+<dt>Ebuild Template</dt>
+<dd><pre class="code text first literal-block">
+<ebuild header>
+inherit <eclass(es)>
+
+DESCRIPTION="<the R package's description>"
+SRC_URI="<src uri for the R package>"
+
+IUSE="${IUSE:-}
+ R_suggests
+"
+R_SUGGESTS="<R package suggestions>"
+DEPEND="<build time dependencies for the R package>"
+RDEPEND="${DEPEND:-}
+ <runtime dependencies>
+ R_suggests? ( ${R_SUGGESTS} )
+"
+
+_UNRESOLVED_PACKAGES=(<unresolvable, but optional dependencies>)
+</pre>
+<p>Some of the variables may be missing if they're not needed.</p>
+<p>A really minimal ebuild would look like:</p>
+<pre class="code text last literal-block">
+<ebuild header>
+inherit <eclass(es)>
+
+SRC_URI="<src uri for the R package>"
+</pre>
+</dd>
+<dt>Example: seewave 1.6.4 from CRAN:</dt>
+<dd><p class="first">The default ebuild header (which cannot be changed) automatically sets
+the ebuild's copyright year to 1999-<em><current year></em>.</p>
+<pre class="code sh last literal-block">
+<span class="c"># Copyright 1999-2012 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+</span>
+<span class="nv">EAPI</span><span class="o">=</span>4
+inherit R-packages
+
+<span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Time wave analysis and graphical representation"</span>
+<span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"http://cran.r-project.org/src/contrib/seewave_1.6.4.tar.gz"</span>
+
+<span class="nv">IUSE</span><span class="o">=</span><span class="s2">"${IUSE:-}
+ R_suggests
+"</span>
+<span class="nv">R_SUGGESTS</span><span class="o">=</span><span class="s2">"sci-R/sound
+ sci-R/audio
+"</span>
+<span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"sci-R/fftw
+ sci-R/tuneR
+ >=dev-lang/R-2.15.0
+ sci-R/rpanel
+ sci-R/rgl
+"</span>
+<span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"${DEPEND:-}
+ media-libs/flac
+ sci-libs/fftw
+ media-libs/libsndfile
+ R_suggests? ( ${R_SUGGESTS} )
+"</span>
+</pre>
+</dd>
+<dt>Example: MetaPCA 0.1.3 from CRAN's archive:</dt>
+<dd><p class="first">Note the shortened <em>DESCRIPTION</em> variable that points to the <em>metadata.xml</em>
+file. This happens if the description is too long.</p>
+<pre class="code sh last literal-block">
+<span class="c"># Copyright 1999-2012 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+</span>
+<span class="nv">EAPI</span><span class="o">=</span>4
+inherit R-packages
+
+<span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"MetaPCA: Meta-analysis in the Di... (see metadata)"</span>
+<span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"http://cran.r-project.org/src/contrib/Archive/MetaPCA/MetaPCA_0.1.3.tar.gz"</span>
+
+<span class="nv">IUSE</span><span class="o">=</span><span class="s2">"${IUSE:-}
+ R_suggests
+"</span>
+<span class="nv">R_SUGGESTS</span><span class="o">=</span><span class="s2">"sci-R/doMC
+ sci-R/affy
+ sci-R/ellipse
+ sci-R/pcaPP
+ sci-R/MASS
+ sci-R/impute
+ sci-R/doSMP
+ sci-R/GEOquery
+"</span>
+<span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"sci-R/foreach"</span>
+<span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"${DEPEND:-}
+ R_suggests? ( ${R_SUGGESTS} )
+"</span>
+
+<span class="nv">_UNRESOLVED_PACKAGES</span><span class="o">=(</span><span class="s1">'hgu133plus2.db'</span><span class="o">)</span>
+</pre>
+</dd>
+</dl>
+</div>
+<div class="section" id="expected-metadata-xml-result">
+<h3><a class="toc-backref" href="#contents">4.2.2 Expected <em>metadata.xml</em> Result</a></h3>
+<p>The <em>metadata.xml</em> will contain the full description for the latest version
+of a package.</p>
+<dl class="docutils">
+<dt>Example: seewave from CRAN</dt>
+<dd><p class="first">Note the ' // ' delimiter. It will be used to separate description strings
+if a package has more than one, e.g. one in its <em>Title</em> and one in its
+<em>Description</em> information field.</p>
+<pre class="code xml last literal-block">
+<span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
+<span class="cp"><!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"></span>
+<span class="nt"><pkgmetadata></span>
+ <span class="nt"><longdescription></span>
+ Time wave analysis and graphical representation // seewave
+ provides functions for analysing, manipulating, displaying,
+ editing and synthesizing time waves (particularly sound). This
+ package processes time analysis (oscillograms and envelopes),
+ spectral content, resonance quality factor, entropy, cross
+ correlation and autocorrelation, zero-crossing, dominant
+ frequency, analytic signal, frequency coherence, 2D and 3D
+ spectrograms and many other analyses.
+ <span class="nt"></longdescription></span>
+<span class="nt"></pkgmetadata></span>
+</pre>
+</dd>
+</dl>
+</div>
+</div>
+</div>
<div class="section" id="repositories-getting-packages">
-<h2><a class="toc-backref" href="#id14">4.1 Repositories / Getting Packages</a></h2>
+<span id="repositories"></span><h1><a class="toc-backref" href="#contents">5 Repositories / Getting Packages</a></h1>
<p><em>roverlay</em> is capable of downloading R packages via rsync and http,
-and is able to use any packages locally available. The concrete method used
-to get and use the packages is determined by the concrete
-<strong>type of a repository</strong> and that's what this section is about.</p>
+and is able to use any packages locally available. The method used to get and
+use the packages is determined by the concrete <strong>type of a repository</strong> and
+that's what this section is about. It also covers repository configuration.</p>
<div class="section" id="a-word-about-repo-config-files">
-<span id="repo-config"></span><h3><a class="toc-backref" href="#id15">4.1.1 A word about repo config files</a></h3>
+<span id="repo-config"></span><h2><a class="toc-backref" href="#contents">5.1 A word about repo config files</a></h2>
<p>Repo config files use <a class="reference external" href="http://docs.python.org/library/configparser.html">ConfigParser</a> syntax (known from ini files).</p>
<p>Each repo entry section is introduced with <tt class="docutils literal">[<repo name>]</tt> and defines</p>
<ul class="simple">
@@ -798,21 +1018,22 @@ verification</li>
<p>Such options are declared with <tt class="docutils literal"><option> = <value></tt> in the repo entry.</p>
<p id="repo-config-options">The common options for repository entries are:</p>
<ul>
-<li><p class="first"><em>type</em>, which declares the repository type. Available types are:</p>
-<blockquote>
+<li><p class="first"><em>type</em> (optional), which declares the repository type.
+Available types are:</p>
<ul class="simple">
<li><a class="reference internal" href="#rsync">rsync</a></li>
<li><a class="reference internal" href="#websync-repo">websync_repo</a></li>
<li><a class="reference internal" href="#websync-pkglist">websync_pkglist</a></li>
<li><a class="reference internal" href="#local">local</a></li>
</ul>
-</blockquote>
-<p>Defaults to <em>rsync</em></p>
+<p>Defaults to <em>rsync</em>.</p>
</li>
-<li><p class="first"><em>src_uri</em>, which declares how ebuilds can download the packages. Some repo
-types use this for downloading, too.</p>
+<li><p class="first"><em>src_uri</em> (<strong>required</strong>),
+which declares how ebuilds can download the packages.
+Some repo types use this for downloading, too.</p>
</li>
-<li><p class="first"><em>directory</em>, which explicitly sets the package directory to use.
+<li><p class="first"><em>directory</em> (optional),
+which explicitly sets the package directory to use.
The default behavior is to use <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>/<repo name></p>
</li>
</ul>
@@ -823,9 +1044,9 @@ creating the default directory.</p>
</div>
</div>
<div class="section" id="rsync-repos">
-<span id="rsync"></span><h3><a class="toc-backref" href="#id16">4.1.2 Rsync repos</a></h3>
+<span id="rsync"></span><h2><a class="toc-backref" href="#contents">5.2 Rsync repos</a></h2>
<p>Runs <em>rsync</em> to download packages. Automatic sync retries are supported if
-<em>rsync</em>'s exit codes indicates chances of success.
+<em>rsync</em>'s exit code indicates chances of success.
For example, up to 3 retries are granted if <em>rsync</em> returns
<em>Partial transfer due to vanished source files</em> which likely happens when
syncing big repositories like CRAN.</p>
@@ -866,7 +1087,7 @@ Options with whitespace are not supported.</li>
</ul>
</div>
<div class="section" id="getting-packages-from-a-repository-that-supports-http-only">
-<span id="websync-repo"></span><h3><a class="toc-backref" href="#id17">4.1.3 Getting packages from a repository that supports http only</a></h3>
+<span id="websync-repo"></span><h2><a class="toc-backref" href="#contents">5.3 Getting packages from a repository that supports http only</a></h2>
<p>This is your best bet if the remote is a repository but doesn't offer
rsync access. Basic digest verification is supported (MD5).
The remote has to have a package list file, typically named
@@ -916,7 +1137,7 @@ Defaults to <em>src_uri</em>/<em>pkglist_file</em></li>
</div>
</div>
<div class="section" id="getting-packages-from-several-remotes-using-http-and-a-package-list">
-<span id="websync-pkglist"></span><h3><a class="toc-backref" href="#id18">4.1.4 Getting packages from several remotes using http and a package list</a></h3>
+<span id="websync-pkglist"></span><h2><a class="toc-backref" href="#contents">5.4 Getting packages from several remotes using http and a package list</a></h2>
<p>This is not a real repository type, instead it creates a <em>local</em> repository
by downloading single R packages from different remotes.
Its only requirement is that a package is downloadable via http.
@@ -929,7 +1150,7 @@ http://download.r-forge.r-project.org/src/contrib/zoo_1.7-7.tar.gz
http://www.omegahat.org/R/src/contrib/Aspell_0.2-0.tar.gz
...
</pre>
-<p>Comments are not supported. Assuming that such a package list exists as <at?>
+<p>Comments are not supported. Assuming that such a package list exists at
<em>~/roverlay/config/http_packages.list</em>, an example entry in the repo config
file would be:</p>
<pre class="code ini literal-block">
@@ -943,7 +1164,7 @@ file would be:</p>
</ul>
</div>
<div class="section" id="using-local-directories">
-<span id="local"></span><h3><a class="toc-backref" href="#id19">4.1.5 Using local directories</a></h3>
+<span id="local"></span><h2><a class="toc-backref" href="#contents">5.5 Using local directories</a></h2>
<p>Using local package directories is possible, too.</p>
<p>Example:</p>
<pre class="code ini literal-block">
@@ -965,47 +1186,19 @@ you should consider using one of the <strong>websync</strong> repo types,
</div>
</div>
</div>
-<div class="section" id="dependency-rules-resolving-dependencies">
-<h2><a class="toc-backref" href="#id20">4.2 Dependency Rules / Resolving Dependencies</a></h2>
-<div class="section" id="dependency-types">
-<h3><a class="toc-backref" href="#id21">4.2.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">
-<dt>Mandatory</dt>
-<dd>Ebuild creation fails if the <em>dependency string</em> in question cannot
-be resolved.</dd>
-<dt>Optional</dt>
-<dd>The opposite of <em>Mandatory</em>, ebuild creation keeps going even if the
-<em>dependency string</em> is unresolvable.</dd>
-<dt>Package Dependency</dt>
-<dd>This declares that the <em>dependency string</em> could be another R package.</dd>
-<dt>System Dependency</dt>
-<dd>This declares that the <em>dependency string</em> could be a system dependency,
-e.g. a scientific library or a video encoder.</dd>
-<dt>Try other dependency types</dt>
-<dd>This declares that the <em>dependency string</em> can be resolved by ignoring its
-dependency type partially. This property allows to resolve
-package dependencies as system dependencies and vice versa.</dd>
-</dl>
-<p><em>Mandatory</em> and <em>Option</em> are mutually exclusive.</p>
-<p>The <em>dependency type</em> of a <em>dependency string</em> is determined by the its origin,
-i.e. info field in the package's DESCRIPTION file.
-The <em>Suggests</em> field, for example,
-gets the <em>"package dependency and optional"</em> type,
-whereas the <em>SystemRequirements</em> gets <em>"system dependency and mandatory"</em>.</p>
-</div>
+<div class="section" id="dependency-rules">
+<h1><a class="toc-backref" href="#contents">6 Dependency Rules</a></h1>
<div class="section" id="simple-dependency-rules">
-<h3><a class="toc-backref" href="#id22">4.2.2 Simple Dependency Rules</a></h3>
+<h2><a class="toc-backref" href="#contents">6.1 Simple Dependency Rules</a></h2>
<p><em>Simple dependency rules</em> use a dictionary and string transformations
to resolve dependencies. <em>Fuzzy simple dependency rules</em> extend these by
-a set of regexes, which allows to resolve many dependency strings that
-minimally differ (e.g. only in the required version and/or comments:
+a set of regular expressions, which allows to resolve many dependency strings
+that minimally differ (e.g. only in the required version and/or comments:
<cite>R (>= 2.10)</cite> and <cite>R [2.14] from http://www.r-project.org/</cite>) with a single
dictionary entry.</p>
<p>This is the only rule implementation currently available.</p>
<div class="section" id="rule-variants">
-<h4><a class="toc-backref" href="#id23">4.2.2.1 Rule Variants</a></h4>
+<h3><a class="toc-backref" href="#contents">6.1.1 Rule Variants</a></h3>
<dl class="docutils">
<dt>default</dt>
<dd>The expected behavior of a dictionary-based rule: It matches one or more
@@ -1016,7 +1209,7 @@ resolve them as <strong>nothing</strong>.</dd>
</dl>
</div>
<div class="section" id="rule-types">
-<h4><a class="toc-backref" href="#id24">4.2.2.2 Rule types</a></h4>
+<h3><a class="toc-backref" href="#contents">6.1.2 Rule types</a></h3>
<dl class="docutils">
<dt>Simple Rules</dt>
<dd><p class="first">A simple rule resolves <strong>exact string matches</strong> (case-insensitive).</p>
@@ -1057,9 +1250,9 @@ as "<dev-lang/R-2.14"</li>
</dl>
</div>
<div class="section" id="rule-file-examples">
-<h4><a class="toc-backref" href="#id25">4.2.2.3 Rule File Examples</a></h4>
+<h3><a class="toc-backref" href="#contents">6.1.3 Rule File Examples</a></h3>
<p>This sections lists some rule file examples.
-See <a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a> for a formal<precise,..?> description.</p>
+See <a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a> for a formal description.</p>
<dl class="docutils">
<dt>Example 1 - <em>default</em> fuzzy rule</dt>
<dd><p class="first">A rule that matches many dependencies on dev-lang/R, for example
@@ -1073,9 +1266,15 @@ resolves them as '>=dev-lang/R-2.12', '>=dev-lang/R-2.14',
<dt>Example 2 - <em>default</em> simple rule stub</dt>
<dd><p class="first">A rule that case-insensitively matches 'zoo' and resolves it as 'sci-R/zoo',
assuming the OVERLAY_CATEGORY is set to 'sci-R':</p>
-<pre class="code text last literal-block">
+<pre class="code text literal-block">
zoo
</pre>
+<div class="note last">
+<p class="first admonition-title">Note</p>
+<p class="last">R Package rules are dynamically created at runtime and therefore not
+needed. Write them only if certain R package dependencies cannot
+be resolved. See <em>Selfdep</em> in <a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a> for details.</p>
+</div>
</dd>
<dt>Example 3 - <em>default</em> simple rule</dt>
<dd><p class="first">A rule that matches several <em>dependency strings</em> and resolves them
@@ -1109,7 +1308,7 @@ if you've installed <em>roverlay</em> with <em>emerge</em>,
else in <em><R Overlay src directory>/simple-deprules.d</em>.</p>
</div>
<div class="section" id="rule-file-syntax">
-<span id="dependency-rule-file-syntax"></span><h4><a class="toc-backref" href="#id26">4.2.2.4 Rule File Syntax</a></h4>
+<span id="dependency-rule-file-syntax"></span><h3><a class="toc-backref" href="#contents">6.1.4 Rule File Syntax</a></h3>
<p>Simple dependency rule files have a special syntax. Each rule is introduced
with the resolving <em>dependency</em> prefixed by a <em>keychar</em> that sets the rule
type if required. The <em>dependency strings</em> resolved by this rule are listed
@@ -1176,8 +1375,8 @@ Use braces <em>( ~... )</em> to work around that.</p>
<dt>Multi line rules</dt>
<dd><p class="first">resolve several <em>dependency strings</em>.
Their rule block begins with '{' + newline, followed by one
-<em>dependency string</em> per line, and ends with '}'.</p>
-<dl class="last docutils">
+<em>dependency string</em> per line, and ends with '}' in a separate line.</p>
+<dl class="docutils">
<dt>Syntax:</dt>
<dd><pre class="code text first last literal-block">
[<keychar>]<dependency> {
@@ -1188,13 +1387,49 @@ Their rule block begins with '{' + newline, followed by one
</pre>
</dd>
</dl>
+<div class="note last">
+<p class="first admonition-title">Note</p>
+<p class="last">Technically, this rule syntax can be used to specify rules with
+zero or more <em>dependency strings</em>. An empty rule doesn't make much sense,
+though.</p>
+</div>
+</dd>
+<dt>Comments</dt>
+<dd>start with <strong>#</strong>. There are a few exceptions to that, the <em>#deptype</em> and
+<em>#! NOPARSE</em> keywords. Comments inside rule blocks are not allowed and
+will be read as normal <em>dependency strings</em>.</dd>
+<dt>Selfdep</dt>
+<dd><p class="first">This is another name for <em>dependency strings</em> that are resolved by an
+R package with the same name, which is also part of the overlay being
+created.</p>
+<p>Example: <em>zoo</em> is resolved as <em>sci-R/zoo</em>, assuming that <a class="reference internal" href="#overlay-category">OVERLAY_CATEGORY</a>
+is set to <em>sci-R</em></p>
+<p>Writing selfdep rules is not necessary since <em>roverlay</em> automatically
+creates rules for all known R packages (see <a class="reference internal" href="#dynamic-selfdep-rule-pool">Dynamic Selfdep Rule Pool</a>
+for details).</p>
+<p>There are a few exceptions to that in which case selfdep rules have to
+be written:</p>
+<ul class="simple">
+<li>The <em>dependency string</em> is assumed to be a system dependency (not an
+R package). This is likely a "bug" in the DESCRIPTION file of the
+R package being processed.</li>
+<li>The R package name is not ebuild-name compliant (e.g. contains the '.'
+char, which is remapped to '_'.).
+Most <em>char remap</em> cases are handled properly, but there may be a few
+exceptions.</li>
+</ul>
+<div class="caution last">
+<p class="first admonition-title">Caution!</p>
+<p class="last">Writing unnecessary selfdep rules slows dependency resolution down!
+Each rule will exist twice, once as <em>dynamic</em> rule and once as
+the written one.</p>
+</div>
</dd>
<dt>Rule Stubs</dt>
-<dd><p class="first">There's a shorter syntax for dependencies that are resolved within the
-created overlay. For example, if your OVERLAY_CATEGORY is
-<em>sci-R</em>, <em>zoo</em> should be resolved as <em>sci-R/zoo</em>.
-This rule can be written as a single word, <em>zoo</em>. Such stubs are called
-<strong>selfdeps</strong>.</p>
+<dd><p class="first">There's a shorter syntax for selfdeps.
+For example, if your OVERLAY_CATEGORY is <em>sci-R</em>,
+<em>zoo</em> should be resolved as <em>sci-R/zoo</em>.
+This rule can be written as a single word, <em>zoo</em>.</p>
<dl class="last docutils">
<dt>Syntax:</dt>
<dd><pre class="code text first last literal-block">
@@ -1203,206 +1438,13 @@ This rule can be written as a single word, <em>zoo</em>. Such stubs are called
</dd>
</dl>
</dd>
-<dt>Comments</dt>
-<dd>start with <strong>#</strong>. There are a few exceptions to that, the <em>#deptype</em> and
-<em>#! NOPARSE</em> keywords. Comments inside rule blocks are not allowed and
-will be read as normal <em>dependency strings</em>.</dd>
</dl>
</div>
</div>
</div>
-<div class="section" id="expected-overlay-result-structure-of-the-generated-overlay">
-<h2><a class="toc-backref" href="#id27">4.3 Expected Overlay Result / Structure of the generated overlay</a></h2>
-<p>Assuming that you're using the default configuration (where possible) and
-the <em>R-packages</em> eclass file, the result should look like:</p>
-<pre class="code text literal-block">
-<overlay root>/
-<overlay root>/eclass
-<overlay root>/eclass/R-packages.eclass
-<overlay root>/profiles
-<overlay root>/profiles/categories
-<overlay root>/profiles/repo_name
-<overlay root>/profiles/use.desc
-<overlay root>/sci-R/<many directories per R package>
-<overlay root>/sci-R/seewave/
-<overlay root>/sci-R/seewave/Manifest
-<overlay root>/sci-R/seewave/metadata.xml
-<overlay root>/sci-R/seewave/seewave-1.5.9.ebuild
-<overlay root>/sci-R/seewave/seewave-1.6.4.ebuild
-</pre>
-</div>
-</div>
-<div class="section" id="depres-console">
-<h1><a class="toc-backref" href="#id28">5 DepRes Console</a></h1>
-<p>As previously stated, the <em>DepRes Console</em> is only meant for <strong>testing</strong>.
-It's an interactive console with the following features:</p>
-<ul class="simple">
-<li>resolve dependencies</li>
-<li>create new dependency rules (<strong>only single line rules</strong>)</li>
-<li>create dependency rules for each R package found in a directory</li>
-<li>load rules from files</li>
-<li>save rules to a file</li>
-</ul>
-<p>Rules are managed in a set. These so-called <em>rule pools</em> are organized in
-a <em>first-in-first-out</em> data structure that allows
-to create or remove them easily at runtime.</p>
-<p>Running <tt class="docutils literal">roverlay depres_console</tt> will print a welcome message that
-lists all available commands and a few usage hints.</p>
-<p>For reference, these commands are currently available:</p>
-<table border="1" class="docutils">
-<colgroup>
-<col width="29%" />
-<col width="71%" />
-</colgroup>
-<thead valign="bottom">
-<tr><th class="head">command</th>
-<th class="head">description</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr><td>help,
-h</td>
-<td>lists all commands</td>
-</tr>
-<tr><td>help --list,
-h --list</td>
-<td>lists all help topics for which help is available</td>
-</tr>
-<tr><td>help <em><cmd></em>,
-h <em><cmd></em></td>
-<td>prints a command-specific help message</td>
-</tr>
-<tr><td>load <em><file|dir></em>,
-l <em><file|dir></em></td>
-<td>loads a rule file or a directory with rule files
-into a new <em>rule pool</em></td>
-</tr>
-<tr><td>load_conf,
-lc</td>
-<td>loads the rule files listed in the config file
-into a new <em>rule pool</em></td>
-</tr>
-<tr><td>addrule <em><rule></em>
-+ <em><rule></em></td>
-<td>creates a new rule and adds it to the topmost,
-i.e. latest <em>rule pool</em>. This command uses
-<a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a>, but multi line rules are
-not supported.</td>
-</tr>
-<tr><td>add_pool,
-<<</td>
-<td>creates a new <em>rule pool</em></td>
-</tr>
-<tr><td>unwind,
->></td>
-<td>removes the topmost <em>rule pool</em> and all of its
-rules</td>
-</tr>
-<tr><td>resolve <em><dep></em>,
-? <em><dep></em></td>
-<td>tries to resolve the given dependency string and
-prints the result</td>
-</tr>
-<tr><td>print, p</td>
-<td>prints the rules of the topmost <em>rule pool</em></td>
-</tr>
-<tr><td>print all, p all</td>
-<td>prints the rules of all <em>rule pools</em></td>
-</tr>
-<tr><td>write <em><file></em>,
-w <em><file></em></td>
-<td>writes the rules of the topmost <em>rule pool</em> into
-<em><file></em></td>
-</tr>
-<tr><td>cd <em><dir></em></td>
-<td>changes the working directory, also creates it if
-necessary</td>
-</tr>
-<tr><td>scandir <em><dir></em>,
-sd <em><dir></em></td>
-<td>creates dependency rules for each R package found
-in <em><dir></em></td>
-</tr>
-<tr><td>set, unset</td>
-<td>prints the status of currently (in)active modes</td>
-</tr>
-<tr><td>set <em><mode></em>,
-unset <em><mode></em></td>
-<td>set or unsets <em><mode></em>. There's only one mode to
-control, the <em>shlex mode</em> which controls how
-command arguments are parsed</td>
-</tr>
-<tr><td>mkhelp</td>
-<td>verifies that each accessible command has a help
-message</td>
-</tr>
-<tr><td>exit, qq, q</td>
-<td>exit the <em>DepRes Console</em></td>
-</tr>
-</tbody>
-</table>
-<dl class="docutils">
-<dt>Example Session:</dt>
-<dd><pre class="code first last literal-block">
-== depres console ==
-Run 'help' to list all known commands
-More specifically, 'help <cmd>' prints a help message for the given
-command, and 'help --list' lists all help topics available
-Use 'load_conf' or 'lc' to load the configured rule files
-
-commands: load, unwind, set, help, >>, load_conf, <<, cd, mkhelp,
-resolve, lc, add_pool, addrule, h, +, l, li, write, p, r, ?, w, print,
-sd, unset, scandir
-exit-commands: q, qq, exit
-
-cmd % + ~dev-lang/R :: R language
-new rules:
-~dev-lang/R :: R language
---- ---
-command succeeded.
-
-cmd % ? R language
-Trying to resolve ('R language',).
-Resolved as: ('dev-lang/R',)
-
-cmd % ? R language [ 2.15 ]
-Trying to resolve ('R language [ 2.15 ]',).
-Resolved as: ('>=dev-lang/R-2.15',)
-
-cmd % ? R
-Trying to resolve ('R',).
-Channel returned None. At least one dep couldn't be resolved.
-
-cmd % p
-~dev-lang/R :: R language
-
-cmd % >>
-Pool removed from resolver.
-
-cmd % p
-
-cmd % ? R language
-Trying to resolve ('R language',).
-Channel returned None. At least one dep couldn't be resolved.
-
-cmd % exit
-</pre>
-</dd>
-</dl>
-</div>
<div class="section" id="configuration-reference">
-<h1><a class="toc-backref" href="#id29">6 Configuration Reference</a></h1>
-<div class="section" id="dependency-rules">
-<h2><a class="toc-backref" href="#id30">6.1 Dependency Rules</a></h2>
-<p><merge with basic..overview::deprules></p>
-</div>
-<div class="section" id="repositories">
-<h2><a class="toc-backref" href="#id31">6.2 Repositories</a></h2>
-<p><merge with basic..overview::repo></p>
-</div>
-<div class="section" id="main-config">
-<h2><a class="toc-backref" href="#id32">6.3 Main Config</a></h2>
-<p>The main config file uses "<option> = <value>" syntax, comment lines start
+<h1><a class="toc-backref" href="#contents">7 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.
Whitespace is ignored, file <strong>paths must not contain whitespace</strong>.</p>
@@ -1413,7 +1455,7 @@ Whitespace is ignored, file <strong>paths must not contain whitespace</strong>.<
<em>WARNING</em>, <em>ERROR</em> and <em>CRITICAL</em>.</dd>
<dt>bool</dt>
<dd><p class="first">Value is a string that represents a boolean value.</p>
-<p>This table illustrates which values strings are accepted:</p>
+<p>This table illustrates which value strings are accepted:</p>
<table border="1" class="last docutils">
<colgroup>
<col width="59%" />
@@ -1454,7 +1496,7 @@ restrictions. It's better to comment out options.</dd>
</dl>
<p>The following sections will list all config entries.</p>
<div class="section" id="misc-options">
-<h3><a class="toc-backref" href="#id33">6.3.1 misc options</a></h3>
+<h2><a class="toc-backref" href="#contents">7.1 misc options</a></h2>
<dl class="docutils" id="distfiles">
<dt>DISTFILES</dt>
<dd>Alias for <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
@@ -1473,7 +1515,7 @@ location (see <a class="reference internal" href="#repo-config-options">repo con
</dl>
</div>
<div class="section" id="overlay-options">
-<h3><a class="toc-backref" href="#id34">6.3.2 overlay options</a></h3>
+<h2><a class="toc-backref" href="#contents">7.2 overlay options</a></h2>
<dl class="docutils" id="eclass">
<dt>ECLASS</dt>
<dd>Alias to <a class="reference internal" href="#overlay-eclass">OVERLAY_ECLASS</a>.</dd>
@@ -1520,7 +1562,7 @@ per R package. All others will be removed.</p>
</dl>
</div>
<div class="section" id="other-config-files">
-<h3><a class="toc-backref" href="#id35">6.3.3 other config files</a></h3>
+<h2><a class="toc-backref" href="#contents">7.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">
@@ -1569,13 +1611,11 @@ much without dependency resolution.</p>
</dl>
</div>
<div class="section" id="logging">
-<h3><a class="toc-backref" href="#id36">6.3.4 logging</a></h3>
+<h2><a class="toc-backref" href="#contents">7.4 logging</a></h2>
<dl class="docutils" id="log-date-format">
<dt>LOG_DATE_FORMAT</dt>
-<dd><p class="first">The date format used in log messages.</p>
-<p class="last">Defaults to <em>%F %H:%M:%S</em>.
-(<<explain the date format by referencing to date(1)
-or python's logging->? module>>)</p>
+<dd><p class="first">The date format (ISO8601) used in log messages.</p>
+<p class="last">Defaults to <em>%F %H:%M:%S</em>.</p>
</dd>
</dl>
<dl class="docutils" id="log-enabled">
@@ -1596,7 +1636,7 @@ level set will use this value.</p>
</dd>
</dl>
<div class="section" id="console-logging">
-<h4><a class="toc-backref" href="#id37">6.3.4.1 console logging</a></h4>
+<h3><a class="toc-backref" href="#contents">7.4.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>
@@ -1617,7 +1657,7 @@ level set will use this value.</p>
</dl>
</div>
<div class="section" id="file-logging">
-<h4><a class="toc-backref" href="#id38">6.3.4.2 file logging</a></h4>
+<h3><a class="toc-backref" href="#contents">7.4.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
@@ -1676,7 +1716,7 @@ files will be kept.</p>
</div>
</div>
<div class="section" id="options-for-debugging-manual-dependency-rule-creation-and-testing">
-<h3><a class="toc-backref" href="#id39">6.3.5 options for debugging, manual dependency rule creation and testing</a></h3>
+<h2><a class="toc-backref" href="#contents">7.5 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
@@ -1709,10 +1749,11 @@ This will pass '--bwlimit=<value>' to all rsync commands.</p>
</dl>
</div>
</div>
-<div class="section" id="id2">
-<h2><a class="toc-backref" href="#id40">6.4 Field Definition</a></h2>
-<p>The field definition file uses <a class="reference external" href="http://docs.python.org/library/configparser.html">ConfigParser</a> syntax. For an example, see
-<a class="reference internal" href="#default-field-definition-file">default field definition file</a>.</p>
+<div class="section" id="field-definition-config">
+<span id="id2"></span><h1><a class="toc-backref" href="#contents">8 Field Definition Config</a></h1>
+<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>
<p>Each information field has its own section which declares a set of options
and flags. Flags are case-insensivitve options
without a value - they're enabled by listing them.</p>
@@ -1761,8 +1802,8 @@ The default behavior is to merge lines.</dd>
</dl>
<dl class="docutils" id="field-flag-islist">
<dt>isList</dt>
-<dd>Declares that a field's value is a list whose values are separated by
-by ',' or ';'.</dd>
+<dd>Declares that a field's value is a list whose values are separated
+by ',' and/or ';'.</dd>
</dl>
<dl class="docutils" id="field-flag-iswhitespacelist">
<dt>isWhitespaceList</dt>
@@ -1781,19 +1822,16 @@ False (e.g. is an empty string).</dd>
<dl class="docutils" id="field-flag-ignore">
<dt>ignore</dt>
<dd>Declares that a field is known but entirely ignored. Unknown fields
-are ignored, too, the main difference is the log message.</dd>
+are ignored, too, the main difference is the emitted log message if
+such a field is found.</dd>
</dl>
</blockquote>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">It won't be checked whether a flag is known or not.</p>
</div>
-</div>
-</div>
-<div class="section" id="appendix">
-<h1><a class="toc-backref" href="#id41">7 Appendix</a></h1>
-<div class="section" id="default-field-definition-file">
-<h2><a class="toc-backref" href="#id42">7.1 Default Field Definition File</a></h2>
+<div class="section" id="example-the-default-field-definition-file">
+<span id="default-field-definition-file"></span><h2><a class="toc-backref" href="#contents">8.1 Example: The default field definition file</a></h2>
<p>This is the default field definition file (without any ignored fields):</p>
<pre class="code ini literal-block">
<span class="k">[Description]</span>
@@ -1828,6 +1866,168 @@ are ignored, too, the main difference is the log message.</dd>
</pre>
</div>
</div>
+<div class="section" id="dependency-resolution-console">
+<span id="depres-console"></span><h1><a class="toc-backref" href="#contents">9 Dependency Resolution Console</a></h1>
+<p>As previously stated, the <em>DepRes Console</em> is only meant for <strong>testing</strong>.
+It's an interactive console with the following features:</p>
+<ul class="simple">
+<li>resolve dependencies</li>
+<li>create new dependency rules (<strong>only single line rules</strong>)</li>
+<li>create dependency rules for each R package found in a directory</li>
+<li>load rules from files</li>
+<li>save rules to a file</li>
+</ul>
+<p>Rules are managed in a set. These so-called <em>rule pools</em> are organized in
+a <em>first-in-first-out</em> data structure that allows
+to create or remove them easily at runtime.</p>
+<p>Running <tt class="docutils literal">roverlay depres_console</tt> will print a welcome message that
+lists all available commands and a few usage hints.</p>
+<p>For reference, these commands are currently available:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="29%" />
+<col width="71%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">command</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>help,
+h</td>
+<td>lists all commands</td>
+</tr>
+<tr><td>help --list,
+h --list</td>
+<td>lists all help topics for which help is available</td>
+</tr>
+<tr><td>help <em><cmd></em>,
+h <em><cmd></em></td>
+<td>prints a command-specific help message</td>
+</tr>
+<tr><td>load <em><file|dir></em>,
+l <em><file|dir></em></td>
+<td>loads a rule file or a directory with rule files
+into a new <em>rule pool</em></td>
+</tr>
+<tr><td>load_conf,
+lc</td>
+<td>loads the rule files listed in the config file
+into a new <em>rule pool</em></td>
+</tr>
+<tr><td>addrule <em><rule></em>
++ <em><rule></em></td>
+<td>creates a new rule and adds it to the topmost,
+i.e. latest <em>rule pool</em>. This command uses
+<a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a>, but multi line rules are
+not supported.</td>
+</tr>
+<tr><td>add_pool,
+<<</td>
+<td>creates a new <em>rule pool</em></td>
+</tr>
+<tr><td>unwind,
+>></td>
+<td>removes the topmost <em>rule pool</em> and all of its
+rules</td>
+</tr>
+<tr><td>resolve <em><dep></em>,
+? <em><dep></em></td>
+<td>tries to resolve the given dependency string and
+prints the result</td>
+</tr>
+<tr><td>print, p</td>
+<td>prints the rules of the topmost <em>rule pool</em></td>
+</tr>
+<tr><td>print all, p all</td>
+<td>prints the rules of all <em>rule pools</em></td>
+</tr>
+<tr><td>write <em><file></em>,
+w <em><file></em></td>
+<td>writes the rules of the topmost <em>rule pool</em> into
+<em><file></em></td>
+</tr>
+<tr><td>cd <em><dir></em></td>
+<td>changes the working directory, also creates it if
+necessary</td>
+</tr>
+<tr><td>scandir <em><dir></em>,
+sd <em><dir></em></td>
+<td>creates dependency rules for each R package found
+in <em><dir></em></td>
+</tr>
+<tr><td>set, unset</td>
+<td>prints the status of currently (in)active modes</td>
+</tr>
+<tr><td>set <em><mode></em>,
+unset <em><mode></em></td>
+<td>sets or unsets <em><mode></em>. There's only one mode to
+control, the <em>shlex mode</em> which controls how
+command arguments are parsed</td>
+</tr>
+<tr><td>mkhelp</td>
+<td>verifies that each accessible command has a help
+message</td>
+</tr>
+<tr><td>exit, qq, q</td>
+<td>exits the <em>DepRes Console</em></td>
+</tr>
+</tbody>
+</table>
+<dl class="docutils">
+<dt>Example Session:</dt>
+<dd><pre class="code first last literal-block">
+== depres console ==
+Run 'help' to list all known commands
+More specifically, 'help <cmd>' prints a help message for the given
+command, and 'help --list' lists all help topics available
+Use 'load_conf' or 'lc' to load the configured rule files
+
+commands: load, unwind, set, help, >>, load_conf, <<, cd, mkhelp,
+resolve, lc, add_pool, addrule, h, +, l, li, write, p, r, ?, w, print,
+sd, unset, scandir
+exit-commands: q, qq, exit
+
+cmd % + ~dev-lang/R :: R language
+new rules:
+~dev-lang/R :: R language
+--- ---
+command succeeded.
+
+cmd % ? R language
+Trying to resolve ('R language',).
+Resolved as: ('dev-lang/R',)
+
+cmd % ? R language [ 2.15 ]
+Trying to resolve ('R language [ 2.15 ]',).
+Resolved as: ('>=dev-lang/R-2.15',)
+
+cmd % ? R
+Trying to resolve ('R',).
+Channel returned None. At least one dep couldn't be resolved.
+
+cmd % p
+~dev-lang/R :: R language
+
+cmd % >>
+Pool removed from resolver.
+
+cmd % p
+
+cmd % ? R language
+Trying to resolve ('R language',).
+Channel returned None. At least one dep couldn't be resolved.
+
+cmd % exit
+</pre>
+</dd>
+</dl>
+</div>
+<div class="section" id="implementation-overview">
+<h1><a class="toc-backref" href="#contents">10 Implementation Overview</a></h1>
+<p id="dynamic-selfdep-rule-pool"><span id="dependency-resolution"></span><<work in progress; not part of the html doc yet>></p>
+</div>
</div>
</body>
</html>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2012-08-20 11:16 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2012-08-20 11:16 UTC (permalink / raw
To: gentoo-commits
commit: 2e060c1bfd58bb04ca2712b759ca6539444eb4f4
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Mon Aug 20 11:16:08 2012 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Mon Aug 20 11:16:08 2012 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=2e060c1b
doc, html: implementation overview
---
doc/html/usage.html | 628 +++++++++++++++++++++++++++++++++++++++++++++++----
1 files changed, 583 insertions(+), 45 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 8326ec4..6772a17 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -315,7 +315,7 @@ ul.auto-toc {
</head>
<body>
<div class="header">
-Automatically Generated Overlay of R packages - Manual (Aug 16 2012)
+Automatically Generated Overlay of R packages - Manual (Aug 20 2012)
<hr class="header"/>
</div>
<div class="document">
@@ -324,68 +324,100 @@ Automatically Generated Overlay of R packages - Manual (Aug 16 2012)
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#introduction" id="id3">1 Introduction</a></li>
-<li><a class="reference internal" href="#installation" id="id4">2 Installation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#prerequisites" id="id5">2.1 Prerequisites</a></li>
-<li><a class="reference internal" href="#via-emerge-gentoo" id="id6">2.2 via emerge (Gentoo)</a></li>
-<li><a class="reference internal" href="#manual-installation" id="id7">2.3 Manual Installation</a></li>
-<li><a class="reference internal" href="#using-roverlay-without-installation" id="id8">2.4 Using <em>roverlay</em> without installation</a></li>
+<li><a class="reference internal" href="#introduction" id="id4">1 Introduction</a></li>
+<li><a class="reference internal" href="#installation" id="id5">2 Installation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#prerequisites" id="id6">2.1 Prerequisites</a></li>
+<li><a class="reference internal" href="#via-emerge-gentoo" id="id7">2.2 via emerge (Gentoo)</a></li>
+<li><a class="reference internal" href="#manual-installation" id="id8">2.3 Manual Installation</a></li>
+<li><a class="reference internal" href="#using-roverlay-without-installation" id="id9">2.4 Using <em>roverlay</em> without installation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-roverlay" id="id9">3 Running Roverlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#required-configuration-steps" id="id10">3.1 Required configuration steps</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id11">3.1.1 Extended Configuration / Where to go from here?</a></li>
+<li><a class="reference internal" href="#running-roverlay" id="id10">3 Running Roverlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#required-configuration-steps" id="id11">3.1 Required configuration steps</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id12">3.1.1 Extended Configuration / Where to go from here?</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-it" id="id12">3.2 Running it</a></li>
-<li><a class="reference internal" href="#providing-a-package-mirror" id="id13">3.3 Providing a package mirror</a></li>
+<li><a class="reference internal" href="#running-it" id="id13">3.2 Running it</a></li>
+<li><a class="reference internal" href="#providing-a-package-mirror" id="id14">3.3 Providing a package mirror</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#basic-implementation-overview" id="id14">4 Basic Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-roverlay-works" id="id15">4.1 How <em>roverlay</em> works</a></li>
-<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id16">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#expected-ebuild-result" id="id17">4.2.1 Expected Ebuild Result</a></li>
-<li><a class="reference internal" href="#expected-metadata-xml-result" id="id18">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
+<li><a class="reference internal" href="#basic-implementation-overview" id="id15">4 Basic Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#how-roverlay-works" id="id16">4.1 How <em>roverlay</em> works</a></li>
+<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id17">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#expected-ebuild-result" id="id18">4.2.1 Expected Ebuild Result</a></li>
+<li><a class="reference internal" href="#expected-metadata-xml-result" id="id19">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#repositories-getting-packages" id="id19">5 Repositories / Getting Packages</a><ul class="auto-toc">
-<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id20">5.1 A word about repo config files</a></li>
-<li><a class="reference internal" href="#rsync-repos" id="id21">5.2 Rsync repos</a></li>
-<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id22">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="id23">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="id24">5.5 Using local directories</a></li>
+<li><a class="reference internal" href="#repositories-getting-packages" id="id20">5 Repositories / Getting Packages</a><ul class="auto-toc">
+<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id21">5.1 A word about repo config files</a></li>
+<li><a class="reference internal" href="#rsync-repos" id="id22">5.2 Rsync repos</a></li>
+<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id23">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="id24">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="id25">5.5 Using local directories</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-rules" id="id25">6 Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#simple-dependency-rules" id="id26">6.1 Simple Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#rule-variants" id="id27">6.1.1 Rule Variants</a></li>
-<li><a class="reference internal" href="#rule-types" id="id28">6.1.2 Rule types</a></li>
-<li><a class="reference internal" href="#rule-file-examples" id="id29">6.1.3 Rule File Examples</a></li>
-<li><a class="reference internal" href="#rule-file-syntax" id="id30">6.1.4 Rule File Syntax</a></li>
+<li><a class="reference internal" href="#dependency-rules" id="id26">6 Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#simple-dependency-rules" id="id27">6.1 Simple Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#rule-variants" id="id28">6.1.1 Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id29">6.1.2 Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id30">6.1.3 Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id31">6.1.4 Rule File Syntax</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#configuration-reference" id="id31">7 Configuration Reference</a><ul class="auto-toc">
-<li><a class="reference internal" href="#misc-options" id="id32">7.1 misc options</a></li>
-<li><a class="reference internal" href="#overlay-options" id="id33">7.2 overlay options</a></li>
-<li><a class="reference internal" href="#other-config-files" id="id34">7.3 other config files</a></li>
-<li><a class="reference internal" href="#logging" id="id35">7.4 logging</a><ul class="auto-toc">
-<li><a class="reference internal" href="#console-logging" id="id36">7.4.1 console logging</a></li>
-<li><a class="reference internal" href="#file-logging" id="id37">7.4.2 file logging</a></li>
+<li><a class="reference internal" href="#configuration-reference" id="id32">7 Configuration Reference</a><ul class="auto-toc">
+<li><a class="reference internal" href="#misc-options" id="id33">7.1 misc options</a></li>
+<li><a class="reference internal" href="#overlay-options" id="id34">7.2 overlay options</a></li>
+<li><a class="reference internal" href="#other-config-files" id="id35">7.3 other config files</a></li>
+<li><a class="reference internal" href="#logging" id="id36">7.4 logging</a><ul class="auto-toc">
+<li><a class="reference internal" href="#console-logging" id="id37">7.4.1 console logging</a></li>
+<li><a class="reference internal" href="#file-logging" id="id38">7.4.2 file logging</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id38">7.5 options for debugging, manual dependency rule creation and testing</a></li>
+<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id39">7.5 options for debugging, manual dependency rule creation and testing</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#field-definition-config" id="id40">8 Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id41">8.1 Example: The default field definition file</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dependency-resolution-console" id="id42">9 Dependency Resolution Console</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id43">10 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id44">10.1 PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id45">10.2 Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#id3" id="id46">10.2.1 Repositories</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id47">10.2.1.1 Adding new repository types</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#overlay" id="id48">10.3 Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id49">10.3.1 Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id50">10.3.2 Manifest Creation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ebuild-creation" id="id51">10.4 Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id52">10.4.1 Ebuild Variables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#overlay-creation" id="id53">10.5 Overlay Creation</a></li>
+<li><a class="reference internal" href="#dependency-resolution" id="id54">10.6 Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id55">10.6.1 Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id56">10.6.1.1 DESCRIPTION file dependency fields</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dependency-environments" id="id57">10.6.2 Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id58">10.6.3 EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id59">10.6.4 Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id60">10.6.5 Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id61">10.6.6 Dependency Resolver</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#field-definition-config" id="id39">8 Field Definition Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id40">8.1 Example: The default field definition file</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution-console" id="id41">9 Dependency Resolution Console</a></li>
-<li><a class="reference internal" href="#implementation-overview" id="id42">10 Implementation Overview</a></li>
</ul>
</div>
<div class="section" id="introduction">
@@ -1755,8 +1787,8 @@ This will pass '--bwlimit=<value>' to all rsync commands.</p>
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>
<p>Each information field has its own section which declares a set of options
-and flags. Flags are case-insensivitve options
-without a value - they're enabled by listing them.</p>
+and flags. Flags are case-insensitive options without a value - they're
+enabled by listing them.</p>
<p id="field-options"><span id="field-option"></span>Known field options:</p>
<blockquote>
<dl class="docutils" id="field-option-default-value">
@@ -1783,7 +1815,8 @@ that list (values are separated by whitespace).</dd>
</dl>
<dl class="docutils" id="field-option-alias-nocase">
<dt>alias_nocase</dt>
-<dd>Same as <a class="reference internal" href="#field-option-alias">field option: alias</a>, but aliases are case-insensitive.</dd>
+<dd>Same as <a class="reference internal" href="#field-option-alias">field option: alias</a>, but the listed aliases are
+case-insensitive.</dd>
</dl>
<dl class="docutils" id="field-option-flags">
<dt>flags</dt>
@@ -2026,7 +2059,512 @@ cmd % exit
</div>
<div class="section" id="implementation-overview">
<h1><a class="toc-backref" href="#contents">10 Implementation Overview</a></h1>
-<p id="dynamic-selfdep-rule-pool"><span id="dependency-resolution"></span><<work in progress; not part of the html doc yet>></p>
+<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">10.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>
+<ul class="simple">
+<li>the path to the R package file</li>
+<li>the origin (repository)</li>
+<li>the SRC_URI</li>
+<li>the package name, version</li>
+</ul>
+<p>Not all of these are really existent, some are calculated. <em>SRC_URI</em>,
+for example, can often be calculated by combining the origin's "root" src uri
+with the package file.</p>
+<p>Initialization may fail if the package's name cannot be understood, which is
+most likely due to unsupported versioning schemes.</p>
+<p>It is then checked whether the newly created <em>PackageInfo p</em> can be part of
+the overlay. The overlay may refuse to accept <em>p</em> if there's already an ebuild
+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">10.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>
+<ul class="simple">
+<li>load repository config from file(s)</li>
+<li>directly add a directory as <em>local repository</em></li>
+<li><em>sync</em> all repos and <em>nosync</em> all repos (offline mode)</li>
+<li>create <em>PackageInfo</em> instances for R packages from all repositories</li>
+</ul>
+<div class="section" id="id3">
+<h3><a class="toc-backref" href="#contents">10.2.1 Repositories</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,
+a repository object <em>repo</em> extends this by:</p>
+<ul>
+<li><p class="first">data</p>
+<blockquote>
+<ul>
+<li><p class="first">repository <em>type</em></p>
+</li>
+<li><p class="first">filesystem directory <em>distdir</em> where <em>repo</em>'s R packages are stored</p>
+</li>
+<li><p class="first">the <em>root src_uri</em>, which is used to determine the <em>SRC_URI</em> ebuild
+variable for all packages from <em>repo</em>:</p>
+<p><em>SRC_URI</em> = <em>root src_uri</em> + '/' + <path of R package relative to <em>distdir</em>></p>
+</li>
+<li><p class="first">other data like the sync status, repository name</p>
+</li>
+</ul>
+</blockquote>
+</li>
+<li><p class="first">functionality</p>
+<blockquote>
+<ul class="simple">
+<li>sync/nosync</li>
+<li>create <em>PackageInfo</em> instances for all packages from <em>repo</em></li>
+<li>status indicators, e.g. if sync was successful</li>
+</ul>
+</blockquote>
+</li>
+</ul>
+<p>The actual functionality depends on the <em>repository type</em>, i.e. the
+implementing class. The most basic implementation that provides all common
+data, status indicator functions and <em>PackageInfo</em> creation is called
+<em>BasicRepo</em>. It also implements a rather abstract sync function that calls
+subclass-specifc <em>_sync()</em>/<em>_nosync()</em> functions if available.
+<em>BasicRepo*s are used to realize *local repositories</em>. The other 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">10.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 sync) and what may be changed if required.
+Most repository types want to define their own sync functionality and
+can do so by implementing <em>_dosync()</em>:</p>
+<table border="1" class="docutils">
+<caption>deriving repository types from BasicRepo</caption>
+<colgroup>
+<col width="25%" />
+<col width="75%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">function/method</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>_dosync()</td>
+<td>sync packages using a remote, has to return True/False</td>
+</tr>
+<tr><td>_nosync()</td>
+<td>sync packages in offline mode (returns True/False)</td>
+</tr>
+<tr><td>sync (<em>online?</em>)</td>
+<td>implemented by <em>BasicRepo</em>, calls _dosync()/_nosync()
+if available, else checks whether <em>distdir</em> exists</td>
+</tr>
+<tr><td>scan_distdir(...)</td>
+<td><em>BasicRepo</em>: creates <em>PackageInfo</em> instances for all
+R packages in <em>distdir</em>. Derived classes can override
+this e.g. if they want to expose only synced packages</td>
+</tr>
+<tr><td>ready()</td>
+<td>tells whether _dosync()/_nosync() was successful,
+used by <em>RepoList</em> to decide whether to call
+scan_distdir() or not. Properly implemented by
+<em>BasicRepo</em> when using its sync() method, else needs
+to be overridden.</td>
+</tr>
+<tr><td>__init__()</td>
+<td>has to be implemented if the new class has additional
+data. Refer to in-code documentation and examples.</td>
+</tr>
+</tbody>
+</table>
+<p>The <em>RsyncRepo</em>, for example, extends <em>BasicRepo</em> by rsync-specific data, e.g.
+the uri used for rsync, and has its own <em>__init__()</em> method. It also
+implements <em>_dosync()</em>, which calls the <em>rsync</em> executable in a filtered
+environment that contains only variables like USER, PATH and RSYNC_PROXY.
+The other available repository types have an internal-only implementation:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="24%" />
+<col width="28%" />
+<col width="48%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">repository type</th>
+<th class="head">repository class</th>
+<th class="head">_dosync() implementation</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>local</td>
+<td>BasicRepo</td>
+<td><em>not applicable</em></td>
+</tr>
+<tr><td>rsync</td>
+<td>RsyncRepo</td>
+<td><strong>external</strong>, using <em>rsync</em> in
+a filtered environment</td>
+</tr>
+<tr><td>websync_repo
+websync_pkglist</td>
+<td>WebsyncRepo
+WebsyncPackageList</td>
+<td>internal, using <em>urllib</em></td>
+</tr>
+</tbody>
+</table>
+<p>Repository types also need an entry in the repository config loader in order
+to be accessible.</p>
+</div>
+</div>
+</div>
+<div class="section" id="overlay">
+<h2><a class="toc-backref" href="#contents">10.3 Overlay</a></h2>
+<p>The <em>overlay</em> is roverlay's central data structure that represents a <em>portage
+overlay</em>. It's organized in a tree structure (overlay root, categories,
+package directories) and implements all overlay-related functionality:</p>
+<ul>
+<li><p class="first">Scan the <em>portage overlay</em> for existing ebuilds</p>
+</li>
+<li><p class="first">Add <em>PackageInfo</em> objects to the overlay. Packages can be declined if
+they already exist as ebuild (incremental overlay).
+Adding multiple packages at once is <strong>thread-safe</strong>, but overlay writing
+is not.</p>
+</li>
+<li><p class="first">List all known packages (filesystem and runtime/memory)</p>
+</li>
+<li><p class="first">Write the overlay to its filesystem location</p>
+<blockquote>
+<ul class="simple">
+<li>initialize the overlay (write the <em>profiles/</em> directory,
+import eclass files)</li>
+<li>Write ebuilds; all <em>PackageInfo</em> instances with an ebuild will be written</li>
+<li>Generate and write metadata</li>
+<li>Write Manifest files</li>
+</ul>
+</blockquote>
+</li>
+<li><p class="first">Features like <a class="reference internal" href="#overlay-keep-nth-latest">OVERLAY_KEEP_NTH_LATEST</a> make use of ebuild deletion,
+but unconditional ebuild deletion is only available on the package directory
+level</p>
+</li>
+</ul>
+<div class="section" id="metadata-creation">
+<h3><a class="toc-backref" href="#contents">10.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
+('Title' and 'Description') into the metadata file.
+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">10.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
+package files are passed in the PORTAGE_RO_DISTDIRS variable and DISTDIR
+is set to <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>/__tmp__.</p>
+</div>
+</div>
+<div class="section" id="ebuild-creation">
+<h2><a class="toc-backref" href="#contents">10.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>
+<ol class="arabic simple">
+<li>Read the DESCRIPTION file of <em>p</em> R package tarball and stores the
+data in an associative array ('DESCRIPTION field' -> 'data')</li>
+<li>Call <a class="reference internal" href="#dependency-resolution">dependency resolution</a></li>
+<li>If dependency resolution was successful, dependency ebuild variables are
+created (<em>DEPEND</em>, <em>RDEPEND</em> and <em>R_SUGGESTS</em>, also <em>IUSE</em>, <em>MISSINGDEPS</em>).
+Otherwise <strong>ebuild creation stops</strong> and <em>p</em> is marked as
+<em>ebuild uncreatable</em>. The overlay creation may decide to remove <em>p</em> in
+order to save memory etc.</li>
+<li>The <em>DESCRIPTION</em> and <em>SRC_URI</em> variables are created</li>
+<li><strong>done</strong> - Generate the ebuild as text, add it to <em>p</em> and mark <em>p</em>
+as <em>ebuild successfully created</em></li>
+</ol>
+<div class="section" id="ebuild-variables">
+<h3><a class="toc-backref" href="#contents">10.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
+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">10.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.
+It accepts <em>PackageInfo</em> objects as input, tries to reserve a slot in the
+overlay for them, and, if successful, adds them to the work queue.</p>
+<p>The work queue is processed by <em>OverlayWorkers</em> that run ebuild creation
+for a <em>PackageInfo</em> object and inform the <em>OverlayCreation</em> about the result
+afterwards. Overlay creation doesn't stop if an ebuild cannot be created,
+instead the event is logged. Running more than one <em>OverlayWorker</em> in parallel
+is possible.</p>
+</div>
+<div class="section" id="dependency-resolution">
+<h2><a class="toc-backref" href="#contents">10.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
+<em>Dynamic DEPEND</em>/<em>DEPEND Atom</em>.</p>
+<p>The ebuild creation uses <em>channels</em> for communication with the <em>dependency
+resolver</em>, so-called <em>EbuildJobChannels</em> that handle the 'high-level'
+string-to-string dependency resolution for a set of <em>dependency strings</em>.
+Typically, one <em>channel</em> is used per ebuild variable (DEPEND, RDEPEND and
+R_SUGGESTS).</p>
+<p>From the ebuild creation perspective, dependency resolution works like this:</p>
+<ol class="arabic simple">
+<li>Collect the <em>dependency strings</em> from the DESCRIPTION data and add them
+to the communication <em>channels</em> (up to 3 will be used)</li>
+<li>Wait until all channels are <em>done</em></li>
+<li><strong>Stop ebuild creation</strong> if a channel reports that it couldn't resolve
+all <em>required dependencies</em>. No ebuild can be created in that case.</li>
+<li><strong>Successfully done</strong> - transfer the channel results to ebuild variables</li>
+</ol>
+<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">10.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">
+<dt>Mandatory</dt>
+<dd>Ebuild creation fails if the <em>dependency string</em> in question cannot
+be resolved.</dd>
+<dt>Optional</dt>
+<dd>The opposite of <em>Mandatory</em>, ebuild creation keeps going even if the
+<em>dependency string</em> is unresolvable.</dd>
+<dt>Package Dependency</dt>
+<dd>This declares that the <em>dependency string</em> could be another R package.</dd>
+<dt>System Dependency</dt>
+<dd>This declares that the <em>dependency string</em> could be a system dependency,
+e.g. a scientific library or a video encoder.</dd>
+<dt>Try other dependency types</dt>
+<dd>This declares that the <em>dependency string</em> can be resolved by ignoring its
+dependency type partially. This property allows to resolve package
+dependencies as system dependencies and vice versa. Throughout this
+document, such property is indicated by <em>TRY_OTHER</em> and
+<em><preferred dependency type> first</em>, e.g. <em>package first</em>.</dd>
+</dl>
+<p><em>Mandatory</em> and <em>Option</em> are mutually exclusive.</p>
+<p>The <em>dependency type</em> of a <em>dependency string</em> is determined by its origin,
+i.e. info field in the package's DESCRIPTION file.
+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">10.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>
+<table border="1" class="docutils">
+<caption>R package dependency fields</caption>
+<colgroup>
+<col width="28%" />
+<col width="31%" />
+<col width="25%" />
+<col width="15%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">dependency field</th>
+<th class="head">ebuild variable</th>
+<th class="head">dependency type</th>
+<th class="head">required</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>Depends</td>
+<td rowspan="2">DEPEND</td>
+<td rowspan="2">package first</td>
+<td rowspan="4"><em>yes</em></td>
+</tr>
+<tr><td>Imports</td>
+</tr>
+<tr><td>LinkingTo</td>
+<td rowspan="2">RDEPEND</td>
+<td>package first</td>
+</tr>
+<tr><td>SystemRequirements</td>
+<td>system first</td>
+</tr>
+<tr><td rowspan="2">Suggests</td>
+<td>R_SUGGESTS</td>
+<td>package <strong>only</strong></td>
+<td><strong>no</strong></td>
+</tr>
+<tr><td>_UNRESOLVED_PACKAGES</td>
+<td><em>unresolvable</em></td>
+<td><em>n/a</em></td>
+</tr>
+</tbody>
+</table>
+<p>A non-empty <em>R_SUGGESTS</em> ebuild variable will enable the <em>R_suggests</em> USE
+flag. <em>R_SUGGESTS</em> is a runtime dependency (a <em>Dynamic DEPEND</em> in <em>RDEPEND</em>).</p>
+<p>Ebuild creation keeps going if an optional dependency cannot be resolved.
+This isn't desirable for most <em>dependency fields</em>, but extremely
+useful for R package suggestions that often link to other repositories or
+private homepages.
+Such unresolvable dependencies go into the <em>_UNRESOLVED_PACKAGES</em> ebuild
+variable.
+Whether and how this variable is used is up to the eclass file(s).
+The default <em>R-packages eclass</em> reports unresolvable,
+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">10.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
+resolution state (<em>resolved</em>, <em>unresolvable</em>, <em>to be processed</em>) and the
+resolving resolving <em>dependency</em>, if any.</p>
+<p>It is initialized by the communication <em>channel</em> and processed by the
+<em>dependency resolver</em>.</p>
+</div>
+<div class="section" id="ebuildjob-channel">
+<h3><a class="toc-backref" href="#contents">10.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>
+<p>Its mode of operation is</p>
+<ol class="arabic">
+<li><p class="first">Accept <em>dependency strings</em>, create <em>dependency environments</em> for them
+and add them to the registered <em>dependency resolver</em>.
+The <em>dependency resolver</em> may already be resolving the added dependencies.</p>
+<p>Leave this state if the ebuild creation signalizes that all <em>dependency
+strings</em> have been added.</p>
+</li>
+<li><p class="first">Tell the <em>dependency resolver</em> that this channel is waiting for results.</p>
+<p>The channel using a <em>blocking queue</em> for waiting. It expects that the
+<em>dependency resolver</em> sends processed <em>dependency environments</em> though this
+channel, whether successful or not.</p>
+</li>
+<li><p class="first">Process each received <em>dependency environment</em> until all dependencies have
+been resolved or waiting doesn't make sense anymore, i.e. at least one
+<em>required</em> dependency could not be resolved.</p>
+<ul class="simple">
+<li>add successful resolved dependencies to the "resolved" list</li>
+<li>add unresolved, but optional dependencies to the "unresolvable" list</li>
+<li>any other unresolved dependency is interpreted as "channel cannot satisfy
+the request", the <strong>channel stops waiting</strong> for remaining results.</li>
+</ul>
+</li>
+<li><p class="first">The <em>channel</em> returns the result to the ebuild creation.</p>
+<p>It's either a 2-tuple of resolved and unresolvable dependencies or
+"nothing" if the request is not satisfiable, i.e. one or more required
+dependencies are unresolvable.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="dependency-rule-pools">
+<h3><a class="toc-backref" href="#contents">10.6.4 Dependency Rule Pools</a></h3>
+<p>The <em>dependency resolver</em> doesn't 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>
+<p>A <em>dependency rule pool</em> combines a list of <em>dependency rules</em> with a
+<em>dependency type</em> and is able to determine whether it accepts the type
+of a <em>dependency string</em> or not.</p>
+<p><em>Dependency rules</em> are objects with a "matches" function that returns the
+<em>resolving dependency</em> if it matches the given <em>dependency string</em>, else
+it returns "cannot resolve". Note the difference between
+"a rule cannot resolve a dep string" and "dep string is unresolvable",
+which means that no rule can resolve a particular <em>dependency string</em>.</p>
+<p>See <a class="reference internal" href="#dependency-rules">Dependency Rules</a> for the concrete rules available.</p>
+<p>Rule pools are normally created by reading rule files, but some rule pools
+consist of rules that exist in memory only.
+These are called <strong>Dynamic Rule Pools</strong> and use runtime data like "all known
+R packages" to create rules.</p>
+<p id="dynamic-selfdep-rule-pool"><em>roverlay</em> uses one dynamic rule pool, the <strong>Dynamic Selfdep Rule Pool</strong>.
+This pool contains rules for all known R packages and is able to resolve
+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">10.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">
+<dt>Listener modules</dt>
+<dd><p class="first">Listener modules are used to react on certain dependency resolution
+<em>events</em>, e.g. if a <em>dependency environment</em> is unresolvable.
+They usually have access to the <em>event</em> and the <em>dependency environment</em>.
+However, they cannot begin communication with the <em>dependency resolver</em>.</p>
+<p class="last">In the current <em>roverlay</em> implementation, a listener module is used to
+report all unresolvable dependencies to a separate file.</p>
+</dd>
+<dt>Channel modules</dt>
+<dd><p class="first">Channel modules interact with the resolver, e.g. queue dependencies for
+resolution, wait for results, and send them to the other end.</p>
+<p class="last">The previously described <a class="reference internal" href="#ebuildjob-channel">EbuildJob Channel</a> is such a channel.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="dependency-resolver">
+<h3><a class="toc-backref" href="#contents">10.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>. It's main task is a loop that
+processes all queued <em>dependency environments</em> and sends the result back to
+their origin (an <em>EbuildJob channel</em>).</p>
+<p>Besides that, it also offers functionality to register new channels, add
+listeners, load rule pools from one or more files etc..
+A dependency resolver has to be explicitly closed in which case it will stop
+working and notify all listeners about that.</p>
+<p>Its mode of operation of operation is best described in pseudo-code:</p>
+<pre class="code text literal-block">
+while <dependencies queued for resolution>
+
+ depenv <= get the next dependency environment
+ resolved <= False
+
+ # try to resolve depenv
+
+ if <depenv's type contains PACKAGE> and
+ <the dynamic selfdep rule pool resolves depenv>
+
+ resolved <= True
+
+ else
+ if <a rule pool accepts depenv's type and resolves depenv>
+ resolved <= True
+
+ else if <depenv's type contains TRY_OTHER>
+
+ if <a rule pool supports TRY_OTHER and doesn't accept depenv's type
+ and resolves depenv>
+
+ resolved <= True
+ end if
+ end if
+
+
+ # send the result to depenv's channel
+
+ if resolved
+ mark depenv as resolved, add the resolving dependency to it
+
+ else
+ mark depenv as unresolvable
+
+ end if
+
+ send depenv to its channel
+
+end while
+</pre>
+<p>The dependency resolver can be <strong>run as thread</strong>, in which case the while loop
+becomes "loop until resolver closes".</p>
+</div>
+</div>
</div>
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-01-09 19:15 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-01-09 19:15 UTC (permalink / raw
To: gentoo-commits
commit: 43572c4e38f2518152f145bcce714ee9404f58af
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jan 9 18:52:26 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jan 9 18:52:26 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=43572c4e
doc/html: update user config file location
---
doc/html/usage.html | 20 ++++++++++++++------
1 files changed, 14 insertions(+), 6 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 836b031..026d8b7 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -3,13 +3,13 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.9: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.9.1: http://docutils.sourceforge.net/" />
<title>Automatically Generated Overlay of R packages</title>
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
+:Id: $Id: html4css1.css 7434 2012-05-11 21:06:27Z milde $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
@@ -249,10 +249,18 @@ pre.address {
margin-top: 0 ;
font: inherit }
-pre.literal-block, pre.doctest-block, pre.math {
+pre.literal-block, pre.doctest-block, pre.math, pre.code {
margin-left: 2em ;
margin-right: 2em }
+pre.code .ln { /* line numbers */
+ color: grey;
+}
+
+.code {
+ background-color: #eeeeee
+}
+
span.classifier {
font-family: sans-serif ;
font-style: oblique }
@@ -573,11 +581,11 @@ as the <em>R Overlay src directory</em> from now on.</p>
<div class="section" id="required-configuration-steps">
<h2><a class="toc-backref" href="#contents">3.1 Required configuration steps</a></h2>
<p><em>roverlay</em> needs a configuration file to run.
-If roverlay has been installed with <em>emerge</em>, it will for the config file in
+If roverlay has been installed with <em>emerge</em>, it will look for the config file in
that order:</p>
<ol class="arabic simple">
<li><em><current directory>/R-overlay.conf</em></li>
-<li><em>~/.R-overlay.conf</em></li>
+<li><em>~/roverlay/R-overlay.conf</em></li>
<li><em>/etc/roverlay/R-overlay.conf</em>,
which is part of the installation but has to be modified.</li>
</ol>
@@ -2565,7 +2573,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2012-08-20.
+Generated on: 2013-01-09.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-03-05 11:27 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-03-05 11:27 UTC (permalink / raw
To: gentoo-commits
commit: 32acbc7561c58d8913ff93dd6108b2f7f015b9ce
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Mar 5 11:26:48 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Mar 5 11:26:48 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=32acbc75
doc/html: Package Rule Files, Configuration
---
doc/html/usage.html | 964 +++++++++++++++++++++++++++++++++++++++------------
1 files changed, 738 insertions(+), 226 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index ff2a36f..d216676 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -3,13 +3,13 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.9.1: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Automatically Generated Overlay of R packages</title>
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 7434 2012-05-11 21:06:27Z milde $
+:Id: $Id: html4css1.css 7514 2012-09-14 14:27:12Z milde $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
@@ -77,7 +77,7 @@ div.tip p.admonition-title {
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
+div.warning p.admonition-title, .code .error {
color: red ;
font-weight: bold ;
font-family: sans-serif }
@@ -253,13 +253,14 @@ pre.literal-block, pre.doctest-block, pre.math, pre.code {
margin-left: 2em ;
margin-right: 2em }
-pre.code .ln { /* line numbers */
- color: grey;
-}
-
-.code {
- background-color: #eeeeee
-}
+pre.code .ln { color: grey; } /* line numbers */
+pre.code, code { background-color: #eeeeee }
+pre.code .comment, code .comment { color: #5C6576 }
+pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
+pre.code .literal.string, code .literal.string { color: #0C5404 }
+pre.code .name.builtin, code .name.builtin { color: #352B84 }
+pre.code .deleted, code .deleted { background-color: #DEB0A1}
+pre.code .inserted, code .inserted { background-color: #A3D289}
span.classifier {
font-family: sans-serif ;
@@ -328,96 +329,111 @@ ul.auto-toc {
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#introduction" id="id4">1 Introduction</a></li>
-<li><a class="reference internal" href="#installation" id="id5">2 Installation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#prerequisites" id="id6">2.1 Prerequisites</a></li>
-<li><a class="reference internal" href="#via-emerge-gentoo" id="id7">2.2 via emerge (Gentoo)</a></li>
-<li><a class="reference internal" href="#manual-installation" id="id8">2.3 Manual Installation</a></li>
-<li><a class="reference internal" href="#using-roverlay-without-installation" id="id9">2.4 Using <em>roverlay</em> without installation</a></li>
+<li><a class="reference internal" href="#introduction" id="id5">1 Introduction</a></li>
+<li><a class="reference internal" href="#installation" id="id6">2 Installation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#prerequisites" id="id7">2.1 Prerequisites</a></li>
+<li><a class="reference internal" href="#via-emerge-gentoo" id="id8">2.2 via emerge (Gentoo)</a></li>
+<li><a class="reference internal" href="#manual-installation" id="id9">2.3 Manual Installation</a></li>
+<li><a class="reference internal" href="#using-roverlay-without-installation" id="id10">2.4 Using <em>roverlay</em> without installation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#running-roverlay" id="id11">3 Running Roverlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#required-configuration-steps" id="id12">3.1 Required configuration steps</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id13">3.1.1 Extended Configuration / Where to go from here?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#running-it" id="id14">3.2 Running it</a></li>
+<li><a class="reference internal" href="#providing-a-package-mirror" id="id15">3.3 Providing a package mirror</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#basic-implementation-overview" id="id16">4 Basic Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#how-roverlay-works" id="id17">4.1 How <em>roverlay</em> works</a></li>
+<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id18">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#expected-ebuild-result" id="id19">4.2.1 Expected Ebuild Result</a></li>
+<li><a class="reference internal" href="#expected-metadata-xml-result" id="id20">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
+</ul>
+</li>
</ul>
</li>
-<li><a class="reference internal" href="#running-roverlay" id="id10">3 Running Roverlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#required-configuration-steps" id="id11">3.1 Required configuration steps</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id12">3.1.1 Extended Configuration / Where to go from here?</a></li>
+<li><a class="reference internal" href="#repositories-getting-packages" id="id21">5 Repositories / Getting Packages</a><ul class="auto-toc">
+<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id22">5.1 A word about repo config files</a></li>
+<li><a class="reference internal" href="#rsync-repos" id="id23">5.2 Rsync repos</a></li>
+<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>
</ul>
</li>
-<li><a class="reference internal" href="#running-it" id="id13">3.2 Running it</a></li>
-<li><a class="reference internal" href="#providing-a-package-mirror" id="id14">3.3 Providing a package mirror</a></li>
+<li><a class="reference internal" href="#dependency-rules" id="id27">6 Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#simple-dependency-rules" id="id28">6.1 Simple Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#rule-variants" id="id29">6.1.1 Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id30">6.1.2 Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id31">6.1.3 Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id32">6.1.4 Rule File Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#basic-implementation-overview" id="id15">4 Basic Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-roverlay-works" id="id16">4.1 How <em>roverlay</em> works</a></li>
-<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id17">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#expected-ebuild-result" id="id18">4.2.1 Expected Ebuild Result</a></li>
-<li><a class="reference internal" href="#expected-metadata-xml-result" id="id19">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#package-rules" id="id33">7 Package Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#package-rule-file-syntax" id="id34">7.1 Package Rule File Syntax</a><ul class="auto-toc">
+<li><a class="reference internal" href="#match-blocks" id="id35">7.1.1 Match Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-match-block-syntax" id="id36">7.1.1.1 Extended Match Block Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#repositories-getting-packages" id="id20">5 Repositories / Getting Packages</a><ul class="auto-toc">
-<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id21">5.1 A word about repo config files</a></li>
-<li><a class="reference internal" href="#rsync-repos" id="id22">5.2 Rsync repos</a></li>
-<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id23">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="id24">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="id25">5.5 Using local directories</a></li>
+<li><a class="reference internal" href="#action-blocks" id="id37">7.1.2 Action Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-action-block-syntax" id="id38">7.1.2.1 Extended Action Block Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-rules" id="id26">6 Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#simple-dependency-rules" id="id27">6.1 Simple Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#rule-variants" id="id28">6.1.1 Rule Variants</a></li>
-<li><a class="reference internal" href="#rule-types" id="id29">6.1.2 Rule types</a></li>
-<li><a class="reference internal" href="#rule-file-examples" id="id30">6.1.3 Rule File Examples</a></li>
-<li><a class="reference internal" href="#rule-file-syntax" id="id31">6.1.4 Rule File Syntax</a></li>
+<li><a class="reference internal" href="#package-rule-examples" id="id39">7.1.3 Package Rule Examples</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#configuration-reference" id="id32">7 Configuration Reference</a><ul class="auto-toc">
-<li><a class="reference internal" href="#misc-options" id="id33">7.1 misc options</a></li>
-<li><a class="reference internal" href="#overlay-options" id="id34">7.2 overlay options</a></li>
-<li><a class="reference internal" href="#other-config-files" id="id35">7.3 other config files</a></li>
-<li><a class="reference internal" href="#logging" id="id36">7.4 logging</a><ul class="auto-toc">
-<li><a class="reference internal" href="#console-logging" id="id37">7.4.1 console logging</a></li>
-<li><a class="reference internal" href="#file-logging" id="id38">7.4.2 file logging</a></li>
+<li><a class="reference internal" href="#configuration-reference" id="id40">8 Configuration Reference</a><ul class="auto-toc">
+<li><a class="reference internal" href="#misc-options" id="id41">8.1 misc options</a></li>
+<li><a class="reference internal" href="#overlay-options" id="id42">8.2 overlay options</a></li>
+<li><a class="reference internal" href="#other-config-files" id="id43">8.3 other config files</a></li>
+<li><a class="reference internal" href="#logging" id="id44">8.4 logging</a><ul class="auto-toc">
+<li><a class="reference internal" href="#console-logging" id="id45">8.4.1 console logging</a></li>
+<li><a class="reference internal" href="#file-logging" id="id46">8.4.2 file logging</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id39">7.5 options for debugging, manual dependency rule creation and testing</a></li>
+<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id47">8.5 options for debugging, manual dependency rule creation and testing</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#field-definition-config" id="id40">8 Field Definition Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id41">8.1 Example: The default field definition file</a></li>
+<li><a class="reference internal" href="#field-definition-config" id="id48">9 Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id49">9.1 Example: The default field definition file</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution-console" id="id42">9 Dependency Resolution Console</a></li>
-<li><a class="reference internal" href="#implementation-overview" id="id43">10 Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#packageinfo" id="id44">10.1 PackageInfo</a></li>
-<li><a class="reference internal" href="#repository-management" id="id45">10.2 Repository Management</a><ul class="auto-toc">
-<li><a class="reference internal" href="#id3" id="id46">10.2.1 Repositories</a><ul class="auto-toc">
-<li><a class="reference internal" href="#adding-new-repository-types" id="id47">10.2.1.1 Adding new repository types</a></li>
+<li><a class="reference internal" href="#dependency-resolution-console" id="id50">10 Dependency Resolution Console</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id51">11 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id52">11.1 PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id53">11.2 Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#id4" id="id54">11.2.1 Repositories</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id55">11.2.1.1 Adding new repository types</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay" id="id48">10.3 Overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#metadata-creation" id="id49">10.3.1 Metadata Creation</a></li>
-<li><a class="reference internal" href="#manifest-creation" id="id50">10.3.2 Manifest Creation</a></li>
+<li><a class="reference internal" href="#overlay" id="id56">11.3 Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id57">11.3.1 Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id58">11.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#ebuild-creation" id="id51">10.4 Ebuild Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#ebuild-variables" id="id52">10.4.1 Ebuild Variables</a></li>
+<li><a class="reference internal" href="#ebuild-creation" id="id59">11.4 Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id60">11.4.1 Ebuild Variables</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay-creation" id="id53">10.5 Overlay Creation</a></li>
-<li><a class="reference internal" href="#dependency-resolution" id="id54">10.6 Dependency Resolution</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id55">10.6.1 Dependency types</a><ul class="auto-toc">
-<li><a class="reference internal" href="#description-file-dependency-fields" id="id56">10.6.1.1 DESCRIPTION file dependency fields</a></li>
+<li><a class="reference internal" href="#overlay-creation" id="id61">11.5 Overlay Creation</a></li>
+<li><a class="reference internal" href="#dependency-resolution" id="id62">11.6 Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id63">11.6.1 Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id64">11.6.1.1 DESCRIPTION file dependency fields</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-environments" id="id57">10.6.2 Dependency Environments</a></li>
-<li><a class="reference internal" href="#ebuildjob-channel" id="id58">10.6.3 EbuildJob Channel</a></li>
-<li><a class="reference internal" href="#dependency-rule-pools" id="id59">10.6.4 Dependency Rule Pools</a></li>
-<li><a class="reference internal" href="#dependency-resolver-modules" id="id60">10.6.5 Dependency Resolver Modules</a></li>
-<li><a class="reference internal" href="#dependency-resolver" id="id61">10.6.6 Dependency Resolver</a></li>
+<li><a class="reference internal" href="#dependency-environments" id="id65">11.6.2 Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id66">11.6.3 EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id67">11.6.4 Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id68">11.6.5 Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id69">11.6.6 Dependency Resolver</a></li>
</ul>
</li>
</ul>
@@ -485,7 +501,7 @@ references to other chapters (4-8) where required.</p>
</li>
<li><p class="first">for Manifest creation:</p>
<ul class="simple">
-<li><em>ebuild</em> from portage</li>
+<li>portage (<em>ebuild</em> and/or the <em>portage libs</em> directly)</li>
<li><em>true</em> or <em>echo</em> from coreutils or busybox for preventing
package downloads during Manifest creation (optional)</li>
</ul>
@@ -498,7 +514,7 @@ package downloads during Manifest creation (optional)</li>
<dt>disk</dt>
<dd><ul class="first last simple">
<li>50-55GB disk space for the R packages</li>
-<li>a filesystem that supports symbolic links</li>
+<li>a filesystem that supports symbolic or hard links</li>
<li>there will be many small-sized files (ebuilds),
so a filesystem with lots of inodes and a small block size
may be advantageous</li>
@@ -510,7 +526,9 @@ write mechanism in use. The amount can be halved (approximately) when
using a slower one.</p>
</dd>
<dt>time</dt>
-<dd><p class="first last">Expect 3-6h execution time, depending on computing and I/O speed.</p>
+<dd><p class="first last">Expect 3-6h execution time for the first run, depending on computing
+and I/O speed. <em>roverlay</em> is able to work in incremental mode,
+thus making subsequent runs need a lot less time.</p>
</dd>
</dl>
</blockquote>
@@ -530,7 +548,7 @@ all necessary config files into <em>/etc/roverlay</em>.</p>
<pre class="code sh literal-block">
git clone git://git.overlays.gentoo.org/proj/R_overlay.git
-<span class="nb">cd </span>R_overlay <span class="o">&&</span> make install
+<span class="name builtin">cd </span>R_overlay <span class="operator">&&</span> make install
</pre>
<p><tt class="docutils literal">make install</tt> also accepts some variables, namely:</p>
<ul class="simple">
@@ -568,10 +586,10 @@ as the <em>R Overlay src directory</em> from now on.</p>
<em>roverlay</em> to ensure that the python modules can be imported correctly.</p>
<p>You can work around this by setting up a wrapper script:</p>
<pre class="code sh last literal-block">
-<span class="c">#!/bin/sh
+<span class="comment">#!/bin/sh
# /usr/local/bin/roverlay.sh
# example wrapper script for roverlay
-</span><span class="nb">cd</span> <span class="k">${</span><span class="nv">ROVERLAY_SRC</span><span class="k">:-</span><span class="p">~/roverlay/src</span><span class="k">}</span> <span class="o">&&</span> ./roverlay.py <span class="nv">$*</span>
+</span><span class="name builtin">cd</span> <span class="keyword">${</span><span class="name variable">ROVERLAY_SRC</span><span class="keyword">:-</span><span class="punctuation">~/roverlay/src</span><span class="keyword">}</span> <span class="operator">&&</span> ./roverlay.py <span class="literal string double">"$@"</span>
</pre>
</div>
</div>
@@ -608,14 +626,14 @@ via <tt class="docutils literal"><span class="pre">--overlay</span> <director
<dd><p class="first">This sets the root directory of all per-repo package directories.
This option is <strong>required</strong> and can be overridden on the command line
via <tt class="docutils literal"><span class="pre">--distroot</span> <directory></tt>.</p>
-<div class="note">
-<p class="first admonition-title">Note</p>
-<p class="last">This directory will also contain a directory <em>__tmp__</em>
-with symlinks to all packages which can be used as package mirror,
-see <a class="reference internal" href="#providing-a-package-mirror">Providing a package mirror</a>.</p>
-</div>
<p class="last">Example: DISTFILES = ~/roverlay/distfiles</p>
</dd>
+<dt>DISTDIR</dt>
+<dd><p class="first">This sets the directory that contains symbolic or hard links to
+all package files for which an ebuild could be created. It is used
+for Manifest file creation and can serve as package mirror directory.</p>
+<p class="last">Example: DISTDIR = ~/roverlay/distdir</p>
+</dd>
<dt>LOG_FILE</dt>
<dd><p class="first">This sets the log file. An empty value disables file logging.</p>
<p class="last">Example: LOG_FILE = ~/roverlay/log/roverlay.log</p>
@@ -629,7 +647,7 @@ without an own log level. Valid log levels are <tt class="docutils literal">DEBU
<p class="first admonition-title">Note</p>
<p class="last">Be careful with low log levels, especially <em>DEBUG</em>.
They produce a lot of messages that help to track ebuild creation of
-the R packages, but increase the size of log files dramatically.</p>
+the R packages, but increase the log file size dramatically.</p>
</div>
</dd>
<dt>LOG_LEVEL_CONSOLE</dt>
@@ -656,9 +674,15 @@ creation without dependency rules fails for most R packages.</p>
<dt>REPO_CONFIG</dt>
<dd><p class="first">A list with one or more files that list repositories.
This option is <strong>required</strong> and can be overridden on the command line
-via one or more <tt class="docutils literal"><span class="pre">repo-config</span> <file></tt> statements.</p>
+via one or more <tt class="docutils literal"><span class="pre">--repo-config</span> <file></tt> statements.</p>
<p class="last">Example: REPO_CONFIG = ~/roverlay/config/repo.list</p>
</dd>
+<dt>PACKAGE_RULES:</dt>
+<dd><p class="first">A list of files and/or directories with package rules.
+Package rules can be used to control overlay/ebuild creation.
+This option is not required.</p>
+<p class="last">Example: PACKAGE_RULES = ~/roverlay/config/packagerules.d</p>
+</dd>
<dt>FIELD_DEFINITION</dt>
<dd><p class="first">The value of this option should point to a field definition file which
controls how an R package's DESCRIPTION file is read.
@@ -675,6 +699,24 @@ Specifying an eclass file that implements the ebuild phase functions
named <em>R-packages.eclass</em> should be part of your installation.</p>
<p class="last">Example: OVERLAY_ECLASS = ~/roverlay/eclass/R-packages.eclass</p>
</dd>
+<dt>DISTDIR_STRATEGY</dt>
+<dd><p class="first">A list of methods that define how to create the DISTDIR. The methods
+will be tried in the specified order, until the first one succeeds.
+The available methods are <em>symlink</em>, <em>hardlink</em>, <em>copy</em> and <em>tmpdir</em>.
+This option is <strong>required</strong>.</p>
+<p>Example: DISTDIR_STRATEGY = "hardlink symlink"</p>
+<p class="last">Try hard links first, then fall back to symbolic ones. This is the
+default value for this option.</p>
+</dd>
+<dt>DISTDIR_FLAT</dt>
+<dd><p class="first">This option controls whether DISTDIR will contain per-package
+subdirectories with links to the package files ("not flat") or all
+links/files in a single directory ("flat"). This option is ignored
+if DISTDIR_STRATEGY is <em>tmpdir</em>.
+Leaving this option as-is (<em>enabled</em>) is recommended if you want to use
+DISTDIR as package mirror.</p>
+<p class="last">Example: DISTDIR_FLAT = yes</p>
+</dd>
</dl>
</blockquote>
<p>There is another option that is useful for creating new dependency rules,
@@ -692,11 +734,13 @@ can be configured.</dd>
<dt>Dependency Rules</dt>
<dd>See <a class="reference internal" href="#dependency-rules">Dependency Rules</a>, which explains the dependency rule syntax amd how
they work.</dd>
+<dt>Package Rules</dt>
+<dd>See <a class="reference internal" href="#package-rules">Package Rules</a>, which explains how to control <em>ebuild creation</em>.</dd>
<dt>Main Config</dt>
<dd>See <a class="reference internal" href="#configuration-reference">Configuration Reference</a> for all main config options like log file
rotation and assistance for writing new <em>dependency rules</em>.</dd>
<dt>Field Definition</dt>
-<dd>Refer to <a class="reference internal" href="#id2">Field Definition</a> in case you want to change <em>how</em> R packages
+<dd>Refer to <a class="reference internal" href="#id3">Field Definition</a> in case you want to change <em>how</em> R packages
are being read, e.g. if you want the 'Depents' information field (obviously
a typo) to be understood as 'Depends'.</dd>
</dl>
@@ -785,11 +829,15 @@ an overlay that is not suitable for production usage.</p>
<tr><td> </td><td>Repo config file to use. Can be specified more than once.
This disables all repo files configured in the main config file.</td></tr>
<tr><td class="option-group" colspan="2">
-<kbd><span class="option">--distdir <var>directory</var></span>, <span class="option">--from <var>directory</var></span></kbd></td>
+<kbd><span class="option">--local-distdir <var>directory</var></span>, <span class="option">--from <var>directory</var></span></kbd></td>
</tr>
<tr><td> </td><td>Create an overlay using the packages found in <em>directory</em>. This disables
all other repositories. The <em>SRC_URI</em> ebuild variable will be invalid!</td></tr>
<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--print-package-rules</span>, <span class="option">--ppr</span></kbd></td>
+</tr>
+<tr><td> </td><td>Print package rules to stdout after parsing them and exit.</td></tr>
+<tr><td class="option-group" colspan="2">
<kbd><span class="option">--overlay <var>directory</var></span>, <span class="option">-O <var>directory</var></span></kbd></td>
</tr>
<tr><td> </td><td>Create the overlay at the given position.</td></tr>
@@ -815,11 +863,15 @@ and resolving dependencies.</p>
</div>
<div class="section" id="providing-a-package-mirror">
<h2><a class="toc-backref" href="#contents">3.3 Providing a package mirror</a></h2>
-<p>No recommendations available at this time.
-The current ManifestCreation implementation creates a directory
-<em><distfiles root>/__tmp__</em> with symlinks to all packages, which could be used
-for providing packages, but this may change in near future since external
-Manifest creation is too slow (takes >60% of overlay creation time).</p>
+<p><a class="reference internal" href="#distdir">DISTDIR</a> with a non-temporary strategy can be used to create a directory
+containing all package files (as symbolic/hard links or as files).
+You have to set up a <em>data service</em>, e.g. an http server, that makes this
+directory accessible.</p>
+<p>The default configuration will create hard links to all package files for
+which an ebuild could be created in a single directory. It will fall back
+to symbolic links if hard links are not supported. This should be fine in
+most cases, but fine-tuning can be done via <a class="reference internal" href="#overlay-distdir-strategy">OVERLAY_DISTDIR_STRATEGY</a> and
+<a class="reference internal" href="#overlay-distdir-flat">OVERLAY_DISTDIR_FLAT</a>.</p>
</div>
</div>
<div class="section" id="basic-implementation-overview">
@@ -827,19 +879,28 @@ Manifest creation is too slow (takes >60% of overlay creation time).</p>
<div class="section" id="how-roverlay-works">
<h2><a class="toc-backref" href="#contents">4.1 How <em>roverlay</em> works</a></h2>
<p>These are the steps that <em>roverlay</em> performs:</p>
-<ol class="arabic simple">
-<li><strong>sync</strong> - get R packages using various methods
-(rsync, http, local directory)</li>
-<li>scan the R Overlay directory (if it exists) for valid ebuilds</li>
-<li>queue all R packages for ebuild creation<ul>
-<li>all repositories are asked to list their packages which are then added
-to a queue</li>
-<li>packages may be declined by the overlay creator if they already have
-an ebuild</li>
+<ol class="arabic">
+<li><p class="first"><strong>sync</strong> - get R packages using various methods
+(rsync, http, local directory)</p>
+</li>
+<li><p class="first">scan the R Overlay directory (if it exists) for valid ebuilds</p>
+</li>
+<li><p class="first"><strong>add</strong> - queue all R packages for ebuild creation</p>
+<ul>
+<li><p class="first">all repositories are asked to list their packages which are then added
+to a queue</p>
+</li>
+<li><p class="first">packages may be declined by the overlay creator if they already have
+an ebuild</p>
+</li>
+<li><p class="first">packages may be declined or manipulated by package rules</p>
+<p>See also: <a class="reference internal" href="#package-rules">Package Rules</a></p>
+</li>
</ul>
</li>
-<li><strong>create</strong> - process each package <em>p</em> from the package queue
-(thread-able on a per package basis)</li>
+<li><p class="first"><strong>create</strong> - process each package <em>p</em> from the package queue
+(thread-able on a per package basis)</p>
+</li>
</ol>
<blockquote>
<ul>
@@ -869,14 +930,15 @@ and may decide to write <em>p</em>'s ebuild now (or later)</p>
<ol class="arabic simple" start="5">
<li>write the overlay<ul>
<li>write all ebuilds
-(thread-able on a per package basis)</li>
+(supports threads on a per package basis)</li>
<li>write the <em>metadata.xml</em> files
-(thread-able on a per package basis)<ul>
+(supports threads on a per package basis)<ul>
<li>this uses the latest created ebuild available for a package</li>
</ul>
</li>
<li>write the <em>Manifest</em> files
-(not thread-able)<ul>
+(does not support threads by default / supports threads on a per package
+basis when using <em>portage</em> directly)<ul>
<li>this uses all ebuilds availabe for a package</li>
</ul>
</li>
@@ -939,29 +1001,29 @@ SRC_URI="<src uri for the R package>"
<dd><p class="first">The default ebuild header (which cannot be changed) automatically sets
the ebuild's copyright year to 1999-<em><current year></em>.</p>
<pre class="code sh last literal-block">
-<span class="c"># Copyright 1999-2012 Gentoo Foundation
+<span class="comment"># Copyright 1999-2012 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
</span>
-<span class="nv">EAPI</span><span class="o">=</span>4
+<span class="name variable">EAPI</span><span class="operator">=</span>4
inherit R-packages
-<span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Time wave analysis and graphical representation"</span>
-<span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"http://cran.r-project.org/src/contrib/seewave_1.6.4.tar.gz"</span>
+<span class="name variable">DESCRIPTION</span><span class="operator">=</span><span class="literal string double">"Time wave analysis and graphical representation"</span>
+<span class="name variable">SRC_URI</span><span class="operator">=</span><span class="literal string double">"http://cran.r-project.org/src/contrib/seewave_1.6.4.tar.gz"</span>
-<span class="nv">IUSE</span><span class="o">=</span><span class="s2">"${IUSE:-}
+<span class="name variable">IUSE</span><span class="operator">=</span><span class="literal string double">"${IUSE:-}
R_suggests
"</span>
-<span class="nv">R_SUGGESTS</span><span class="o">=</span><span class="s2">"sci-R/sound
+<span class="name variable">R_SUGGESTS</span><span class="operator">=</span><span class="literal string double">"sci-R/sound
sci-R/audio
"</span>
-<span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"sci-R/fftw
+<span class="name variable">DEPEND</span><span class="operator">=</span><span class="literal string double">"sci-R/fftw
sci-R/tuneR
>=dev-lang/R-2.15.0
sci-R/rpanel
sci-R/rgl
"</span>
-<span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"${DEPEND:-}
+<span class="name variable">RDEPEND</span><span class="operator">=</span><span class="literal string double">"${DEPEND:-}
media-libs/flac
sci-libs/fftw
media-libs/libsndfile
@@ -973,20 +1035,20 @@ inherit R-packages
<dd><p class="first">Note the shortened <em>DESCRIPTION</em> variable that points to the <em>metadata.xml</em>
file. This happens if the description is too long.</p>
<pre class="code sh last literal-block">
-<span class="c"># Copyright 1999-2012 Gentoo Foundation
+<span class="comment"># Copyright 1999-2012 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
</span>
-<span class="nv">EAPI</span><span class="o">=</span>4
+<span class="name variable">EAPI</span><span class="operator">=</span>4
inherit R-packages
-<span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"MetaPCA: Meta-analysis in the Di... (see metadata)"</span>
-<span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"http://cran.r-project.org/src/contrib/Archive/MetaPCA/MetaPCA_0.1.3.tar.gz"</span>
+<span class="name variable">DESCRIPTION</span><span class="operator">=</span><span class="literal string double">"MetaPCA: Meta-analysis in the Di... (see metadata)"</span>
+<span class="name variable">SRC_URI</span><span class="operator">=</span><span class="literal string double">"http://cran.r-project.org/src/contrib/Archive/MetaPCA/MetaPCA_0.1.3.tar.gz"</span>
-<span class="nv">IUSE</span><span class="o">=</span><span class="s2">"${IUSE:-}
+<span class="name variable">IUSE</span><span class="operator">=</span><span class="literal string double">"${IUSE:-}
R_suggests
"</span>
-<span class="nv">R_SUGGESTS</span><span class="o">=</span><span class="s2">"sci-R/doMC
+<span class="name variable">R_SUGGESTS</span><span class="operator">=</span><span class="literal string double">"sci-R/doMC
sci-R/affy
sci-R/ellipse
sci-R/pcaPP
@@ -995,12 +1057,12 @@ inherit R-packages
sci-R/doSMP
sci-R/GEOquery
"</span>
-<span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"sci-R/foreach"</span>
-<span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"${DEPEND:-}
+<span class="name variable">DEPEND</span><span class="operator">=</span><span class="literal string double">"sci-R/foreach"</span>
+<span class="name variable">RDEPEND</span><span class="operator">=</span><span class="literal string double">"${DEPEND:-}
R_suggests? ( ${R_SUGGESTS} )
"</span>
-<span class="nv">_UNRESOLVED_PACKAGES</span><span class="o">=(</span><span class="s1">'hgu133plus2.db'</span><span class="o">)</span>
+<span class="name variable">_UNRESOLVED_PACKAGES</span><span class="operator">=(</span><span class="literal string single">'hgu133plus2.db'</span><span class="operator">)</span>
</pre>
</dd>
</dl>
@@ -1015,10 +1077,10 @@ of a package.</p>
if a package has more than one, e.g. one in its <em>Title</em> and one in its
<em>Description</em> information field.</p>
<pre class="code xml last literal-block">
-<span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
-<span class="cp"><!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"></span>
-<span class="nt"><pkgmetadata></span>
- <span class="nt"><longdescription></span>
+<span class="comment preproc"><?xml version="1.0" encoding="UTF-8"?></span>
+<span class="comment preproc"><!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"></span>
+<span class="name tag"><pkgmetadata></span>
+ <span class="name tag"><longdescription></span>
Time wave analysis and graphical representation // seewave
provides functions for analysing, manipulating, displaying,
editing and synthesizing time waves (particularly sound). This
@@ -1027,8 +1089,8 @@ if a package has more than one, e.g. one in its <em>Title</em> and one in its
correlation and autocorrelation, zero-crossing, dominant
frequency, analytic signal, frequency coherence, 2D and 3D
spectrograms and many other analyses.
- <span class="nt"></longdescription></span>
-<span class="nt"></pkgmetadata></span>
+ <span class="name tag"></longdescription></span>
+<span class="name tag"></pkgmetadata></span>
</pre>
</dd>
</dl>
@@ -1101,23 +1163,23 @@ Options with whitespace are not supported.</li>
<li><p class="first">CRAN</p>
<blockquote>
<pre class="code ini literal-block">
-<span class="k">[CRAN]</span>
-<span class="na">type</span> <span class="o">=</span> <span class="s">rsync</span>
-<span class="na">rsync_uri</span> <span class="o">=</span> <span class="s">cran.r-project.org::CRAN/src/contrib</span>
-<span class="na">src_uri</span> <span class="o">=</span> <span class="s">http://cran.r-project.org/src/contrib</span>
-<span class="na">extra_rsync_opts</span> <span class="o">=</span> <span class="s">--progress --exclude=PACKAGES --exclude=PACKAGES.gz</span>
+<span class="keyword">[CRAN]</span>
+<span class="name attribute">type</span> <span class="operator">=</span> <span class="literal string">rsync</span>
+<span class="name attribute">rsync_uri</span> <span class="operator">=</span> <span class="literal string">cran.r-project.org::CRAN/src/contrib</span>
+<span class="name attribute">src_uri</span> <span class="operator">=</span> <span class="literal string">http://cran.r-project.org/src/contrib</span>
+<span class="name attribute">extra_rsync_opts</span> <span class="operator">=</span> <span class="literal string">--progress --exclude=PACKAGES --exclude=PACKAGES.gz</span>
</pre>
</blockquote>
</li>
<li><p class="first">CRAN's archive:</p>
<blockquote>
<pre class="code ini literal-block">
-<span class="k">[CRAN-Archive]</span>
-<span class="na">type</span> <span class="o">=</span> <span class="s">rsync</span>
-<span class="na">rsync_uri</span> <span class="o">=</span> <span class="s">cran.r-project.org::CRAN/src/contrib/Archive</span>
-<span class="na">src_uri</span> <span class="o">=</span> <span class="s">http://cran.r-project.org/src/contrib/Archive</span>
-<span class="na">extra_rsync_opts</span> <span class="o">=</span> <span class="s">--progress</span>
-<span class="na">recursive</span> <span class="o">=</span> <span class="s">yes</span>
+<span class="keyword">[CRAN-Archive]</span>
+<span class="name attribute">type</span> <span class="operator">=</span> <span class="literal string">rsync</span>
+<span class="name attribute">rsync_uri</span> <span class="operator">=</span> <span class="literal string">cran.r-project.org::CRAN/src/contrib/Archive</span>
+<span class="name attribute">src_uri</span> <span class="operator">=</span> <span class="literal string">http://cran.r-project.org/src/contrib/Archive</span>
+<span class="name attribute">extra_rsync_opts</span> <span class="operator">=</span> <span class="literal string">--progress</span>
+<span class="name attribute">recursive</span> <span class="operator">=</span> <span class="literal string">yes</span>
</pre>
</blockquote>
</li>
@@ -1132,29 +1194,29 @@ with a special syntax (debian control file syntax).</p>
<p>A package list example,
excerpt from <a class="reference external" href="http://www.omegahat.org/R/src/contrib/PACKAGES">omegahat's PACKAGES file</a> (as of Aug 2012):</p>
<pre class="code control literal-block">
-<span class="err">...</span>
-<span class="k">Package</span><span class="w">: </span><span class="s">CGIwithR</span>
-<span class="k">Version</span>: <span class="m">0.73-0</span>
-<span class="k">Suggests</span><span class="w">: </span><span class="s">GDD</span>
-<span class="k">License</span><span class="w">: </span><span class="s">GPL (>= 2)</span>
-<span class="k">MD5sum</span><span class="w">: </span><span class="s">50b1f48209c9e66909c7afb3a4b8af5e</span>
-
-<span class="k">Package</span><span class="w">: </span><span class="s">CodeDepends</span>
-<span class="k">Version</span>: <span class="m">0.2-1</span>
-<span class="k">Depends</span>: <span class="nf">methods</span>
-<span class="k">Imports</span><span class="w">: </span><span class="s">codetools, XML</span>
-<span class="k">Suggests</span><span class="w">: </span><span class="s">graph, Rgraphviz</span>
-<span class="k">License</span><span class="w">: </span><span class="s">GPL</span>
-<span class="k">MD5sum</span><span class="w">: </span><span class="s">e2ec3505f9db1a96919a72f07673a2d8</span>
-<span class="err">...</span>
+<span class="error">...</span>
+<span class="keyword">Package</span><span class="whitespace">: </span><span class="literal string">CGIwithR</span>
+<span class="keyword">Version</span>: <span class="literal number">0.73-0</span>
+<span class="keyword">Suggests</span><span class="whitespace">: </span><span class="literal string">GDD</span>
+<span class="keyword">License</span><span class="whitespace">: </span><span class="literal string">GPL (>= 2)</span>
+<span class="keyword">MD5sum</span><span class="whitespace">: </span><span class="literal string">50b1f48209c9e66909c7afb3a4b8af5e</span>
+
+<span class="keyword">Package</span><span class="whitespace">: </span><span class="literal string">CodeDepends</span>
+<span class="keyword">Version</span>: <span class="literal number">0.2-1</span>
+<span class="keyword">Depends</span>: <span class="name function">methods</span>
+<span class="keyword">Imports</span><span class="whitespace">: </span><span class="literal string">codetools, XML</span>
+<span class="keyword">Suggests</span><span class="whitespace">: </span><span class="literal string">graph, Rgraphviz</span>
+<span class="keyword">License</span><span class="whitespace">: </span><span class="literal string">GPL</span>
+<span class="keyword">MD5sum</span><span class="whitespace">: </span><span class="literal string">e2ec3505f9db1a96919a72f07673a2d8</span>
+<span class="error">...</span>
</pre>
<p>An example repo config entry for omegahat:</p>
<pre class="code ini literal-block">
-<span class="k">[omegahat]</span>
-<span class="na">type</span> <span class="o">=</span> <span class="s">websync_repo</span>
-<span class="na">src_uri</span> <span class="o">=</span> <span class="s">http://www.omegahat.org/R/src/contrib</span>
-<span class="na">digest</span> <span class="o">=</span> <span class="s">md5</span>
-<span class="c">#digest = none</span>
+<span class="keyword">[omegahat]</span>
+<span class="name attribute">type</span> <span class="operator">=</span> <span class="literal string">websync_repo</span>
+<span class="name attribute">src_uri</span> <span class="operator">=</span> <span class="literal string">http://www.omegahat.org/R/src/contrib</span>
+<span class="name attribute">digest</span> <span class="operator">=</span> <span class="literal string">md5</span>
+<span class="comment">#digest = none</span>
</pre>
<p>This repo type extends the default options by:</p>
<ul class="simple">
@@ -1191,9 +1253,9 @@ http://www.omegahat.org/R/src/contrib/Aspell_0.2-0.tar.gz
<em>~/roverlay/config/http_packages.list</em>, an example entry in the repo config
file would be:</p>
<pre class="code ini literal-block">
-<span class="k">[http-packages]</span>
-<span class="na">type</span> <span class="o">=</span> <span class="s">websync_pkglist</span>
-<span class="na">pkglist</span> <span class="o">=</span> <span class="s">~/roverlay/config/http_packages.list</span>
+<span class="keyword">[http-packages]</span>
+<span class="name attribute">type</span> <span class="operator">=</span> <span class="literal string">websync_pkglist</span>
+<span class="name attribute">pkglist</span> <span class="operator">=</span> <span class="literal string">~/roverlay/config/http_packages.list</span>
</pre>
<p>This repo type extends the default options by:</p>
<ul class="simple">
@@ -1205,10 +1267,10 @@ file would be:</p>
<p>Using local package directories is possible, too.</p>
<p>Example:</p>
<pre class="code ini literal-block">
-<span class="k">[local-packages]</span>
-<span class="na">type</span> <span class="o">=</span> <span class="s">local</span>
-<span class="na">directory</span> <span class="o">=</span> <span class="s">/var/local/R-packages</span>
-<span class="na">src_uri</span> <span class="o">=</span> <span class="s">http://localhost/R-packages</span>
+<span class="keyword">[local-packages]</span>
+<span class="name attribute">type</span> <span class="operator">=</span> <span class="literal string">local</span>
+<span class="name attribute">directory</span> <span class="operator">=</span> <span class="literal string">/var/local/R-packages</span>
+<span class="name attribute">src_uri</span> <span class="operator">=</span> <span class="literal string">http://localhost/R-packages</span>
</pre>
<p>This will use all packages from <em>/var/local/R-packages</em> and assumes
that they are available via <em>http://localhost/R-packages</em>.</p>
@@ -1477,8 +1539,370 @@ as <em>sci-R/zoo</em>. This rule can be written as a single word, <em>zoo</em>.<
</div>
</div>
</div>
+<div class="section" id="package-rules">
+<h1><a class="toc-backref" href="#contents">7 Package Rules</a></h1>
+<p>Package Rules can be used to control both overlay and ebuild creation.
+Each package rule consists of conditions, e.g. <em>package name contains amd64</em>,
+and actions, e.g. <em>set KEYWORDS="-x86 amd64"</em>.
+The actions of a rule will only be applied if a package meets all conditions,
+otherwise the rule does nothing.
+Moreover, rules can contain further rules which will only take effect if all
+enclosing rules match a given package.</p>
+<div class="section" id="package-rule-file-syntax">
+<h2><a class="toc-backref" href="#contents">7.1 Package Rule File Syntax</a></h2>
+<p>As stated above, each rule has two parts, a <em>match block</em> that lists the
+rule's conditions and an <em>action block</em> that defines which actions and
+nested rules are applied to a package if the rule matches it, i.e. if all
+conditions are met.</p>
+<p>A rule file contains zero or more package rules.
+Each rule has to declare one <em>match</em> and one <em>action statement</em> at least.
+The basic syntax for a rule with 1..m <em>match</em> and 1..n <em>action statements</em> is</p>
+<pre class="code literal-block">
+MATCH:
+ <match statement 1>
+ <match statement 2>
+ ...
+ <match statement m>
+ACTION:
+ <action statement 1>
+ <action statement 2>
+ ...
+ <action statement n>
+END;
+</pre>
+<p>A rule is introduced by the <tt class="docutils literal">MATCH:</tt> keyword, which starts the
+<em>match block</em> and is followed by one or more <em>match statements</em>, one per line.
+The <em>match block</em> ends with the <tt class="docutils literal">ACTION:</tt> keyword, which also starts the
+<em>action block</em> and is followed by one or more <em>action statements</em>
+(again, one per line). Finally, the rule is terminated by the <tt class="docutils literal">END;</tt> keyword.</p>
+<p>Indention is purely optional, leading and ending whitespace will be discarded.
+Lines starting with <tt class="docutils literal">#</tt> or <tt class="docutils literal">;</tt> are considered to be comments and will be
+ignored.</p>
+<div class="section" id="match-blocks">
+<h3><a class="toc-backref" href="#contents">7.1.1 Match Blocks</a></h3>
+<p>The <em>match block</em> lists one or more conditions, which all must evaluate to
+<em>true</em> for a certain package, otherwise no actions will be applied.
+There are two types of conditions, <em>trivial</em> conditions,
+e.g. <em>always true/false</em> or <em>random - flip a coin</em>, and <em>non-trivial</em> ones
+that depend on the information a package has, e.g. its repository or name.</p>
+<p>Only <em>non-trivial</em> conditions can be defined in <em>match statements</em>.
+The consist of a <strong>match keyword</strong> that defines <em>what</em> should be matched, an
+<strong>accepted value</strong> to compare against and an <strong>operator</strong> that defines the
+relation <em>accepted value - package's information</em>, i.e. <em>how</em> to compare.
+The operator can be omitted, in which case it is determined by the
+<em>match keyword</em>.</p>
+<p>The <em>match statement</em> syntax is</p>
+<pre class="code literal-block">
+<match keyword> [<operator>] <accepted value>
+</pre>
+<p>These <em>match keywords</em> are recognized:</p>
+<table border="1" class="docutils">
+<caption>match statement keywords</caption>
+<colgroup>
+<col width="21%" />
+<col width="25%" />
+<col width="54%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">match keyword</th>
+<th class="head">default operator</th>
+<th class="head">matches</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>repo</td>
+<td>nocase-string</td>
+<td><em>alias to repo_name</em></td>
+</tr>
+<tr><td>repo_name</td>
+<td>nocase-string</td>
+<td>name of the repo, e.g. <em>CRAN</em></td>
+</tr>
+<tr><td>package</td>
+<td><em>implicit</em></td>
+<td>package file name with version
+but without the file extension, e.g.
+<em>rpart.plot_1.3-0</em></td>
+</tr>
+<tr><td>package_name</td>
+<td><em>implicit</em></td>
+<td>package file name without version
+and file extension, e.g. <em>seewave</em></td>
+</tr>
+<tr><td>name</td>
+<td><em>implicit</em></td>
+<td><em>alias to package_name</em></td>
+</tr>
+</tbody>
+</table>
+<p>Note the <strong>implicit operator</strong>. It will be used whenever no explicit operator
+has been specified in the match statement and the match keyword does not
+define a default one. Four explicit operators are available:</p>
+<table border="1" class="docutils">
+<caption>match statement operators</caption>
+<colgroup>
+<col width="21%" />
+<col width="18%" />
+<col width="61%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">operator name</th>
+<th class="head">operator(s)</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>exact-string</td>
+<td>== =</td>
+<td>exact string match</td>
+</tr>
+<tr><td>nocase-string</td>
+<td>,= =,</td>
+<td>case-insensitive string match</td>
+</tr>
+<tr><td>exact-regex</td>
+<td>~= =~</td>
+<td>exact regex match <em>^<expression>$</em></td>
+</tr>
+<tr><td>regex</td>
+<td>~~ ~</td>
+<td>partial regex match</td>
+</tr>
+<tr><td><em>implicit</em></td>
+<td><em>none</em></td>
+<td><em>exact-regex</em> operator if <em>accepted value</em>
+has any wildcard characters (?, *), else
+<em>exact-string</em>. Wildcard chars will
+be replaced with their regex equivalents.</td>
+</tr>
+</tbody>
+</table>
+<p>The <em>accepted value</em> is a simple string or a regular expression,
+which depends on the operator.</p>
+<div class="section" id="extended-match-block-syntax">
+<h4><a class="toc-backref" href="#contents">7.1.1.1 Extended Match Block Syntax</a></h4>
+<p>Sometimes, a rule should apply its actions to a package if it matches <em>any</em>
+condition, e.g. <em>package from CRAN or BIOC</em>, or if it does not match a certain
+condition, e.g. <em>package not from BIOC/experiment</em>.</p>
+<p>This is supported by special <em>match keywords</em> that represent
+<em>boolean functions</em>. Such a <em>match statement</em> is introduced by the keyword,
+followed by one or more <em>match statements</em> that are indented by one asterisk
+<tt class="docutils literal">*</tt> or dash <tt class="docutils literal">-</tt> character for each <em>boolean function</em> that is currently
+active. These characters are important and indicate the <em>match depth</em>.
+A depth of 0 means that no function is active.</p>
+<p>Syntax Example:</p>
+<pre class="code literal-block">
+MATCH:
+ <match statement 1, match depth 0>
+ ...
+ <boolean function>
+ * <match statement 1, match depth 1>
+ * <match statement 2, match depth 1>
+ * ...
+ * <match statement m, match depth 1>
+ ...
+ <match statement n, match depth 0>
+ACTION:
+ ...
+END;
+</pre>
+<p>For reference, the following table lists the <em>boolean functions</em> available,
+their <em>match keywords</em> and their meaning:</p>
+<table border="1" class="docutils">
+<caption>boolean functions</caption>
+<colgroup>
+<col width="25%" />
+<col width="18%" />
+<col width="56%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">boolean function</th>
+<th class="head">match
+keyword(s)</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>AND</td>
+<td>and all &&</td>
+<td>all listed conditions must match</td>
+</tr>
+<tr><td>OR</td>
+<td>or ||</td>
+<td>any
+of the listed conditions must match</td>
+</tr>
+<tr><td>XOR1</td>
+<td>xor1 xor ^^</td>
+<td>exactly one
+of the listed conditions must match</td>
+</tr>
+<tr><td>NOR</td>
+<td>nor none</td>
+<td>none
+of the listed conditions must match</td>
+</tr>
+</tbody>
+</table>
+<p>In other words, a (boolean) match keyword starts a <em>nested match block</em>
+at any position in the current one and increases the <em>match depth</em> by one.
+The nested block is terminated by indenting out, i.e. decreasing the
+<em>match depth</em> by one. The (extended) match statement syntax then becomes:</p>
+<pre class="code literal-block">
+<'*'^<match_depth>> <(basic) match statement>
+</pre>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>The extended match statement syntax does not support boolean functions
+with a fixed number of conditions, e.g. 1. This is why there is no
+<em>NOT</em> function. The definition for more than one condition would be
+ambiguous, either <em>NOR</em> or <em>NAND</em>.</p>
+<p class="last">Correspondingly, the logic for the top-level match block is <em>AND</em> by
+convention.</p>
+</div>
+<p>Using this syntax, match blocks can be nested indefinitely (minus technical
+limitations):</p>
+<pre class="code literal-block">
+MATCH:
+ <match statement 1, depth 0>
+ <boolean function 2, depth 0>
+ * <match statement 1, depth 1>
+ * <match statement 2, depth 1>
+ * ...
+ * <match statement k-1, depth 1>
+ * <boolean function k, depth 1>
+ ** <match statement 1, depth 2>
+ ** ...
+ ** <match statement o, depth 2>
+ * <match statement k+1, depth 1>
+ * ...
+ * <match statement m, depth 1>
+ ...
+ <match statement n, depth 0>
+ACTION:
+ ...
+END;
+</pre>
+</div>
+</div>
+<div class="section" id="action-blocks">
+<h3><a class="toc-backref" href="#contents">7.1.2 Action Blocks</a></h3>
+<p>The action block syntax is quite simple. Each <em>action statement</em> starts
+with an <em>action keyword</em>, optionally followed by one or more <em>values</em>.</p>
+<p>Action statement syntax:</p>
+<pre class="code literal-block">
+<action keyword> [<value>]*
+</pre>
+<p>The value(s) can be enclosed by quotation characters (<tt class="docutils literal">"</tt>, <tt class="docutils literal">'</tt>).</p>
+<p>The following table lists all <em>action keywords</em>, their impact (<em>what</em> they
+control <em>where</em>) and the number of values they accept:</p>
+<table border="1" class="docutils">
+<caption>action keywords</caption>
+<colgroup>
+<col width="23%" />
+<col width="25%" />
+<col width="18%" />
+<col width="34%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">action keyword</th>
+<th class="head">affects</th>
+<th class="head"># of values</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>ignore</td>
+<td rowspan="2">overlay creation</td>
+<td rowspan="2">none</td>
+<td rowspan="2">ignore package,
+do not try to create
+an ebuild for it</td>
+</tr>
+<tr><td>do-not-process</td>
+</tr>
+<tr><td>keywords</td>
+<td>ebuild variables</td>
+<td>>= 1</td>
+<td>set per-package
+<tt class="docutils literal">KEYWORDS</tt></td>
+</tr>
+</tbody>
+</table>
+<div class="section" id="extended-action-block-syntax">
+<h4><a class="toc-backref" href="#contents">7.1.2.1 Extended Action Block Syntax</a></h4>
+<p>A mentioned before, action blocks can contain <em>nested rules</em>. The syntax
+is exactly the same as for the normal package rules:</p>
+<pre class="code literal-block">
+MATCH:
+ # top-level rule, match block
+ ...
+ACTION:
+ # top-level rule, action block
+ ...
+ MATCH:
+ # nested rule, match block
+ ...
+ ACTION:
+ # nested rule, action block
+ ...
+ END;
+ # top-level rule, action block continues
+ ...
+END;
+</pre>
+<p>Rules can be nested indefinitely, whitespace indention is optional.
+A <em>nested rule</em> only becomes active, i.e. tries to match a package, if its
+enclosing rule already matched it. This can be used to reduce the number of
+checks necessary for a given package.</p>
+</div>
+</div>
+<div class="section" id="package-rule-examples">
+<h3><a class="toc-backref" href="#contents">7.1.3 Package Rule Examples</a></h3>
+<p>A rule that ignores the 'yaqcaffy' package from CRAN, which is also available
+from BIOC:</p>
+<pre class="code literal-block">
+MATCH:
+ repo == CRAN
+ package_name == yaqcaffy
+ACTION:
+ do-not-process
+END;
+</pre>
+<p>A more complex example that sets the <tt class="docutils literal">KEYWORDS</tt> ebuild variable for
+all packages whose name contains <em>amd64</em> or <em>x86_64</em> to <tt class="docutils literal"><span class="pre">-x86</span> ~amd64</tt>
+if the package is from BIOC/experiment, and otherwise to <tt class="docutils literal"><span class="pre">-x86</span> amd64</tt>:</p>
+<pre class="code literal-block">
+MATCH:
+ or
+ * package_name ~ x86_64
+ * package_name ~ amd64
+ACTION:
+ MATCH:
+ NOR
+ * repo == BIOC/experiment
+ ACTION:
+ keywords "-x86 amd64"
+ END;
+ MATCH:
+ repo == BIOC/experiment
+ ACTION:
+ keywords "-x86 ~amd64"
+ END;
+END;
+</pre>
+<div class="caution">
+<p class="first admonition-title">Caution!</p>
+<p class="last">Applying the same action more than once per package is not supported.
+That is why the example above uses another nested rule with a <em>NOR</em>-match
+instead of simply specifying the desired action.
+This limitation will be removed soon.</p>
+</div>
+</div>
+</div>
+</div>
<div class="section" id="configuration-reference">
-<h1><a class="toc-backref" href="#contents">7 Configuration Reference</a></h1>
+<h1><a class="toc-backref" href="#contents">8 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.
@@ -1531,7 +1955,7 @@ 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">7.1 misc options</a></h2>
+<h2><a class="toc-backref" href="#contents">8.1 misc options</a></h2>
<dl class="docutils" id="distfiles">
<dt>DISTFILES</dt>
<dd>Alias to <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
@@ -1565,7 +1989,19 @@ 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">7.2 overlay options</a></h2>
+<h2><a class="toc-backref" href="#contents">8.2 overlay options</a></h2>
+<dl class="docutils" id="distdir">
+<dt>DISTDIR</dt>
+<dd>Alias to <a class="reference internal" href="#overlay-distdir-root">OVERLAY_DISTDIR_ROOT</a>.</dd>
+</dl>
+<dl class="docutils" id="distdir-flat">
+<dt>DISTDIR_FLAT</dt>
+<dd>Alias to <a class="reference internal" href="#overlay-distdir-flat">OVERLAY_DISTDIR_FLAT</a>.</dd>
+</dl>
+<dl class="docutils" id="distdir-strategy">
+<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="eclass">
<dt>ECLASS</dt>
<dd>Alias to <a class="reference internal" href="#overlay-eclass">OVERLAY_ECLASS</a>.</dd>
@@ -1587,6 +2023,69 @@ for this option, but values with a slash <em>/</em> lead to errors.</p>
<p class="last">This option is <strong>required</strong>.</p>
</dd>
</dl>
+<dl class="docutils" id="overlay-distdir-flat">
+<dt>OVERLAY_DISTDIR_FLAT</dt>
+<dd><p class="first">A <em>bool</em> that controls the overall layout of _OVERLAY_DISTDIR_ROOT.</p>
+<p>A flat distdir is a single directory with all package files or package
+file links in it. A nested distdir contains per-package directories.</p>
+<p class="last">Defaults to <em>true</em>.
+This option has no effect if the distdir strategy is <em>tmpdir</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="overlay-distdir-root">
+<dt>OVERLAY_DISTDIR_ROOT</dt>
+<dd><p class="first">Sets the DISTDIR root directory. It is used for Manifest file
+creation, but can serve as package mirror directory as well.</p>
+<p>The actual appearance of this directory is up to the distdir strategy
+(<a class="reference internal" href="#overlay-distdir-strategy">OVERLAY_DISTDIR_STRATEGY</a>) and <a class="reference internal" href="#overlay-distdir-flat">OVERLAY_DISTDIR_FLAT</a>.
+Basically, it contains all package files that have a valid ebuild.</p>
+<div class="note last">
+<p class="first admonition-title">Note</p>
+<p class="last">This directory will not be cleaned up, only broken symbolic links
+will be removed. On the one hand, it is absolutely guaranteed that
+package files will not disappear unless replaced by a new file with
+the same name, but on the other hand, the directory may get bloated
+over time.</p>
+</div>
+</dd>
+</dl>
+<dl class="docutils" id="overlay-distdir-strategy">
+<dt>OVERLAY_DISTDIR_STRATEGY</dt>
+<dd><p class="first">The distdir strategy defines <em>how</em> package files are created.
+It is a list of methods that will be tried in the specified order, until
+the first one succeeds.</p>
+<table border="1" class="docutils">
+<caption>distdir creation methods</caption>
+<colgroup>
+<col width="14%" />
+<col width="86%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">method</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>symlink</td>
+<td>use symbolic links</td>
+</tr>
+<tr><td>hardlink</td>
+<td>use hard links</td>
+</tr>
+<tr><td>copy</td>
+<td>copy package files
+Obviously, this will need much more disk space.</td>
+</tr>
+<tr><td>tmpdir</td>
+<td>use a temporary DISTDIR that will be deleted at exit.
+This method is not compatible with any of the above.</td>
+</tr>
+</tbody>
+</table>
+<p class="last">This option is <strong>required</strong>, but has a reasonable value in the default
+config file, "hardlink symlink".</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
@@ -1608,9 +2107,11 @@ per R package. All others will be removed.</p>
</dl>
<dl class="docutils" id="overlay-manifest-implementation">
<dt>OVERLAY_MANIFEST_IMPLEMENTATION</dt>
-<dd><p class="first">Sets the implementation to use for Manifest file writing.
-Available choices are 'external:ebuild', 'default' and 'none'.
-Defaults to 'default'.</p>
+<dd><p class="first">Sets the implementation that will be used for Manifest file writing.
+Available choices are <em>ebuild</em>, <em>portage</em>, <em>default</em> and <em>none</em>.
+Defaults to <em>default</em> (-> <em>ebuild</em>).
+<em>portage</em> is highly experimental and therefore not recommended
+for production usage.</p>
<div class="note last">
<p class="first admonition-title">Note</p>
<p class="last">Choosing 'none' is destructive - <em>roverlay</em> will fail to function
@@ -1630,11 +2131,11 @@ writing.</p>
</dl>
</div>
<div class="section" id="other-config-files">
-<h2><a class="toc-backref" href="#contents">7.3 other config files</a></h2>
+<h2><a class="toc-backref" href="#contents">8.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">
-<li>no need for modification in most cases, e.g. the <a class="reference internal" href="#id2">field definition</a> file</li>
+<li>no need for modification in most cases, e.g. the <a class="reference internal" href="#id3">field definition</a> file</li>
<li>special syntax that is not compatible with the main config file,
e.g. the <a class="reference internal" href="#dependency-rule-file-syntax">dependency rule file syntax</a></li>
</ul>
@@ -1652,6 +2153,15 @@ of R packages is read.</p>
<dd>Alias to <a class="reference internal" href="#field-definition">FIELD_DEFINITION</a>.</dd>
</dl>
<dl class="docutils" id="id1">
+<dt>PACKAGE_RULES</dt>
+<dd>Alias to <a class="reference internal" href="#package-rule-files">PACKAGE_RULE_FILES</a>.</dd>
+</dl>
+<dl class="docutils" id="package-rule-files">
+<dt>PACKAGE_RULE_FILES</dt>
+<dd>A list of files and directories with package rules.
+Directories will be recursively scanned for rule files.</dd>
+</dl>
+<dl class="docutils" id="id2">
<dt>REPO_CONFIG</dt>
<dd><p class="first">A list of one or more repo config files.</p>
<p class="last">This option is <strong>required</strong>.</p>
@@ -1659,11 +2169,11 @@ of R packages is read.</p>
</dl>
<dl class="docutils" id="repo-config-file">
<dt>REPO_CONFIG_FILE</dt>
-<dd>Alias to <a class="reference internal" href="#id1">REPO_CONFIG</a>.</dd>
+<dd>Alias to <a class="reference internal" href="#id2">REPO_CONFIG</a>.</dd>
</dl>
<dl class="docutils" id="repo-config-files">
<dt>REPO_CONFIG_FILES</dt>
-<dd>Alias to <a class="reference internal" href="#id1">REPO_CONFIG</a>.</dd>
+<dd>Alias to <a class="reference internal" href="#id2">REPO_CONFIG</a>.</dd>
</dl>
<dl class="docutils" id="simple-rules-file">
<dt>SIMPLE_RULES_FILE</dt>
@@ -1679,7 +2189,7 @@ much without dependency resolution.</p>
</dl>
</div>
<div class="section" id="logging">
-<h2><a class="toc-backref" href="#contents">7.4 logging</a></h2>
+<h2><a class="toc-backref" href="#contents">8.4 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>
@@ -1704,7 +2214,7 @@ have their own log level.</p>
</dd>
</dl>
<div class="section" id="console-logging">
-<h3><a class="toc-backref" href="#contents">7.4.1 console logging</a></h3>
+<h3><a class="toc-backref" href="#contents">8.4.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>
@@ -1725,7 +2235,7 @@ have their own log level.</p>
</dl>
</div>
<div class="section" id="file-logging">
-<h3><a class="toc-backref" href="#contents">7.4.2 file logging</a></h3>
+<h3><a class="toc-backref" href="#contents">8.4.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
@@ -1784,7 +2294,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">7.5 options for debugging, manual dependency rule creation and testing</a></h2>
+<h2><a class="toc-backref" href="#contents">8.5 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
@@ -1803,7 +2313,7 @@ on <em>roverlay</em> exit. Primarily useful for creating new rules.</p>
</div>
</div>
<div class="section" id="field-definition-config">
-<span id="id2"></span><h1><a class="toc-backref" href="#contents">8 Field Definition Config</a></h1>
+<span id="id3"></span><h1><a class="toc-backref" href="#contents">9 Field Definition Config</a></h1>
<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>
@@ -1885,43 +2395,43 @@ 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><h2><a class="toc-backref" href="#contents">8.1 Example: The default field definition file</a></h2>
+<span id="default-field-definition-file"></span><h2><a class="toc-backref" href="#contents">9.1 Example: The default field definition file</a></h2>
<p>This is the default field definition file (without any ignored fields):</p>
<pre class="code ini literal-block">
-<span class="k">[Description]</span>
-<span class="err">joinValues</span>
+<span class="keyword">[Description]</span>
+<span class="error">joinValues</span>
-<span class="k">[Title]</span>
-<span class="err">joinValues</span>
+<span class="keyword">[Title]</span>
+<span class="error">joinValues</span>
-<span class="k">[Suggests]</span>
-<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">Suggests, Suggest, %Suggests, Suggets, Recommends</span>
-<span class="err">isList</span>
+<span class="keyword">[Suggests]</span>
+<span class="name attribute">alias_nocase</span> <span class="operator">=</span> <span class="literal string">Suggests, Suggest, %Suggests, Suggets, Recommends</span>
+<span class="error">isList</span>
-<span class="k">[Depends]</span>
-<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">Depends, Dependencies, Dependes, %Depends, Depents, Require, Requires</span>
-<span class="err">isList</span>
+<span class="keyword">[Depends]</span>
+<span class="name attribute">alias_nocase</span> <span class="operator">=</span> <span class="literal string">Depends, Dependencies, Dependes, %Depends, Depents, Require, Requires</span>
+<span class="error">isList</span>
-<span class="k">[Imports]</span>
-<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">Imports, Import</span>
-<span class="err">isList</span>
+<span class="keyword">[Imports]</span>
+<span class="name attribute">alias_nocase</span> <span class="operator">=</span> <span class="literal string">Imports, Import</span>
+<span class="error">isList</span>
-<span class="k">[LinkingTo]</span>
-<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">LinkingTo, LinkingdTo, LinkinTo</span>
-<span class="err">isList</span>
+<span class="keyword">[LinkingTo]</span>
+<span class="name attribute">alias_nocase</span> <span class="operator">=</span> <span class="literal string">LinkingTo, LinkingdTo, LinkinTo</span>
+<span class="error">isList</span>
-<span class="k">[SystemRequirements]</span>
-<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">SystemRequirements, SystemRequirement</span>
-<span class="err">isList</span>
+<span class="keyword">[SystemRequirements]</span>
+<span class="name attribute">alias_nocase</span> <span class="operator">=</span> <span class="literal string">SystemRequirements, SystemRequirement</span>
+<span class="error">isList</span>
-<span class="k">[OS_Type]</span>
-<span class="na">alias_nocase</span> <span class="o">=</span> <span class="s">OS_TYPE</span>
-<span class="na">allowed_values</span> <span class="o">=</span> <span class="s">unix</span>
+<span class="keyword">[OS_Type]</span>
+<span class="name attribute">alias_nocase</span> <span class="operator">=</span> <span class="literal string">OS_TYPE</span>
+<span class="name attribute">allowed_values</span> <span class="operator">=</span> <span class="literal string">unix</span>
</pre>
</div>
</div>
<div class="section" id="dependency-resolution-console">
-<span id="depres-console"></span><h1><a class="toc-backref" href="#contents">9 Dependency Resolution Console</a></h1>
+<span id="depres-console"></span><h1><a class="toc-backref" href="#contents">10 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">
@@ -2079,13 +2589,13 @@ cmd % exit
</dl>
</div>
<div class="section" id="implementation-overview">
-<h1><a class="toc-backref" href="#contents">10 Implementation Overview</a></h1>
+<h1><a class="toc-backref" href="#contents">11 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">10.1 PackageInfo</a></h2>
+<h2><a class="toc-backref" href="#contents">11.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>
@@ -2106,7 +2616,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">10.2 Repository Management</a></h2>
+<h2><a class="toc-backref" href="#contents">11.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>
@@ -2116,8 +2626,8 @@ functionality:</p>
<li><em>sync</em> all repos and <em>nosync</em> all repos (offline mode)</li>
<li>create <em>PackageInfo</em> instances for R packages from all repositories</li>
</ul>
-<div class="section" id="id3">
-<h3><a class="toc-backref" href="#contents">10.2.1 Repositories</a></h3>
+<div class="section" id="id4">
+<h3><a class="toc-backref" href="#contents">11.2.1 Repositories</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,
@@ -2158,7 +2668,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">10.2.1.1 Adding new repository types</a></h4>
+<h4><a class="toc-backref" href="#contents">11.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.
@@ -2245,7 +2755,7 @@ to be accessible.</p>
</div>
</div>
<div class="section" id="overlay">
-<h2><a class="toc-backref" href="#contents">10.3 Overlay</a></h2>
+<h2><a class="toc-backref" href="#contents">11.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>
@@ -2276,7 +2786,7 @@ level</p>
</li>
</ul>
<div class="section" id="metadata-creation">
-<h3><a class="toc-backref" href="#contents">10.3.1 Metadata Creation</a></h3>
+<h3><a class="toc-backref" href="#contents">11.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
@@ -2285,7 +2795,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">10.3.2 Manifest Creation</a></h3>
+<h3><a class="toc-backref" href="#contents">11.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
@@ -2294,7 +2804,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">10.4 Ebuild Creation</a></h2>
+<h2><a class="toc-backref" href="#contents">11.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>
@@ -2308,11 +2818,12 @@ Otherwise <strong>ebuild creation stops</strong> and <em>p</em> is marked as
<em>ebuild uncreatable</em>. The overlay creation may decide to remove <em>p</em> in
order to save memory etc.</li>
<li>The <em>DESCRIPTION</em> and <em>SRC_URI</em> variables are created</li>
+<li>Add any ebuild variables created by package rules, e.g. <em>KEYWORDS</em></li>
<li><strong>done</strong> - Generate the ebuild as text, add it to <em>p</em> and mark <em>p</em>
as <em>ebuild successfully created</em></li>
</ol>
<div class="section" id="ebuild-variables">
-<h3><a class="toc-backref" href="#contents">10.4.1 Ebuild Variables</a></h3>
+<h3><a class="toc-backref" href="#contents">11.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
@@ -2320,11 +2831,12 @@ 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">10.5 Overlay Creation</a></h2>
+<h2><a class="toc-backref" href="#contents">11.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.
-It accepts <em>PackageInfo</em> objects as input, tries to reserve a slot in the
+It accepts <em>PackageInfo</em> objects as input, applies package rules to them,
+which possibly filters some packages out, tries to reserve a slot in the
overlay for them, and, if successful, adds them to the work queue.</p>
<p>The work queue is processed by <em>OverlayWorkers</em> that run ebuild creation
for a <em>PackageInfo</em> object and inform the <em>OverlayCreation</em> about the result
@@ -2333,7 +2845,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">10.6 Dependency Resolution</a></h2>
+<h2><a class="toc-backref" href="#contents">11.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
@@ -2355,7 +2867,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">10.6.1 Dependency types</a></h3>
+<h3><a class="toc-backref" href="#contents">11.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">
@@ -2377,14 +2889,14 @@ dependencies as system dependencies and vice versa. Throughout this
document, such property is indicated by <em>TRY_OTHER</em> and
<em><preferred dependency type> first</em>, e.g. <em>package first</em>.</dd>
</dl>
-<p><em>Mandatory</em> and <em>Option</em> are mutually exclusive.</p>
+<p><em>Mandatory</em> and <em>Optional</em> are mutually exclusive.</p>
<p>The <em>dependency type</em> of a <em>dependency string</em> is determined by its origin,
i.e. info field in the package's DESCRIPTION file.
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">10.6.1.1 DESCRIPTION file dependency fields</a></h4>
+<h4><a class="toc-backref" href="#contents">11.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>
@@ -2443,7 +2955,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">10.6.2 Dependency Environments</a></h3>
+<h3><a class="toc-backref" href="#contents">11.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
@@ -2453,7 +2965,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">10.6.3 EbuildJob Channel</a></h3>
+<h3><a class="toc-backref" href="#contents">11.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>
@@ -2490,7 +3002,7 @@ dependencies are unresolvable.</li>
</ol>
</div>
<div class="section" id="dependency-rule-pools">
-<h3><a class="toc-backref" href="#contents">10.6.4 Dependency Rule Pools</a></h3>
+<h3><a class="toc-backref" href="#contents">11.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>
@@ -2513,7 +3025,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">10.6.5 Dependency Resolver Modules</a></h3>
+<h3><a class="toc-backref" href="#contents">11.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">
@@ -2533,7 +3045,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">10.6.6 Dependency Resolver</a></h3>
+<h3><a class="toc-backref" href="#contents">11.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
@@ -2591,7 +3103,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-01-09.
+Generated on: 2013-03-05.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-04-25 16:44 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-04-25 16:44 UTC (permalink / raw
To: gentoo-commits
commit: 988507522a444647348de69c8b5b7dc31980afcc
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Apr 23 09:36:08 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Apr 23 09:36:08 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=98850752
doc/html: package rules
See previous commit for details.
---
doc/html/usage.html | 47 ++++++++++++++++++++++++++++++-----------------
1 files changed, 30 insertions(+), 17 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index d216676..62e4e9a 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -470,13 +470,13 @@ e.g. configure which R packages will be part of the generated overlay</p>
namely <a class="reference internal" href="#repositories-getting-packages">Repositories / Getting Packages</a>, <a class="reference internal" href="#dependency-rules">Dependency Rules</a>,
<a class="reference internal" href="#configuration-reference">Configuration Reference</a> and <a class="reference internal" href="#field-definition-config">Field Definition Config</a>.</p>
<p>There is another chapter that is only interesting for testing, the
-<a class="reference internal" href="#dependency-resolution-console">Dependency Resolution Console</a> (9), which can be used to interactively
+<a class="reference internal" href="#dependency-resolution-console">Dependency Resolution Console</a> (10), which can be used to interactively
test dependency rules.</p>
</li>
<li><p class="first"><em>roverlay</em> code maintainers who want to know <strong>how roverlay works</strong> for
code improvements etc.</p>
-<p>The most important chapter is <a class="reference internal" href="#implementation-overview">Implementation Overview</a> (10) which has
-references to other chapters (4-8) where required.</p>
+<p>The most important chapter is <a class="reference internal" href="#implementation-overview">Implementation Overview</a> (11) which has
+references to other chapters (4-9) where required.</p>
</li>
</ul>
</blockquote>
@@ -859,6 +859,13 @@ and resolving dependencies.</p>
<p>Meant for <strong>testing only</strong>.</p>
<p class="last">More information can be found in the <a class="reference internal" href="#depres-console">DepRes Console</a> section.</p>
</dd>
+<dt>apply_rules</dt>
+<dd><p class="first">Applies the package rules to all available packages and reports what has
+been done, either to stdout or to <tt class="docutils literal"><span class="pre">--dump-file</span> <file></tt>.</p>
+<p>Meant for testing.</p>
+<p class="last">This command implies the <strong>sync</strong> command unless the <em>--nosync</em> option
+is specified.</p>
+</dd>
</dl>
</div>
<div class="section" id="providing-a-package-mirror">
@@ -1827,8 +1834,26 @@ an ebuild for it</td>
<td>set per-package
<tt class="docutils literal">KEYWORDS</tt></td>
</tr>
+<tr><td rowspan="2">trace</td>
+<td rowspan="2">package rules</td>
+<td>none</td>
+<td>marks a package as
+modified</td>
+</tr>
+<tr><td>1</td>
+<td>adds the stored string
+to a package's
+<em>modified</em> variable
+whenever this action
+is applied</td>
+</tr>
</tbody>
</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">Applying the same (non-incremental) ebuild variable action more than once
+is possible, but only the last one will have an effect on ebuild creation.</p>
+</div>
<div class="section" id="extended-action-block-syntax">
<h4><a class="toc-backref" href="#contents">7.1.2.1 Extended Action Block Syntax</a></h4>
<p>A mentioned before, action blocks can contain <em>nested rules</em>. The syntax
@@ -1878,12 +1903,7 @@ MATCH:
* package_name ~ x86_64
* package_name ~ amd64
ACTION:
- MATCH:
- NOR
- * repo == BIOC/experiment
- ACTION:
- keywords "-x86 amd64"
- END;
+ keywords "-x86 amd64"
MATCH:
repo == BIOC/experiment
ACTION:
@@ -1891,13 +1911,6 @@ ACTION:
END;
END;
</pre>
-<div class="caution">
-<p class="first admonition-title">Caution!</p>
-<p class="last">Applying the same action more than once per package is not supported.
-That is why the example above uses another nested rule with a <em>NOR</em>-match
-instead of simply specifying the desired action.
-This limitation will be removed soon.</p>
-</div>
</div>
</div>
</div>
@@ -3103,7 +3116,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-03-05.
+Generated on: 2013-04-23.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
2013-06-05 18:08 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
@ 2013-06-13 16:34 ` André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-06-13 16:34 UTC (permalink / raw
To: gentoo-commits
commit: e1d57a113226f2a8147ebdd26d47e3224bda4179
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jun 5 18:05:51 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jun 5 18:05:51 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=e1d57a11
doc/html, package rules: set/rename actions
---
doc/html/usage.html | 263 +++++++++++++++++++++++++++++++++++++---------------
1 file changed, 188 insertions(+), 75 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 62e4e9a..a02a772 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -329,111 +329,111 @@ ul.auto-toc {
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#introduction" id="id5">1 Introduction</a></li>
-<li><a class="reference internal" href="#installation" id="id6">2 Installation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#prerequisites" id="id7">2.1 Prerequisites</a></li>
-<li><a class="reference internal" href="#via-emerge-gentoo" id="id8">2.2 via emerge (Gentoo)</a></li>
-<li><a class="reference internal" href="#manual-installation" id="id9">2.3 Manual Installation</a></li>
-<li><a class="reference internal" href="#using-roverlay-without-installation" id="id10">2.4 Using <em>roverlay</em> without installation</a></li>
+<li><a class="reference internal" href="#introduction" id="id4">1 Introduction</a></li>
+<li><a class="reference internal" href="#installation" id="id5">2 Installation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#prerequisites" id="id6">2.1 Prerequisites</a></li>
+<li><a class="reference internal" href="#via-emerge-gentoo" id="id7">2.2 via emerge (Gentoo)</a></li>
+<li><a class="reference internal" href="#manual-installation" id="id8">2.3 Manual Installation</a></li>
+<li><a class="reference internal" href="#using-roverlay-without-installation" id="id9">2.4 Using <em>roverlay</em> without installation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-roverlay" id="id11">3 Running Roverlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#required-configuration-steps" id="id12">3.1 Required configuration steps</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id13">3.1.1 Extended Configuration / Where to go from here?</a></li>
+<li><a class="reference internal" href="#running-roverlay" id="id10">3 Running Roverlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#required-configuration-steps" id="id11">3.1 Required configuration steps</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id12">3.1.1 Extended Configuration / Where to go from here?</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-it" id="id14">3.2 Running it</a></li>
-<li><a class="reference internal" href="#providing-a-package-mirror" id="id15">3.3 Providing a package mirror</a></li>
+<li><a class="reference internal" href="#running-it" id="id13">3.2 Running it</a></li>
+<li><a class="reference internal" href="#providing-a-package-mirror" id="id14">3.3 Providing a package mirror</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#basic-implementation-overview" id="id16">4 Basic Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-roverlay-works" id="id17">4.1 How <em>roverlay</em> works</a></li>
-<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id18">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#expected-ebuild-result" id="id19">4.2.1 Expected Ebuild Result</a></li>
-<li><a class="reference internal" href="#expected-metadata-xml-result" id="id20">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
+<li><a class="reference internal" href="#basic-implementation-overview" id="id15">4 Basic Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#how-roverlay-works" id="id16">4.1 How <em>roverlay</em> works</a></li>
+<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id17">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#expected-ebuild-result" id="id18">4.2.1 Expected Ebuild Result</a></li>
+<li><a class="reference internal" href="#expected-metadata-xml-result" id="id19">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#repositories-getting-packages" id="id21">5 Repositories / Getting Packages</a><ul class="auto-toc">
-<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id22">5.1 A word about repo config files</a></li>
-<li><a class="reference internal" href="#rsync-repos" id="id23">5.2 Rsync repos</a></li>
-<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="#repositories-getting-packages" id="id20">5 Repositories / Getting Packages</a><ul class="auto-toc">
+<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id21">5.1 A word about repo config files</a></li>
+<li><a class="reference internal" href="#rsync-repos" id="id22">5.2 Rsync repos</a></li>
+<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id23">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="id24">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="id25">5.5 Using local directories</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-rules" id="id27">6 Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#simple-dependency-rules" id="id28">6.1 Simple Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#rule-variants" id="id29">6.1.1 Rule Variants</a></li>
-<li><a class="reference internal" href="#rule-types" id="id30">6.1.2 Rule types</a></li>
-<li><a class="reference internal" href="#rule-file-examples" id="id31">6.1.3 Rule File Examples</a></li>
-<li><a class="reference internal" href="#rule-file-syntax" id="id32">6.1.4 Rule File Syntax</a></li>
+<li><a class="reference internal" href="#dependency-rules" id="id26">6 Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#simple-dependency-rules" id="id27">6.1 Simple Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#rule-variants" id="id28">6.1.1 Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id29">6.1.2 Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id30">6.1.3 Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id31">6.1.4 Rule File Syntax</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#package-rules" id="id33">7 Package Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#package-rule-file-syntax" id="id34">7.1 Package Rule File Syntax</a><ul class="auto-toc">
-<li><a class="reference internal" href="#match-blocks" id="id35">7.1.1 Match Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-match-block-syntax" id="id36">7.1.1.1 Extended Match Block Syntax</a></li>
+<li><a class="reference internal" href="#package-rules" id="id32">7 Package Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#package-rule-file-syntax" id="id33">7.1 Package Rule File Syntax</a><ul class="auto-toc">
+<li><a class="reference internal" href="#match-blocks" id="id34">7.1.1 Match Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-match-block-syntax" id="id35">7.1.1.1 Extended Match Block Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#action-blocks" id="id37">7.1.2 Action Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-action-block-syntax" id="id38">7.1.2.1 Extended Action Block Syntax</a></li>
+<li><a class="reference internal" href="#action-blocks" id="id36">7.1.2 Action Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-action-block-syntax" id="id37">7.1.2.1 Extended Action Block Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#package-rule-examples" id="id39">7.1.3 Package Rule Examples</a></li>
+<li><a class="reference internal" href="#package-rule-examples" id="id38">7.1.3 Package Rule Examples</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#configuration-reference" id="id40">8 Configuration Reference</a><ul class="auto-toc">
-<li><a class="reference internal" href="#misc-options" id="id41">8.1 misc options</a></li>
-<li><a class="reference internal" href="#overlay-options" id="id42">8.2 overlay options</a></li>
-<li><a class="reference internal" href="#other-config-files" id="id43">8.3 other config files</a></li>
-<li><a class="reference internal" href="#logging" id="id44">8.4 logging</a><ul class="auto-toc">
-<li><a class="reference internal" href="#console-logging" id="id45">8.4.1 console logging</a></li>
-<li><a class="reference internal" href="#file-logging" id="id46">8.4.2 file logging</a></li>
+<li><a class="reference internal" href="#configuration-reference" id="id39">8 Configuration Reference</a><ul class="auto-toc">
+<li><a class="reference internal" href="#misc-options" id="id40">8.1 misc options</a></li>
+<li><a class="reference internal" href="#overlay-options" id="id41">8.2 overlay options</a></li>
+<li><a class="reference internal" href="#other-config-files" id="id42">8.3 other config files</a></li>
+<li><a class="reference internal" href="#logging" id="id43">8.4 logging</a><ul class="auto-toc">
+<li><a class="reference internal" href="#console-logging" id="id44">8.4.1 console logging</a></li>
+<li><a class="reference internal" href="#file-logging" id="id45">8.4.2 file logging</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id47">8.5 options for debugging, manual dependency rule creation and testing</a></li>
+<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id46">8.5 options for debugging, manual dependency rule creation and testing</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#field-definition-config" id="id48">9 Field Definition Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id49">9.1 Example: The default field definition file</a></li>
+<li><a class="reference internal" href="#field-definition-config" id="id47">9 Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id48">9.1 Example: The default field definition file</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution-console" id="id50">10 Dependency Resolution Console</a></li>
-<li><a class="reference internal" href="#implementation-overview" id="id51">11 Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#packageinfo" id="id52">11.1 PackageInfo</a></li>
-<li><a class="reference internal" href="#repository-management" id="id53">11.2 Repository Management</a><ul class="auto-toc">
-<li><a class="reference internal" href="#id4" id="id54">11.2.1 Repositories</a><ul class="auto-toc">
-<li><a class="reference internal" href="#adding-new-repository-types" id="id55">11.2.1.1 Adding new repository types</a></li>
+<li><a class="reference internal" href="#dependency-resolution-console" id="id49">10 Dependency Resolution Console</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id50">11 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id51">11.1 PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id52">11.2 Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#repository" id="id53">11.2.1 Repository</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id54">11.2.1.1 Adding new repository types</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay" id="id56">11.3 Overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#metadata-creation" id="id57">11.3.1 Metadata Creation</a></li>
-<li><a class="reference internal" href="#manifest-creation" id="id58">11.3.2 Manifest Creation</a></li>
+<li><a class="reference internal" href="#overlay" id="id55">11.3 Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id56">11.3.1 Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id57">11.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#ebuild-creation" id="id59">11.4 Ebuild Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#ebuild-variables" id="id60">11.4.1 Ebuild Variables</a></li>
+<li><a class="reference internal" href="#ebuild-creation" id="id58">11.4 Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id59">11.4.1 Ebuild Variables</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay-creation" id="id61">11.5 Overlay Creation</a></li>
-<li><a class="reference internal" href="#dependency-resolution" id="id62">11.6 Dependency Resolution</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id63">11.6.1 Dependency types</a><ul class="auto-toc">
-<li><a class="reference internal" href="#description-file-dependency-fields" id="id64">11.6.1.1 DESCRIPTION file dependency fields</a></li>
+<li><a class="reference internal" href="#overlay-creation" id="id60">11.5 Overlay Creation</a></li>
+<li><a class="reference internal" href="#dependency-resolution" id="id61">11.6 Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id62">11.6.1 Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id63">11.6.1.1 DESCRIPTION file dependency fields</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-environments" id="id65">11.6.2 Dependency Environments</a></li>
-<li><a class="reference internal" href="#ebuildjob-channel" id="id66">11.6.3 EbuildJob Channel</a></li>
-<li><a class="reference internal" href="#dependency-rule-pools" id="id67">11.6.4 Dependency Rule Pools</a></li>
-<li><a class="reference internal" href="#dependency-resolver-modules" id="id68">11.6.5 Dependency Resolver Modules</a></li>
-<li><a class="reference internal" href="#dependency-resolver" id="id69">11.6.6 Dependency Resolver</a></li>
+<li><a class="reference internal" href="#dependency-environments" id="id64">11.6.2 Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id65">11.6.3 EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id66">11.6.4 Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id67">11.6.5 Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id68">11.6.6 Dependency Resolver</a></li>
</ul>
</li>
</ul>
@@ -791,6 +791,11 @@ the faster write mechanism (at ca. 95% ebuild creation success rate),
the default package repositories.</p>
</td></tr>
<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--fixup-category-move</span>, <span class="option">--fixup-category-move-reverse</span></kbd></td>
+</tr>
+<tr><td> </td><td>Remove ebuilds that have been moved to a different category.
+See <a class="reference internal" href="#action-blocks">Action Blocks</a> in <a class="reference internal" href="#package-rules">Package Rules</a> for details.</td></tr>
+<tr><td class="option-group" colspan="2">
<kbd><span class="option">--config <var>file</var></span>, <span class="option">-c <var>file</var></span></kbd></td>
</tr>
<tr><td> </td><td>Path to the config file</td></tr>
@@ -1636,9 +1641,16 @@ but without the file extension, e.g.
<td>package file name without version
and file extension, e.g. <em>seewave</em></td>
</tr>
+<tr><td>ebuild_name</td>
+<td><em>implicit</em></td>
+<td>ebuild name <tt class="docutils literal">${PN}</tt>, which is the
+package_name with special chars
+removed or replaced (e.g.,
+<em>R.oo</em> (pkg) => <em>R_oo</em> (ebuild))</td>
+</tr>
<tr><td>name</td>
<td><em>implicit</em></td>
-<td><em>alias to package_name</em></td>
+<td><em>alias to ebuild_name</em></td>
</tr>
</tbody>
</table>
@@ -1837,22 +1849,91 @@ an ebuild for it</td>
<tr><td rowspan="2">trace</td>
<td rowspan="2">package rules</td>
<td>none</td>
-<td>marks a package as
+<td>mark a package as
modified</td>
</tr>
<tr><td>1</td>
-<td>adds the stored string
+<td>add the stored string
to a package's
<em>modified</em> variable
whenever this action
is applied</td>
</tr>
+<tr><td>set</td>
+<td rowspan="2">package
+metadata,
+overlay creaton</td>
+<td>2</td>
+<td rowspan="2">set package
+information</td>
+</tr>
+<tr><td>set_<key></td>
+<td>1</td>
+</tr>
+<tr><td>rename</td>
+<td rowspan="2">package
+metadata,
+overlay creation</td>
+<td>2</td>
+<td rowspan="2">modify package
+information with
+sed-like
+<em>s/expr/repl/</em>
+statements</td>
+</tr>
+<tr><td>rename_<key></td>
+<td>1</td>
+</tr>
</tbody>
</table>
+<p>The two-arg form of the set/rename keywords expect a <key> as first and
+a value / sed expression as second arg. The one-arg form expects the latter
+one only. The "/" delimitier in the sed expression can be any character.</p>
+<p>The following <em>info keys</em> can be set and/or modified:</p>
+<table border="1" class="docutils">
+<caption>info keys for set/rename</caption>
+<colgroup>
+<col width="19%" />
+<col width="29%" />
+<col width="51%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">info key</th>
+<th class="head">supports set/rename</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>name</td>
+<td>yes / yes</td>
+<td>rename the ebuild</td>
+</tr>
+<tr><td>category</td>
+<td>yes / <strong>no</strong></td>
+<td>set package category</td>
+</tr>
+<tr><td>destfile</td>
+<td>yes / yes</td>
+<td>rename ebuild destfile by using the
+'->' operator in <tt class="docutils literal">${SRC_URI}</tt></td>
+</tr>
+</tbody>
+</table>
+<div class="caution">
+<p class="first admonition-title">Caution!</p>
+<p class="last">Category moves are not handled automatically. In incremental mode, overlay
+creation has to be called with either <tt class="docutils literal"><span class="pre">--fixup-category-move</span></tt> or
+<tt class="docutils literal"><span class="pre">--fixup-category-move-reverse</span></tt>, depending on whether the package(s)
+have been moved away from the default category or back to the default
+category ("reverse"). Configuring both category move types at once requires
+a full recreation of the overlay, that is <tt class="docutils literal">rm <span class="pre">-rf</span> <overlay dir></tt>
+followed by <tt class="docutils literal">roverlay create</tt>.</p>
+</div>
<div class="note">
<p class="first admonition-title">Note</p>
-<p class="last">Applying the same (non-incremental) ebuild variable action more than once
-is possible, but only the last one will have an effect on ebuild creation.</p>
+<p class="last">Applying the same (non-incremental) ebuild variable, set or rename action
+more than once is possible, but only the last one will have an effect
+on ebuild creation.</p>
</div>
<div class="section" id="extended-action-block-syntax">
<h4><a class="toc-backref" href="#contents">7.1.2.1 Extended Action Block Syntax</a></h4>
@@ -1911,6 +1992,37 @@ ACTION:
END;
END;
</pre>
+<p>A rule that assigns all packages from BIOC-2.10/bioc to sci-bioc:</p>
+<pre class="code literal-block">
+MATCH:
+ repo == BIOC-2.10/bioc
+ACTION:
+ set category sci-bioc
+END;
+
+# alternatively:
+MATCH:
+ repo == BIOC-2.10/bioc
+ACTION:
+ set_category sci-bioc
+END;
+</pre>
+<p>The following example prefixes all <em>yaml</em> packages with <em>Rpkg_</em>:</p>
+<pre class="code literal-block">
+MATCH:
+ ebuild_name ,= yaml
+ACTION:
+ rename destfile s/^/Rpkg_/
+END;
+</pre>
+<p>Moving such packages to a "R-package" sub directory would be possible, too:</p>
+<pre class="code literal-block">
+MATCH:
+ name ,= yaml
+ACTION:
+ rename_destfile s=^=R-package=
+END;
+</pre>
</div>
</div>
</div>
@@ -1988,8 +2100,9 @@ location (see <a class="reference internal" href="#repo-config-options">repo con
<dl class="docutils" id="ebuild-prog">
<dt>EBUILD_PROG</dt>
<dd><p class="first">Name or path of the ebuild executables that is required for (external)
-Manifest file creation. A wrong value will cause ebuild creation late,
-which is a huge time loss, so make sure that this option is properly set.</p>
+Manifest file creation. A wrong value will cause ebuild creation to fail
+late, which is a huge time loss, so make sure that this option is properly
+set.</p>
<p class="last">Defaults to <em>ebuild</em>, which should be fine in most cases.</p>
</dd>
</dl>
@@ -2639,8 +2752,8 @@ functionality:</p>
<li><em>sync</em> all repos and <em>nosync</em> all repos (offline mode)</li>
<li>create <em>PackageInfo</em> instances for R packages from all repositories</li>
</ul>
-<div class="section" id="id4">
-<h3><a class="toc-backref" href="#contents">11.2.1 Repositories</a></h3>
+<div class="section" id="repository">
+<h3><a class="toc-backref" href="#contents">11.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,
@@ -3116,7 +3229,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-04-23.
+Generated on: 2013-06-05.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
2013-06-12 21:10 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
@ 2013-06-13 16:34 ` André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-06-13 16:34 UTC (permalink / raw
To: gentoo-commits
commit: f2919debb37db3e9994392a77cc5072d2e568181
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jun 12 21:09:18 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jun 12 21:09:18 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=f2919deb
doc/html: additions dir
---
doc/html/usage.html | 280 ++++++++++++++++++++++++++++++++++------------------
1 file changed, 183 insertions(+), 97 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 9ab7683..5c4863b 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -363,77 +363,82 @@ ul.auto-toc {
<li><a class="reference internal" href="#using-local-directories" id="id25">5.5 Using local directories</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-rules" id="id26">6 Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#simple-dependency-rules" id="id27">6.1 Simple Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#rule-variants" id="id28">6.1.1 Rule Variants</a></li>
-<li><a class="reference internal" href="#rule-types" id="id29">6.1.2 Rule types</a></li>
-<li><a class="reference internal" href="#rule-file-examples" id="id30">6.1.3 Rule File Examples</a></li>
-<li><a class="reference internal" href="#rule-file-syntax" id="id31">6.1.4 Rule File Syntax</a></li>
+<li><a class="reference internal" href="#additions-directory" id="id26">6 Additions Directory</a><ul class="auto-toc">
+<li><a class="reference internal" href="#patching-ebuilds" id="id27">6.1 Patching ebuilds</a></li>
+<li><a class="reference internal" href="#importing-ebuilds" id="id28">6.2 Importing ebuilds</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#dependency-rules" id="id29">7 Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#simple-dependency-rules" id="id30">7.1 Simple Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#rule-variants" id="id31">7.1.1 Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id32">7.1.2 Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id33">7.1.3 Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id34">7.1.4 Rule File Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#package-rules" id="id32">7 Package Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#package-rule-file-syntax" id="id33">7.1 Package Rule File Syntax</a><ul class="auto-toc">
-<li><a class="reference internal" href="#match-blocks" id="id34">7.1.1 Match Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-match-block-syntax" id="id35">7.1.1.1 Extended Match Block Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#action-blocks" id="id36">7.1.2 Action Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-action-block-syntax" id="id37">7.1.2.1 Extended Action Block Syntax</a></li>
+<li><a class="reference internal" href="#package-rules" id="id35">8 Package Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#package-rule-file-syntax" id="id36">8.1 Package Rule File Syntax</a><ul class="auto-toc">
+<li><a class="reference internal" href="#match-blocks" id="id37">8.1.1 Match Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-match-block-syntax" id="id38">8.1.1.1 Extended Match Block Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#package-rule-examples" id="id38">7.1.3 Package Rule Examples</a></li>
+<li><a class="reference internal" href="#action-blocks" id="id39">8.1.2 Action Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-action-block-syntax" id="id40">8.1.2.1 Extended Action Block Syntax</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#package-rule-examples" id="id41">8.1.3 Package Rule Examples</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#configuration-reference" id="id39">8 Configuration Reference</a><ul class="auto-toc">
-<li><a class="reference internal" href="#misc-options" id="id40">8.1 misc options</a></li>
-<li><a class="reference internal" href="#overlay-options" id="id41">8.2 overlay options</a></li>
-<li><a class="reference internal" href="#other-config-files" id="id42">8.3 other config files</a></li>
-<li><a class="reference internal" href="#logging" id="id43">8.4 logging</a><ul class="auto-toc">
-<li><a class="reference internal" href="#console-logging" id="id44">8.4.1 console logging</a></li>
-<li><a class="reference internal" href="#file-logging" id="id45">8.4.2 file logging</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id46">8.5 options for debugging, manual dependency rule creation and testing</a></li>
+<li><a class="reference internal" href="#configuration-reference" id="id42">9 Configuration Reference</a><ul class="auto-toc">
+<li><a class="reference internal" href="#misc-options" id="id43">9.1 misc options</a></li>
+<li><a class="reference internal" href="#overlay-options" id="id44">9.2 overlay options</a></li>
+<li><a class="reference internal" href="#other-config-files" id="id45">9.3 other config files</a></li>
+<li><a class="reference internal" href="#logging" id="id46">9.4 logging</a><ul class="auto-toc">
+<li><a class="reference internal" href="#console-logging" id="id47">9.4.1 console logging</a></li>
+<li><a class="reference internal" href="#file-logging" id="id48">9.4.2 file logging</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#field-definition-config" id="id47">9 Field Definition Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id48">9.1 Example: The default field definition file</a></li>
+<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id49">9.5 options for debugging, manual dependency rule creation and testing</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution-console" id="id49">10 Dependency Resolution Console</a></li>
-<li><a class="reference internal" href="#implementation-overview" id="id50">11 Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#packageinfo" id="id51">11.1 PackageInfo</a></li>
-<li><a class="reference internal" href="#repository-management" id="id52">11.2 Repository Management</a><ul class="auto-toc">
-<li><a class="reference internal" href="#repository" id="id53">11.2.1 Repository</a><ul class="auto-toc">
-<li><a class="reference internal" href="#adding-new-repository-types" id="id54">11.2.1.1 Adding new repository types</a></li>
+<li><a class="reference internal" href="#field-definition-config" id="id50">10 Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id51">10.1 Example: The default field definition file</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#dependency-resolution-console" id="id52">11 Dependency Resolution Console</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id53">12 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id54">12.1 PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id55">12.2 Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#repository" id="id56">12.2.1 Repository</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id57">12.2.1.1 Adding new repository types</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay" id="id55">11.3 Overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#metadata-creation" id="id56">11.3.1 Metadata Creation</a></li>
-<li><a class="reference internal" href="#manifest-creation" id="id57">11.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#ebuild-creation" id="id58">11.4 Ebuild Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#ebuild-variables" id="id59">11.4.1 Ebuild Variables</a></li>
+<li><a class="reference internal" href="#overlay" id="id58">12.3 Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id59">12.3.1 Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id60">12.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay-creation" id="id60">11.5 Overlay Creation</a></li>
-<li><a class="reference internal" href="#dependency-resolution" id="id61">11.6 Dependency Resolution</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id62">11.6.1 Dependency types</a><ul class="auto-toc">
-<li><a class="reference internal" href="#description-file-dependency-fields" id="id63">11.6.1.1 DESCRIPTION file dependency fields</a></li>
+<li><a class="reference internal" href="#ebuild-creation" id="id61">12.4 Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id62">12.4.1 Ebuild Variables</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-environments" id="id64">11.6.2 Dependency Environments</a></li>
-<li><a class="reference internal" href="#ebuildjob-channel" id="id65">11.6.3 EbuildJob Channel</a></li>
-<li><a class="reference internal" href="#dependency-rule-pools" id="id66">11.6.4 Dependency Rule Pools</a></li>
-<li><a class="reference internal" href="#dependency-resolver-modules" id="id67">11.6.5 Dependency Resolver Modules</a></li>
-<li><a class="reference internal" href="#dependency-resolver" id="id68">11.6.6 Dependency Resolver</a></li>
+<li><a class="reference internal" href="#overlay-creation" id="id63">12.5 Overlay Creation</a></li>
+<li><a class="reference internal" href="#dependency-resolution" id="id64">12.6 Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id65">12.6.1 Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id66">12.6.1.1 DESCRIPTION file dependency fields</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dependency-environments" id="id67">12.6.2 Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id68">12.6.3 EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id69">12.6.4 Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id70">12.6.5 Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id71">12.6.6 Dependency Resolver</a></li>
</ul>
</li>
</ul>
@@ -466,17 +471,18 @@ does and what to expect from the generated overlay.</p>
</li>
<li><p class="first"><em>roverlay</em> maintainers who <strong>control and test overlay creation</strong>,
e.g. configure which R packages will be part of the generated overlay</p>
-<p>Depending on what you want to configure, chapters 5-8 are relevant,
-namely <a class="reference internal" href="#repositories-getting-packages">Repositories / Getting Packages</a>, <a class="reference internal" href="#dependency-rules">Dependency Rules</a>,
-<a class="reference internal" href="#configuration-reference">Configuration Reference</a> and <a class="reference internal" href="#field-definition-config">Field Definition Config</a>.</p>
+<p>Depending on what you want to configure, chapters 5-10 are relevant,
+namely <a class="reference internal" href="#repositories-getting-packages">Repositories / Getting Packages</a>, <cite>Additions Directory</cite>,
+<a class="reference internal" href="#dependency-rules">Dependency Rules</a>, <a class="reference internal" href="#package-rules">Package Rules</a>, <a class="reference internal" href="#configuration-reference">Configuration Reference</a>
+and <a class="reference internal" href="#field-definition-config">Field Definition Config</a>.</p>
<p>There is another chapter that is only interesting for testing, the
-<a class="reference internal" href="#dependency-resolution-console">Dependency Resolution Console</a> (10), which can be used to interactively
+<a class="reference internal" href="#dependency-resolution-console">Dependency Resolution Console</a> (11), which can be used to interactively
test dependency rules.</p>
</li>
<li><p class="first"><em>roverlay</em> code maintainers who want to know <strong>how roverlay works</strong> for
code improvements etc.</p>
-<p>The most important chapter is <a class="reference internal" href="#implementation-overview">Implementation Overview</a> (11) which has
-references to other chapters (4-9) where required.</p>
+<p>The most important chapter is <a class="reference internal" href="#implementation-overview">Implementation Overview</a> (12) which has
+references to other chapters (4-10) where required.</p>
</li>
</ul>
</blockquote>
@@ -677,12 +683,17 @@ This option is <strong>required</strong> and can be overridden on the command li
via one or more <tt class="docutils literal"><span class="pre">--repo-config</span> <file></tt> statements.</p>
<p class="last">Example: REPO_CONFIG = ~/roverlay/config/repo.list</p>
</dd>
-<dt>PACKAGE_RULES:</dt>
+<dt>PACKAGE_RULES</dt>
<dd><p class="first">A list of files and/or directories with package rules.
Package rules can be used to control overlay/ebuild creation.
This option is not required.</p>
<p class="last">Example: PACKAGE_RULES = ~/roverlay/config/packagerules.d</p>
</dd>
+<dt>ADDITIONS_DIR</dt>
+<dd><p class="first">Directory with an overlay-like structure that contains extra files, e.g.
+ebuild patches and hand-written ebuilds.</p>
+<p class="last">Example: ADDITIONS_DIR = ~/roverlay/additions</p>
+</dd>
<dt>FIELD_DEFINITION</dt>
<dd><p class="first">The value of this option should point to a field definition file which
controls how an R package's DESCRIPTION file is read.
@@ -897,6 +908,8 @@ most cases, but fine-tuning can be done via <a class="reference internal" href="
</li>
<li><p class="first">scan the R Overlay directory (if it exists) for valid ebuilds</p>
</li>
+<li><p class="first">import ebuilds from the additions dir</p>
+</li>
<li><p class="first"><strong>add</strong> - queue all R packages for ebuild creation</p>
<ul>
<li><p class="first">all repositories are asked to list their packages which are then added
@@ -939,9 +952,9 @@ and may decide to write <em>p</em>'s ebuild now (or later)</p>
</li>
</ul>
</blockquote>
-<ol class="arabic simple" start="5">
+<ol class="arabic simple" start="6">
<li>write the overlay<ul>
-<li>write all ebuilds
+<li>write all ebuilds and apply patches to them
(supports threads on a per package basis)</li>
<li>write the <em>metadata.xml</em> files
(supports threads on a per package basis)<ul>
@@ -1297,10 +1310,72 @@ consider using one of the <strong>websync</strong> repo types, <a class="referen
</div>
</div>
</div>
+<div class="section" id="additions-directory">
+<h1><a class="toc-backref" href="#contents">6 Additions Directory</a></h1>
+<p>The <em>additions directory</em> is a directory with overlay-like structure that
+contains extra files for overlay creation. Currently, ebuild patches and
+ebuild files are supported.</p>
+<p>To give an idea of how this directory could</p>
+<div class="section" id="patching-ebuilds">
+<h2><a class="toc-backref" href="#contents">6.1 Patching ebuilds</a></h2>
+<p>Patches can apply to a <strong>specific version</strong> or to <strong>all versions</strong> of a
+package.</p>
+<p>The naming convention for patches is (full filesystem paths relative to the
+additions dir):</p>
+<pre class="code text literal-block">
+# version-specific patches
+${CATEGORY}/${PN}/${PF}[-dddd].patch
+
+# version-agnostic patches
+${CATEGORY}/${PN}/${PN}[-dddd].patch
+</pre>
+<p>The <em>-dddd</em> part is optional and can be used to apply more than one patch to
+an ebuild in the specified order. <em>d</em> should be a digit (0..9) and exactly
+4 digits are expected. The not-numbered patch is always applied first.
+So, in theory, up to 10001 patches per ebuild are supported.</p>
+<p>The <em>default</em> (version-agnostic) patches are only applied to ebuilds for
+which no version-specific patches exist.</p>
+<p>Exempting a specific ebuild from being patched can be achieved by creating
+an empty patch file (or a symlink to /dev/null). This is only necessary
+if <em>default</em> patches are available, else it adds some overhead.</p>
+<div class="caution">
+<p class="first admonition-title">Caution!</p>
+<p class="last">Don't try to patch the (R)DEPEND variables of an ebuild.
+It will <em>randomly</em> break because <em>roverlay</em> uses unordered data structures
+for collecting dependencies.</p>
+</div>
+<p>Example:</p>
+<pre class="code text literal-block">
+<additions dir>/sci-CRAN/R_oo/R_oo-1.9.8.patch
+<additions dir>/sci-CRAN/R_oo/R_oo-1.9.8-0000.patch
+<additions dir>/sci-CRAN/R_oo/R_oo-1.9.8-0001.patch
+<additions dir>/sci-R/seewave/seewave-1.6.7.patch
+<additions dir>/sci-R/seewave/seewave.patch
+</pre>
+</div>
+<div class="section" id="importing-ebuilds">
+<h2><a class="toc-backref" href="#contents">6.2 Importing ebuilds</a></h2>
+<p>Foreign ebuilds can be imported into the overlay by simple putting them into
+the additions directory.</p>
+<p>The naming convention is similar to ebuild patches and identical to the
+portage tree:</p>
+<pre class="code literal-block">
+${CATEGORY}/${PN}/${PF}.ebuild
+</pre>
+<p>Ebuilds imported that way can not be overwritten by generated ebuilds and
+benefit from most overlay creation features, e.g. Manifest file creation.
+However, they cannot be used for metadata creation.</p>
+<div class="important">
+<p class="first admonition-title">Important</p>
+<p class="last">Importing ebuilds is only supported by the default Manifest implementation
+(<em>ebuildmanifest</em>).</p>
+</div>
+</div>
+</div>
<div class="section" id="dependency-rules">
-<h1><a class="toc-backref" href="#contents">6 Dependency Rules</a></h1>
+<h1><a class="toc-backref" href="#contents">7 Dependency Rules</a></h1>
<div class="section" id="simple-dependency-rules">
-<h2><a class="toc-backref" href="#contents">6.1 Simple Dependency Rules</a></h2>
+<h2><a class="toc-backref" href="#contents">7.1 Simple Dependency Rules</a></h2>
<p><em>Simple dependency rules</em> use a dictionary and string transformations
to resolve dependencies. <em>Fuzzy simple dependency rules</em> extend these by
a set of regular expressions, which allows to resolve many dependency strings
@@ -1309,7 +1384,7 @@ that minimally differ (e.g. only in the required version and/or comments:
dictionary entry.</p>
<p>This is the only rule implementation currently available.</p>
<div class="section" id="rule-variants">
-<h3><a class="toc-backref" href="#contents">6.1.1 Rule Variants</a></h3>
+<h3><a class="toc-backref" href="#contents">7.1.1 Rule Variants</a></h3>
<dl class="docutils">
<dt>default</dt>
<dd>The expected behavior of a dictionary-based rule: It matches one or more
@@ -1320,7 +1395,7 @@ resolve them as <strong>nothing</strong>.</dd>
</dl>
</div>
<div class="section" id="rule-types">
-<h3><a class="toc-backref" href="#contents">6.1.2 Rule types</a></h3>
+<h3><a class="toc-backref" href="#contents">7.1.2 Rule types</a></h3>
<dl class="docutils">
<dt>Simple Rules</dt>
<dd><p class="first">A simple rule resolves <strong>exact string matches</strong> (case-insensitive).</p>
@@ -1361,7 +1436,7 @@ as "<dev-lang/R-2.14"</li>
</dl>
</div>
<div class="section" id="rule-file-examples">
-<h3><a class="toc-backref" href="#contents">6.1.3 Rule File Examples</a></h3>
+<h3><a class="toc-backref" href="#contents">7.1.3 Rule File Examples</a></h3>
<p>This sections lists some rule file examples.
See <a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a> for a formal description.</p>
<dl class="docutils">
@@ -1418,7 +1493,7 @@ They can be found in <em>/etc/roverlay/simple-deprules.d</em> if <em>roverlay</e
installed with <em>emerge</em>, else in <em><R Overlay src directory>/simple-deprules.d</em>.</p>
</div>
<div class="section" id="rule-file-syntax">
-<span id="dependency-rule-file-syntax"></span><h3><a class="toc-backref" href="#contents">6.1.4 Rule File Syntax</a></h3>
+<span id="dependency-rule-file-syntax"></span><h3><a class="toc-backref" href="#contents">7.1.4 Rule File Syntax</a></h3>
<p>Simple dependency rule files have a special syntax. Each rule is introduced
with the resolving <em>dependency</em> prefixed by a <em>keychar</em> that sets the rule
type if required. The <em>dependency strings</em> resolved by this rule are listed
@@ -1552,7 +1627,7 @@ as <em>sci-R/zoo</em>. This rule can be written as a single word, <em>zoo</em>.<
</div>
</div>
<div class="section" id="package-rules">
-<h1><a class="toc-backref" href="#contents">7 Package Rules</a></h1>
+<h1><a class="toc-backref" href="#contents">8 Package Rules</a></h1>
<p>Package Rules can be used to control both overlay and ebuild creation.
Each package rule consists of conditions, e.g. <em>package name contains amd64</em>,
and actions, e.g. <em>set KEYWORDS="-x86 amd64"</em>.
@@ -1561,7 +1636,7 @@ otherwise the rule does nothing.
Moreover, rules can contain further rules which will only take effect if all
enclosing rules match a given package.</p>
<div class="section" id="package-rule-file-syntax">
-<h2><a class="toc-backref" href="#contents">7.1 Package Rule File Syntax</a></h2>
+<h2><a class="toc-backref" href="#contents">8.1 Package Rule File Syntax</a></h2>
<p>As stated above, each rule has two parts, a <em>match block</em> that lists the
rule's conditions and an <em>action block</em> that defines which actions and
nested rules are applied to a package if the rule matches it, i.e. if all
@@ -1591,7 +1666,7 @@ The <em>match block</em> ends with the <tt class="docutils literal">ACTION:</tt>
Lines starting with <tt class="docutils literal">#</tt> or <tt class="docutils literal">;</tt> are considered to be comments and will be
ignored.</p>
<div class="section" id="match-blocks">
-<h3><a class="toc-backref" href="#contents">7.1.1 Match Blocks</a></h3>
+<h3><a class="toc-backref" href="#contents">8.1.1 Match Blocks</a></h3>
<p>The <em>match block</em> lists one or more conditions, which all must evaluate to
<em>true</em> for a certain package, otherwise no actions will be applied.
There are two types of conditions, <em>trivial</em> conditions,
@@ -1699,7 +1774,7 @@ be replaced with their regex equivalents.</td>
<p>The <em>accepted value</em> is a simple string or a regular expression,
which depends on the operator.</p>
<div class="section" id="extended-match-block-syntax">
-<h4><a class="toc-backref" href="#contents">7.1.1.1 Extended Match Block Syntax</a></h4>
+<h4><a class="toc-backref" href="#contents">8.1.1.1 Extended Match Block Syntax</a></h4>
<p>Sometimes, a rule should apply its actions to a package if it matches <em>any</em>
condition, e.g. <em>package from CRAN or BIOC</em>, or if it does not match a certain
condition, e.g. <em>package not from BIOC/experiment</em>.</p>
@@ -1805,7 +1880,7 @@ END;
</div>
</div>
<div class="section" id="action-blocks">
-<h3><a class="toc-backref" href="#contents">7.1.2 Action Blocks</a></h3>
+<h3><a class="toc-backref" href="#contents">8.1.2 Action Blocks</a></h3>
<p>The action block syntax is quite simple. Each <em>action statement</em> starts
with an <em>action keyword</em>, optionally followed by one or more <em>values</em>.</p>
<p>Action statement syntax:</p>
@@ -1936,7 +2011,7 @@ more than once is possible, but only the last one will have an effect
on ebuild creation.</p>
</div>
<div class="section" id="extended-action-block-syntax">
-<h4><a class="toc-backref" href="#contents">7.1.2.1 Extended Action Block Syntax</a></h4>
+<h4><a class="toc-backref" href="#contents">8.1.2.1 Extended Action Block Syntax</a></h4>
<p>A mentioned before, action blocks can contain <em>nested rules</em>. The syntax
is exactly the same as for the normal package rules:</p>
<pre class="code literal-block">
@@ -1964,7 +2039,7 @@ checks necessary for a given package.</p>
</div>
</div>
<div class="section" id="package-rule-examples">
-<h3><a class="toc-backref" href="#contents">7.1.3 Package Rule Examples</a></h3>
+<h3><a class="toc-backref" href="#contents">8.1.3 Package Rule Examples</a></h3>
<p>A rule that ignores the 'yaqcaffy' package from CRAN, which is also available
from BIOC:</p>
<pre class="code literal-block">
@@ -2027,7 +2102,7 @@ END;
</div>
</div>
<div class="section" id="configuration-reference">
-<h1><a class="toc-backref" href="#contents">8 Configuration Reference</a></h1>
+<h1><a class="toc-backref" href="#contents">9 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.
@@ -2080,7 +2155,7 @@ 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">8.1 misc options</a></h2>
+<h2><a class="toc-backref" href="#contents">9.1 misc options</a></h2>
<dl class="docutils" id="distfiles">
<dt>DISTFILES</dt>
<dd>Alias to <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
@@ -2115,7 +2190,11 @@ 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">8.2 overlay options</a></h2>
+<h2><a class="toc-backref" href="#contents">9.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>
+</dl>
<dl class="docutils" id="distdir">
<dt>DISTDIR</dt>
<dd>Alias to <a class="reference internal" href="#overlay-distdir-root">OVERLAY_DISTDIR_ROOT</a>.</dd>
@@ -2136,6 +2215,13 @@ This will pass '--bwlimit=<value>' to all rsync commands.</p>
<dt>MANIFEST_IMPLEMENTATION</dt>
<dd>Alias to <a class="reference internal" href="#overlay-manifest-implementation">OVERLAY_MANIFEST_IMPLEMENTATION</a>.</dd>
</dl>
+<dl class="docutils" id="overlay-additions-dir">
+<dt>OVERLAY_ADDITIONS_DIR</dt>
+<dd><p class="first">Directory with an overlay-like structure that contains extra files, e.g.
+ebuild patches and hand-written ebuilds. This option is not required.</p>
+<p class="last">Defaults to <not set>, which disables this feature.</p>
+</dd>
+</dl>
<dl class="docutils" id="overlay-category">
<dt>OVERLAY_CATEGORY</dt>
<dd><p class="first">Sets the category of created ebuilds. There are no value type restrictions
@@ -2151,7 +2237,7 @@ for this option, but values with a slash <em>/</em> lead to errors.</p>
</dl>
<dl class="docutils" id="overlay-distdir-flat">
<dt>OVERLAY_DISTDIR_FLAT</dt>
-<dd><p class="first">A <em>bool</em> that controls the overall layout of _OVERLAY_DISTDIR_ROOT.</p>
+<dd><p class="first">A <em>bool</em> that controls the overall layout of <a class="reference internal" href="#overlay-distdir-root">OVERLAY_DISTDIR_ROOT</a>.</p>
<p>A flat distdir is a single directory with all package files or package
file links in it. A nested distdir contains per-package directories.</p>
<p class="last">Defaults to <em>true</em>.
@@ -2257,7 +2343,7 @@ writing.</p>
</dl>
</div>
<div class="section" id="other-config-files">
-<h2><a class="toc-backref" href="#contents">8.3 other config files</a></h2>
+<h2><a class="toc-backref" href="#contents">9.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">
@@ -2315,7 +2401,7 @@ much without dependency resolution.</p>
</dl>
</div>
<div class="section" id="logging">
-<h2><a class="toc-backref" href="#contents">8.4 logging</a></h2>
+<h2><a class="toc-backref" href="#contents">9.4 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>
@@ -2340,7 +2426,7 @@ have their own log level.</p>
</dd>
</dl>
<div class="section" id="console-logging">
-<h3><a class="toc-backref" href="#contents">8.4.1 console logging</a></h3>
+<h3><a class="toc-backref" href="#contents">9.4.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>
@@ -2361,7 +2447,7 @@ have their own log level.</p>
</dl>
</div>
<div class="section" id="file-logging">
-<h3><a class="toc-backref" href="#contents">8.4.2 file logging</a></h3>
+<h3><a class="toc-backref" href="#contents">9.4.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
@@ -2420,7 +2506,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">8.5 options for debugging, manual dependency rule creation and testing</a></h2>
+<h2><a class="toc-backref" href="#contents">9.5 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
@@ -2439,7 +2525,7 @@ on <em>roverlay</em> exit. Primarily useful for creating new rules.</p>
</div>
</div>
<div class="section" id="field-definition-config">
-<span id="id3"></span><h1><a class="toc-backref" href="#contents">9 Field Definition Config</a></h1>
+<span id="id3"></span><h1><a class="toc-backref" href="#contents">10 Field Definition Config</a></h1>
<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>
@@ -2521,7 +2607,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><h2><a class="toc-backref" href="#contents">9.1 Example: The default field definition file</a></h2>
+<span id="default-field-definition-file"></span><h2><a class="toc-backref" href="#contents">10.1 Example: The default field definition file</a></h2>
<p>This is the default field definition file (without any ignored fields):</p>
<pre class="code ini literal-block">
<span class="keyword">[Description]</span>
@@ -2557,7 +2643,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">10 Dependency Resolution Console</a></h1>
+<span id="depres-console"></span><h1><a class="toc-backref" href="#contents">11 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">
@@ -2715,13 +2801,13 @@ cmd % exit
</dl>
</div>
<div class="section" id="implementation-overview">
-<h1><a class="toc-backref" href="#contents">11 Implementation Overview</a></h1>
+<h1><a class="toc-backref" href="#contents">12 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">11.1 PackageInfo</a></h2>
+<h2><a class="toc-backref" href="#contents">12.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>
@@ -2742,7 +2828,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">11.2 Repository Management</a></h2>
+<h2><a class="toc-backref" href="#contents">12.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>
@@ -2753,7 +2839,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">11.2.1 Repository</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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,
@@ -2794,7 +2880,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">11.2.1.1 Adding new repository types</a></h4>
+<h4><a class="toc-backref" href="#contents">12.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.
@@ -2881,7 +2967,7 @@ to be accessible.</p>
</div>
</div>
<div class="section" id="overlay">
-<h2><a class="toc-backref" href="#contents">11.3 Overlay</a></h2>
+<h2><a class="toc-backref" href="#contents">12.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>
@@ -2912,7 +2998,7 @@ level</p>
</li>
</ul>
<div class="section" id="metadata-creation">
-<h3><a class="toc-backref" href="#contents">11.3.1 Metadata Creation</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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
@@ -2921,7 +3007,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">11.3.2 Manifest Creation</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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
@@ -2930,7 +3016,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">11.4 Ebuild Creation</a></h2>
+<h2><a class="toc-backref" href="#contents">12.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>
@@ -2949,7 +3035,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">11.4.1 Ebuild Variables</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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
@@ -2957,7 +3043,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">11.5 Overlay Creation</a></h2>
+<h2><a class="toc-backref" href="#contents">12.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.
@@ -2971,7 +3057,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">11.6 Dependency Resolution</a></h2>
+<h2><a class="toc-backref" href="#contents">12.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
@@ -2993,7 +3079,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">11.6.1 Dependency types</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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">
@@ -3022,7 +3108,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">11.6.1.1 DESCRIPTION file dependency fields</a></h4>
+<h4><a class="toc-backref" href="#contents">12.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>
@@ -3081,7 +3167,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">11.6.2 Dependency Environments</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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
@@ -3091,7 +3177,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">11.6.3 EbuildJob Channel</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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>
@@ -3128,7 +3214,7 @@ dependencies are unresolvable.</li>
</ol>
</div>
<div class="section" id="dependency-rule-pools">
-<h3><a class="toc-backref" href="#contents">11.6.4 Dependency Rule Pools</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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>
@@ -3151,7 +3237,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">11.6.5 Dependency Resolver Modules</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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">
@@ -3171,7 +3257,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">11.6.6 Dependency Resolver</a></h3>
+<h3><a class="toc-backref" href="#contents">12.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
@@ -3229,7 +3315,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-06-05.
+Generated on: 2013-06-12.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
2013-06-18 14:12 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
@ 2013-06-18 14:12 ` André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-06-18 14:12 UTC (permalink / raw
To: gentoo-commits
commit: 7bb0058e0639e2829eae14dd0bef98e230ef60dc
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Jun 18 12:54:45 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Jun 18 12:54:45 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=7bb0058e
doc/html: r_suggests USE_EXPAND variable
---
doc/html/usage.html | 309 +++++++++++++++++++++++++++++++++++-----------------
1 file changed, 211 insertions(+), 98 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 5c4863b..9206894 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -329,116 +329,120 @@ ul.auto-toc {
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#introduction" id="id4">1 Introduction</a></li>
-<li><a class="reference internal" href="#installation" id="id5">2 Installation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#prerequisites" id="id6">2.1 Prerequisites</a></li>
-<li><a class="reference internal" href="#via-emerge-gentoo" id="id7">2.2 via emerge (Gentoo)</a></li>
-<li><a class="reference internal" href="#manual-installation" id="id8">2.3 Manual Installation</a></li>
-<li><a class="reference internal" href="#using-roverlay-without-installation" id="id9">2.4 Using <em>roverlay</em> without installation</a></li>
+<li><a class="reference internal" href="#introduction" id="id5">1 Introduction</a></li>
+<li><a class="reference internal" href="#installation" id="id6">2 Installation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#prerequisites" id="id7">2.1 Prerequisites</a></li>
+<li><a class="reference internal" href="#via-emerge-gentoo" id="id8">2.2 via emerge (Gentoo)</a></li>
+<li><a class="reference internal" href="#manual-installation" id="id9">2.3 Manual Installation</a></li>
+<li><a class="reference internal" href="#using-roverlay-without-installation" id="id10">2.4 Using <em>roverlay</em> without installation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-roverlay" id="id10">3 Running Roverlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#required-configuration-steps" id="id11">3.1 Required configuration steps</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id12">3.1.1 Extended Configuration / Where to go from here?</a></li>
+<li><a class="reference internal" href="#running-roverlay" id="id11">3 Running Roverlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#required-configuration-steps" id="id12">3.1 Required configuration steps</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id13">3.1.1 Extended Configuration / Where to go from here?</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-it" id="id13">3.2 Running it</a></li>
-<li><a class="reference internal" href="#providing-a-package-mirror" id="id14">3.3 Providing a package mirror</a></li>
+<li><a class="reference internal" href="#running-it" id="id14">3.2 Running it</a></li>
+<li><a class="reference internal" href="#providing-a-package-mirror" id="id15">3.3 Providing a package mirror</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#basic-implementation-overview" id="id15">4 Basic Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-roverlay-works" id="id16">4.1 How <em>roverlay</em> works</a></li>
-<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id17">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#expected-ebuild-result" id="id18">4.2.1 Expected Ebuild Result</a></li>
-<li><a class="reference internal" href="#expected-metadata-xml-result" id="id19">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
+<li><a class="reference internal" href="#basic-implementation-overview" id="id16">4 Basic Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#how-roverlay-works" id="id17">4.1 How <em>roverlay</em> works</a></li>
+<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id18">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#expected-ebuild-result" id="id19">4.2.1 Expected Ebuild Result</a></li>
+<li><a class="reference internal" href="#expected-metadata-xml-result" id="id20">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#repositories-getting-packages" id="id20">5 Repositories / Getting Packages</a><ul class="auto-toc">
-<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id21">5.1 A word about repo config files</a></li>
-<li><a class="reference internal" href="#rsync-repos" id="id22">5.2 Rsync repos</a></li>
-<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id23">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="id24">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="id25">5.5 Using local directories</a></li>
+<li><a class="reference internal" href="#repositories-getting-packages" id="id21">5 Repositories / Getting Packages</a><ul class="auto-toc">
+<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id22">5.1 A word about repo config files</a></li>
+<li><a class="reference internal" href="#rsync-repos" id="id23">5.2 Rsync repos</a></li>
+<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>
</ul>
</li>
-<li><a class="reference internal" href="#additions-directory" id="id26">6 Additions Directory</a><ul class="auto-toc">
-<li><a class="reference internal" href="#patching-ebuilds" id="id27">6.1 Patching ebuilds</a></li>
-<li><a class="reference internal" href="#importing-ebuilds" id="id28">6.2 Importing ebuilds</a></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>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-rules" id="id29">7 Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#simple-dependency-rules" id="id30">7.1 Simple Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#rule-variants" id="id31">7.1.1 Rule Variants</a></li>
-<li><a class="reference internal" href="#rule-types" id="id32">7.1.2 Rule types</a></li>
-<li><a class="reference internal" href="#rule-file-examples" id="id33">7.1.3 Rule File Examples</a></li>
-<li><a class="reference internal" href="#rule-file-syntax" id="id34">7.1.4 Rule File Syntax</a></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>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#package-rules" id="id35">8 Package Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#package-rule-file-syntax" id="id36">8.1 Package Rule File Syntax</a><ul class="auto-toc">
-<li><a class="reference internal" href="#match-blocks" id="id37">8.1.1 Match Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-match-block-syntax" id="id38">8.1.1.1 Extended Match Block Syntax</a></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>
</ul>
</li>
-<li><a class="reference internal" href="#action-blocks" id="id39">8.1.2 Action Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-action-block-syntax" id="id40">8.1.2.1 Extended Action Block Syntax</a></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>
</ul>
</li>
-<li><a class="reference internal" href="#package-rule-examples" id="id41">8.1.3 Package Rule Examples</a></li>
+<li><a class="reference internal" href="#package-rule-examples" id="id42">8.1.3 Package Rule Examples</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#configuration-reference" id="id42">9 Configuration Reference</a><ul class="auto-toc">
-<li><a class="reference internal" href="#misc-options" id="id43">9.1 misc options</a></li>
-<li><a class="reference internal" href="#overlay-options" id="id44">9.2 overlay options</a></li>
-<li><a class="reference internal" href="#other-config-files" id="id45">9.3 other config files</a></li>
-<li><a class="reference internal" href="#logging" id="id46">9.4 logging</a><ul class="auto-toc">
-<li><a class="reference internal" href="#console-logging" id="id47">9.4.1 console logging</a></li>
-<li><a class="reference internal" href="#file-logging" id="id48">9.4.2 file logging</a></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>
</ul>
</li>
-<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id49">9.5 options for debugging, manual dependency rule creation and testing</a></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>
</ul>
</li>
-<li><a class="reference internal" href="#field-definition-config" id="id50">10 Field Definition Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id51">10.1 Example: The default field definition file</a></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>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution-console" id="id52">11 Dependency Resolution Console</a></li>
-<li><a class="reference internal" href="#implementation-overview" id="id53">12 Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#packageinfo" id="id54">12.1 PackageInfo</a></li>
-<li><a class="reference internal" href="#repository-management" id="id55">12.2 Repository Management</a><ul class="auto-toc">
-<li><a class="reference internal" href="#repository" id="id56">12.2.1 Repository</a><ul class="auto-toc">
-<li><a class="reference internal" href="#adding-new-repository-types" id="id57">12.2.1.1 Adding new repository types</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>
</ul>
</li>
-<li><a class="reference internal" href="#overlay" id="id58">12.3 Overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#metadata-creation" id="id59">12.3.1 Metadata Creation</a></li>
-<li><a class="reference internal" href="#manifest-creation" id="id60">12.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#ebuild-creation" id="id61">12.4 Ebuild Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#ebuild-variables" id="id62">12.4.1 Ebuild Variables</a></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>
</ul>
</li>
-<li><a class="reference internal" href="#overlay-creation" id="id63">12.5 Overlay Creation</a></li>
-<li><a class="reference internal" href="#dependency-resolution" id="id64">12.6 Dependency Resolution</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id65">12.6.1 Dependency types</a><ul class="auto-toc">
-<li><a class="reference internal" href="#description-file-dependency-fields" id="id66">12.6.1.1 DESCRIPTION file dependency fields</a></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="#dependency-environments" id="id67">12.6.2 Dependency Environments</a></li>
-<li><a class="reference internal" href="#ebuildjob-channel" id="id68">12.6.3 EbuildJob Channel</a></li>
-<li><a class="reference internal" href="#dependency-rule-pools" id="id69">12.6.4 Dependency Rule Pools</a></li>
-<li><a class="reference internal" href="#dependency-resolver-modules" id="id70">12.6.5 Dependency Resolver Modules</a></li>
-<li><a class="reference internal" href="#dependency-resolver" id="id71">12.6.6 Dependency Resolver</a></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>
+</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>
</ul>
</li>
</ul>
@@ -702,6 +706,16 @@ This option is <strong>required</strong> and can be overridden on the command li
via <tt class="docutils literal"><span class="pre">--field-definition</span> <file></tt>.</p>
<p class="last">Example: FIELD_DEFINITION = ~/roverlay/config/description_fields.conf</p>
</dd>
+<dt>USE_EXPAND_DESC</dt>
+<dd><p class="first">A file that contains USE_EXPAND flag descriptions. This option is not
+required.</p>
+<p class="last">Example: USE_EXPAND_DESC = ~/roverlay/config/useflag/useflag_desc</p>
+</dd>
+<dt>USE_EXPAND_RENAME</dt>
+<dd><p class="first">The value of this option should point to a USE flag remap file which
+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>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.
@@ -751,7 +765,7 @@ they work.</dd>
<dd>See <a class="reference internal" href="#configuration-reference">Configuration Reference</a> for all main config options like log file
rotation and assistance for writing new <em>dependency rules</em>.</dd>
<dt>Field Definition</dt>
-<dd>Refer to <a class="reference internal" href="#id3">Field Definition</a> in case you want to change <em>how</em> R packages
+<dd>Refer to <a class="reference internal" href="#id4">Field Definition</a> in case you want to change <em>how</em> R packages
are being read, e.g. if you want the 'Depents' information field (obviously
a typo) to be understood as 'Depends'.</dd>
</dl>
@@ -954,6 +968,10 @@ and may decide to write <em>p</em>'s ebuild now (or later)</p>
</blockquote>
<ol class="arabic simple" start="6">
<li>write the overlay<ul>
+<li>write/update the profiles dir<ul>
+<li><em>roverlay</em> respects manual changes to USE_EXPAND description files</li>
+</ul>
+</li>
<li>write all ebuilds and apply patches to them
(supports threads on a per package basis)</li>
<li>write the <em>metadata.xml</em> files
@@ -983,6 +1001,8 @@ eclass file are used, the result should look like:</p>
<overlay root>/profiles/categories
<overlay root>/profiles/repo_name
<overlay root>/profiles/use.desc
+<overlay root>/profiles/desc
+<overlay root>/profiles/desc/r_suggests.desc
<overlay root>/sci-R/<many directories per R package>
<overlay root>/sci-R/seewave/
<overlay root>/sci-R/seewave/Manifest
@@ -996,19 +1016,22 @@ eclass file are used, the result should look like:</p>
<dt>Ebuild Template</dt>
<dd><pre class="code text first literal-block">
<ebuild header>
+
+EAPI=<EAPI>
+
inherit <eclass(es)>
DESCRIPTION="<the R package's description>"
SRC_URI="<src uri for the R package>"
-IUSE="${IUSE:-}
- R_suggests
+IUSE="${IUSE-}
+ r_suggests_<flag> r_suggests_<another flag> ...
"
-R_SUGGESTS="<R package suggestions>"
+R_SUGGESTS="r_suggests_<flag>? ( <optional dependency> ) ..."
DEPEND="<build time dependencies for the R package>"
-RDEPEND="${DEPEND:-}
+RDEPEND="${DEPEND-}
<runtime dependencies>
- R_suggests? ( ${R_SUGGESTS} )
+ ${R_SUGGESTS-}
"
_UNRESOLVED_PACKAGES=(<unresolvable, but optional dependencies>)
@@ -1017,6 +1040,9 @@ _UNRESOLVED_PACKAGES=(<unresolvable, but optional dependencies>)
<p>A really minimal ebuild would look like:</p>
<pre class="code text last literal-block">
<ebuild header>
+
+EAPI=<EAPI>
+
inherit <eclass(es)>
SRC_URI="<src uri for the R package>"
@@ -1026,7 +1052,7 @@ SRC_URI="<src uri for the R package>"
<dd><p class="first">The default ebuild header (which cannot be changed) automatically sets
the ebuild's copyright year to 1999-<em><current year></em>.</p>
<pre class="code sh last literal-block">
-<span class="comment"># Copyright 1999-2012 Gentoo Foundation
+<span class="comment"># Copyright 1999-2013 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
</span>
@@ -1036,11 +1062,13 @@ inherit R-packages
<span class="name variable">DESCRIPTION</span><span class="operator">=</span><span class="literal string double">"Time wave analysis and graphical representation"</span>
<span class="name variable">SRC_URI</span><span class="operator">=</span><span class="literal string double">"http://cran.r-project.org/src/contrib/seewave_1.6.4.tar.gz"</span>
-<span class="name variable">IUSE</span><span class="operator">=</span><span class="literal string double">"${IUSE:-}
- R_suggests
+<span class="name variable">IUSE</span><span class="operator">=</span><span class="literal string double">"${IUSE-}
+ r_suggests_sound
+ r_suggests_audio
"</span>
-<span class="name variable">R_SUGGESTS</span><span class="operator">=</span><span class="literal string double">"sci-R/sound
- sci-R/audio
+<span class="name variable">R_SUGGESTS</span><span class="operator">=</span><span class="literal string double">"
+ r_suggests_sound? ( sci-R/sound )
+ r_suggests_audio? ( sci-R/audio )
"</span>
<span class="name variable">DEPEND</span><span class="operator">=</span><span class="literal string double">"sci-R/fftw
sci-R/tuneR
@@ -1048,11 +1076,11 @@ inherit R-packages
sci-R/rpanel
sci-R/rgl
"</span>
-<span class="name variable">RDEPEND</span><span class="operator">=</span><span class="literal string double">"${DEPEND:-}
+<span class="name variable">RDEPEND</span><span class="operator">=</span><span class="literal string double">"${DEPEND-}
media-libs/flac
sci-libs/fftw
media-libs/libsndfile
- R_suggests? ( ${R_SUGGESTS} )
+ ${R_SUGGESTS-}
"</span>
</pre>
</dd>
@@ -1060,7 +1088,7 @@ inherit R-packages
<dd><p class="first">Note the shortened <em>DESCRIPTION</em> variable that points to the <em>metadata.xml</em>
file. This happens if the description is too long.</p>
<pre class="code sh last literal-block">
-<span class="comment"># Copyright 1999-2012 Gentoo Foundation
+<span class="comment"># Copyright 1999-2013 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
</span>
@@ -1070,21 +1098,29 @@ inherit R-packages
<span class="name variable">DESCRIPTION</span><span class="operator">=</span><span class="literal string double">"MetaPCA: Meta-analysis in the Di... (see metadata)"</span>
<span class="name variable">SRC_URI</span><span class="operator">=</span><span class="literal string double">"http://cran.r-project.org/src/contrib/Archive/MetaPCA/MetaPCA_0.1.3.tar.gz"</span>
-<span class="name variable">IUSE</span><span class="operator">=</span><span class="literal string double">"${IUSE:-}
- R_suggests
+<span class="name variable">IUSE</span><span class="operator">=</span><span class="literal string double">"${IUSE-}
+ r_suggests_domc
+ r_suggests_affy
+ r_suggests_ellipse
+ r_suggests_pcapp
+ r_suggests_mass
+ r_suggests_impute
+ r_suggests_dosmp
+ r_suggests_geoquery
"</span>
-<span class="name variable">R_SUGGESTS</span><span class="operator">=</span><span class="literal string double">"sci-R/doMC
- sci-R/affy
- sci-R/ellipse
- sci-R/pcaPP
- sci-R/MASS
- sci-R/impute
- sci-R/doSMP
- sci-R/GEOquery
+<span class="name variable">R_SUGGESTS</span><span class="operator">=</span><span class="literal string double">"
+ r_suggests_domc? ( sci-R/doMC )
+ r_suggests_affy? ( sci-R/affy )
+ r_suggests_ellipse? ( sci-R/ellipse )
+ r_suggests_pcapp? ( sci-R/pcaPP )
+ r_suggests_mass? ( sci-R/MASS )
+ r_suggests_impute? ( sci-R/impute )
+ r_suggests_dosmp? ( sci-R/doSMP )
+ r_suggests_geoquery? ( sci-R/GEOquery )
"</span>
<span class="name variable">DEPEND</span><span class="operator">=</span><span class="literal string double">"sci-R/foreach"</span>
-<span class="name variable">RDEPEND</span><span class="operator">=</span><span class="literal string double">"${DEPEND:-}
- R_suggests? ( ${R_SUGGESTS} )
+<span class="name variable">RDEPEND</span><span class="operator">=</span><span class="literal string double">"${DEPEND-}
+ ${R_SUGGESTS-}
"</span>
<span class="name variable">_UNRESOLVED_PACKAGES</span><span class="operator">=(</span><span class="literal string single">'hgu133plus2.db'</span><span class="operator">)</span>
@@ -2195,6 +2231,10 @@ This will pass '--bwlimit=<value>' to all rsync commands.</p>
<dt>ADDITIONS_DIR:</dt>
<dd>Alias to <a class="reference internal" href="#overlay-additions-dir">OVERLAY_ADDITIONS_DIR</a>.</dd>
</dl>
+<dl class="docutils" id="backup-desc">
+<dt>BACKUP_DESC</dt>
+<dd>Alias to <a class="reference internal" href="#overlay-backup-desc">OVERLAY_BACKUP_DESC</a>.</dd>
+</dl>
<dl class="docutils" id="distdir">
<dt>DISTDIR</dt>
<dd>Alias to <a class="reference internal" href="#overlay-distdir-root">OVERLAY_DISTDIR_ROOT</a>.</dd>
@@ -2207,6 +2247,10 @@ 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="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>
+</dl>
<dl class="docutils" id="eclass">
<dt>ECLASS</dt>
<dd>Alias to <a class="reference internal" href="#overlay-eclass">OVERLAY_ECLASS</a>.</dd>
@@ -2222,6 +2266,13 @@ ebuild patches and hand-written ebuilds. This option is not required.</p>
<p class="last">Defaults to <not set>, which disables this feature.</p>
</dd>
</dl>
+<dl class="docutils" id="overlay-backup-desc">
+<dt>OVERLAY_BACKUP_DESC</dt>
+<dd><p class="first">A <em>bool</em> that indicates whether the description file of the <em>R_SUGGESTS</em>
+USE_EXPAND variable should be backed up before (over-)writing it.</p>
+<p class="last">Defaults to <em>true</em>.</p>
+</dd>
+</dl>
<dl class="docutils" id="overlay-category">
<dt>OVERLAY_CATEGORY</dt>
<dd><p class="first">Sets the category of created ebuilds. There are no value type restrictions
@@ -2341,18 +2392,35 @@ writing.</p>
<p class="last">Defaults to <em>R_Overlay</em>.</p>
</dd>
</dl>
+<dl class="docutils" id="use-expand-name">
+<dt>USE_EXPAND_NAME:</dt>
+<dd>Alias to <a class="reference internal" href="#ebuild-use-expand-name">EBUILD_USE_EXPAND_NAME</a>.</dd>
+</dl>
</div>
<div class="section" id="other-config-files">
<h2><a class="toc-backref" href="#contents">9.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">
-<li>no need for modification in most cases, e.g. the <a class="reference internal" href="#id3">field definition</a> file</li>
+<li>no need for modification in most cases, e.g. the <a class="reference internal" href="#id4">field definition</a> file</li>
<li>special syntax that is not compatible with the main config file,
e.g. the <a class="reference internal" href="#dependency-rule-file-syntax">dependency rule file syntax</a></li>
</ul>
<p>The paths to these files have to be listed in the main config file and
can be overridden with the appropriate command line options.</p>
+<dl class="docutils" id="ebuild-use-expand-desc">
+<dt>EBUILD_USE_EXPAND_DESC</dt>
+<dd><p class="first">Path to a flag description file (for the <em>R_SUGGESTS</em> USE_EXPAND variable).
+The syntax of this file is identical to USE_EXPAND description files
+(<tt class="docutils literal"><overlay <span class="pre">root>/profiles/desc/r_suggests.desc</span></tt>).</p>
+<p class="last">Defaults to <not set>, which disables this option.</p>
+</dd>
+</dl>
+<dl class="docutils" id="ebuild-use-expand-rename">
+<dt>EBUILD_USE_EXPAND_RENAME</dt>
+<dd>Path to a file that lists alternative names for a flag in the <em>R_SUGGESTS</em>
+USE_EXPAND variable.</dd>
+</dl>
<dl class="docutils" id="field-definition">
<dt>FIELD_DEFINITION</dt>
<dd><p class="first">Path to the field definition file that controls how the <em>DESCRIPTION</em> file
@@ -2399,6 +2467,14 @@ much without dependency resolution.</p>
<dt>SIMPLE_RULES_FILES</dt>
<dd>Alias to <a class="reference internal" href="#simple-rules-file">SIMPLE_RULES_FILE</a>.</dd>
</dl>
+<dl class="docutils" id="use-expand-desc">
+<dt>USE_EXPAND_DESC</dt>
+<dd>Alias to <a class="reference internal" href="#ebuild-use-expand-desc">EBUILD_USE_EXPAND_DESC</a>.</dd>
+</dl>
+<dl class="docutils" id="use-expand-rename">
+<dt>USE_EXPAND_RENAME</dt>
+<dd>Alias to <a class="reference internal" href="#ebuild-use-expand-rename">EBUILD_USE_EXPAND_RENAME</a>.</dd>
+</dl>
</div>
<div class="section" id="logging">
<h2><a class="toc-backref" href="#contents">9.4 logging</a></h2>
@@ -2524,8 +2600,44 @@ on <em>roverlay</em> exit. Primarily useful for creating new rules.</p>
</dl>
</div>
</div>
+<div class="section" id="id3">
+<h1><a class="toc-backref" href="#contents">10 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>
+<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>
+<pre class="code text literal-block">
+# comments start with '#'
+
+<effective flag> <runtime flag> [<another runtime flag>...]
+
+# a '=' can be used as separator to improve readability
+<effective flag> = <runtime flag> [<another runtime flag>...]
+
+# the previous line can be continued with leading whitespace
+<effective flag> = <runtime flag>
+ [<another runtime flag>...]
+</pre>
+<p>Example:</p>
+<pre class="code text literal-block">
+# rename 'audio' and 'snd' to 'sound'
+sound = audio snd
+</pre>
+<p>Each flag is renamed at most once, so the following example renames 'sound'
+to media, but 'audio' to 'sound':;</p>
+<pre class="code text literal-block">
+sound = audio snd
+media = sound video
+</pre>
+<div class="caution">
+<p class="first admonition-title">Caution!</p>
+<p class="last">Assigning more than one <em>effective flag</em> to a <em>runtime flag</em> leads to
+unpredictable results.</p>
+</div>
+</div>
<div class="section" id="field-definition-config">
-<span id="id3"></span><h1><a class="toc-backref" href="#contents">10 Field Definition Config</a></h1>
+<span id="id4"></span><h2><a class="toc-backref" href="#contents">10.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>
@@ -2607,7 +2719,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><h2><a class="toc-backref" href="#contents">10.1 Example: The default field definition file</a></h2>
+<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>
<p>This is the default field definition file (without any ignored fields):</p>
<pre class="code ini literal-block">
<span class="keyword">[Description]</span>
@@ -2642,6 +2754,7 @@ such a field is found.</dd>
</pre>
</div>
</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>
<p>As previously stated, the <em>DepRes Console</em> is only meant for <strong>testing</strong>.
@@ -3315,7 +3428,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-06-12.
+Generated on: 2013-06-18.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
2013-06-26 17:29 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
@ 2013-06-30 15:58 ` André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-06-30 15:58 UTC (permalink / raw
To: gentoo-commits
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 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>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
2013-07-03 10:04 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
@ 2013-07-03 10:05 ` André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-07-03 10:05 UTC (permalink / raw
To: gentoo-commits
commit: 88cab2b7a719fe8e327220d3809cf47d92d3fce2
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jul 3 09:58:02 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jul 3 09:58:02 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=88cab2b7
doc/html: SLOT handling
---
doc/html/usage.html | 74 ++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 67 insertions(+), 7 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index c4d90fc..62431a4 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -1484,7 +1484,8 @@ as dev-lang/R:</p>
<dt>Fuzzy Rules</dt>
<dd><p class="first">Fuzzy Rules are <strong>extended Simple Rules</strong>. If the basic lookup
as described above fails for a <em>dependency string</em>,
-they will <em>try</em> to resolve it as a <strong>version-relative match</strong>.</p>
+they will <em>try</em> to resolve it as a <strong>version-relative</strong>,
+<strong>slot-relative</strong> or <strong>version,slot-relative match</strong>.</p>
<p>To do this, the <em>dependency string</em> will be split into components like
<em>dependency name</em>, <em>dependency version</em> and useless comments, which are
discarded.
@@ -1500,7 +1501,7 @@ it will resolve any of these <em>dependency strings</em>:</p>
<li>"R 2.12" as ">=dev-lang/R-2.12"</li>
<li>"The R PROGRAMMING LANGUAGE [<2.14] from <a class="reference external" href="http://www.r-project.org/">http://www.r-project.org/</a>"
as "<dev-lang/R-2.14"</li>
-<li>"R ( !2.10 )" as "( !=dev-lang/R-2.10 dev-lang/R )"</li>
+<li>"R ( !=2.10 )" as "( !=dev-lang/R-2.10 dev-lang/R )"</li>
</ul>
</dd>
</dl>
@@ -1514,7 +1515,7 @@ See <a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a>
<dl class="docutils">
<dt>Example 1 - <em>default</em> fuzzy rule</dt>
<dd><p class="first">A rule that matches many dependencies on dev-lang/R, for example
-"r 2.12", "R(>= 2.14)", "R [<2.10]", "r{ !2.12 }", and "R", and
+"r 2.12", "R(>= 2.14)", "R [<2.10]", "r{ !=2.12 }", and "R", and
resolves them as '>=dev-lang/R-2.12', '>=dev-lang/R-2.14',
'<dev-lang/R-2.10', etc.:</p>
<pre class="code text last literal-block">
@@ -1558,6 +1559,32 @@ in some R package DESCRIPTION files.</p>
}
</pre>
</dd>
+<dt>Example 5 - fuzzy slot rule</dt>
+<dd><p class="first">A rule that matches many dependencies on sci-libs/fftw and resolves them
+as slotted depencency. The <tt class="docutils literal"><span class="pre">s=<range></span></tt> option controls which parts of the
+version (from the dependency string) are relevant for calculating the
+slot. The following example resolves "fftw 2.1", "fftw 2.1.2" and
+"fftw 2.1.3" as "sci-libs/fftw:2.1", "fftw 3.0" as "sci-libs/fftw:3.0"
+and so on:</p>
+<pre class="code text last literal-block">
+~sci-libs/fftw:s=0..1 :: fftw
+</pre>
+</dd>
+<dt>Example 6 - slot-restricted fuzzy slot rule</dt>
+<dd><p class="first">Similar to example 5, but this rule does not resolve anything unless the
+calculated slot is allowed.</p>
+<pre class="code text last literal-block">
+~sci-libs/fftw:s=0..1:restrict=2.1,3.0: :: fftw
+</pre>
+</dd>
+<dt>Example 7 - slot-restricted fuzzy slot rule with <em>immediate</em> value</dt>
+<dd><p class="first">Example 6 is not quite correct, as sci-libs/fftw currently uses slot 3.0
+for various versions from the 3.x range. The following rule resolves
+"fftw 3.0", ..., "fftw 3.3" as "sci-libs/fftw:3.0":</p>
+<pre class="code text last literal-block">
+~sci-libs/fftw:s=i3.0:restrict=3.0,3.1,3.2,3.3 :: fftw
+</pre>
+</dd>
</dl>
<p>Please see the default rule files for more extensive examples that cover
other aspects like limiting a rule to certain dependency types.
@@ -1624,7 +1651,7 @@ Use braces <em>( ~... )</em> to work around that.</p>
<dl class="last docutils">
<dt>Syntax:</dt>
<dd><pre class="code text first last literal-block">
-[<keychar>]<dependency> :: <dependency string>
+[<keychar>]<dependency>[<rule options>] :: <dependency string>
</pre>
</dd>
</dl>
@@ -1636,7 +1663,7 @@ Their rule block begins with '{' + newline, followed by one
<dl class="docutils">
<dt>Syntax:</dt>
<dd><pre class="code text first last literal-block">
-[<keychar>]<dependency> {
+[<keychar>]<dependency>[<rule options>] {
<dependency string>
[<dependency string>]
...
@@ -1651,6 +1678,39 @@ zero or more <em>dependency strings</em>. An empty rule makes little sense,
though.</p>
</div>
</dd>
+<dt>Rule Options</dt>
+<dd>Certain rule types accept options that control the rule's behavior.
+For example, <em>default</em> fuzzy rules can be set up to yield slotted
+dependencies.</dd>
+<dt>Fuzzy Slot Rules</dt>
+<dd><p class="first">Fuzzy Slot rules are a subtype of <em>default</em> fuzzy rules. Appending a colon
+character <tt class="docutils literal">:</tt> to the <em>dependency string</em> of a fuzzy rule
+(as <em>rule option</em>) turns it into a slot rule.</p>
+<p>Fuzzy slot rules accept even more options, each of them separated by one
+colong char <tt class="docutils literal">:</tt>:</p>
+<ul class="simple">
+<li>slot mode:<ul>
+<li><tt class="docutils literal">default</tt>: calculate a slot value (<tt class="docutils literal"><span class="pre"><cat>/<pkg>:<SLOT></span></tt>)</li>
+<li><tt class="docutils literal">with_version</tt> or <tt class="docutils literal">+v</tt>: include version, too (<tt class="docutils literal"><span class="pre">=<cat>/<pkg>-<pkgver>:<SLOT></span></tt>)</li>
+<li><tt class="docutils literal">open</tt>: non-versioned slot (<tt class="docutils literal"><span class="pre"><cat>/<pkg>:*</span></tt> or <tt class="docutils literal"><span class="pre"><cat>/<pkg>:=</span></tt>)</li>
+</ul>
+</li>
+<li>accepted <em>calculated</em> slot values can be restricted with
+<tt class="docutils literal"><span class="pre">restrict=<list</span> of accepted values</tt> or <tt class="docutils literal"><span class="pre">r=<list></span></tt></li>
+<li>relevant slot parts can be set with <tt class="docutils literal"><span class="pre">slotparts=<selection></span></tt> or
+<tt class="docutils literal"><span class="pre">s=<selection></span></tt></li>
+<li>relevant subslot parts can be set with <tt class="docutils literal"><span class="pre">subslotparts=<selection></span></tt> or
+<tt class="docutils literal">/<selection></tt></li>
+<li>slot operator can be set to <tt class="docutils literal">*</tt> or <tt class="docutils literal">=</tt></li>
+</ul>
+<p><tt class="docutils literal"><selection></tt> can be an index (integer) range
+<tt class="docutils literal"><span class="pre">[<low>:=0]..[<high>:=<low>]</span></tt> or a fixed value <tt class="docutils literal">i<value></tt>.</p>
+<div class="note last">
+<p class="first admonition-title">Note</p>
+<p class="last">Fuzzy Slot rules cannot resolve "not <version>" statements, e.g.
+"R ( != 2.14 )".</p>
+</div>
+</dd>
<dt>Comments</dt>
<dd>start with <strong>#</strong>. There are a few exceptions to that, the <em>#deptype</em> and
<em>#! NOPARSE</em> keywords. Comments inside rule blocks are not allowed and
@@ -1689,7 +1749,7 @@ as <em>sci-R/zoo</em>. This rule can be written as a single word, <em>zoo</em>.<
<dl class="last docutils">
<dt>Syntax:</dt>
<dd><pre class="code text first last literal-block">
-[<keychar>]<short dependency>
+[<keychar>]<short dependency>[<rule options>]
</pre>
</dd>
</dl>
@@ -3933,7 +3993,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-06-26.
+Generated on: 2013-07-03.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-07-10 16:16 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-07-10 16:16 UTC (permalink / raw
To: gentoo-commits
commit: 24965cc5a306d732cb88ec6eb2ab1fb08bd002dd
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jul 10 15:09:31 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jul 10 15:09:31 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=24965cc5
recreate doc/html
---
doc/html/usage.html | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 62431a4..0745d2c 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -1301,7 +1301,7 @@ excerpt from <a class="reference external" href="http://www.omegahat.org/R/src/c
<span class="name attribute">type</span> <span class="operator">=</span> <span class="literal string">websync_repo</span>
<span class="name attribute">src_uri</span> <span class="operator">=</span> <span class="literal string">http://www.omegahat.org/R/src/contrib</span>
<span class="name attribute">digest</span> <span class="operator">=</span> <span class="literal string">md5</span>
-<span class="comment">#digest = none</span>
+<span class="comment single">#digest = none</span>
</pre>
<p>This repo type extends the default options by:</p>
<ul class="simple">
@@ -3993,7 +3993,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-07-03.
+Generated on: 2013-07-10.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
2013-07-16 16:35 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
@ 2013-07-16 16:36 ` André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-07-16 16:36 UTC (permalink / raw
To: gentoo-commits
commit: 13ae75011982063640f369c29bcd65a02b5a1325
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Jul 16 16:33:48 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Jul 16 16:33:48 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=13ae7501
doc/html: api, manifest creation
---
doc/html/usage.html | 270 ++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 197 insertions(+), 73 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 0745d2c..91453b8 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -428,35 +428,42 @@ ul.auto-toc {
</ul>
</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>
+<li><a class="reference internal" href="#roverlay-interface" id="id66">13 Roverlay Interface</a><ul class="auto-toc">
+<li><a class="reference internal" href="#depres-interface" id="id67">13.1 DepRes Interface</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#implementation-overview" id="id68">14 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id69">14.1 PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id70">14.2 Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#repository" id="id71">14.2.1 Repository</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id72">14.2.1.1 Adding new repository types</a></li>
</ul>
</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="#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>
+<li><a class="reference internal" href="#overlay" id="id73">14.3 Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id74">14.3.1 Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id75">14.3.2 Manifest Creation</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>
+<li><a class="reference internal" href="#ebuild-creation" id="id76">14.4 Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id77">14.4.1 Ebuild Variables</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>
+<li><a class="reference internal" href="#overlay-creation" id="id78">14.5 Overlay Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#selfdep-validation" id="id79">14.5.1 Selfdep Validation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dependency-resolution" id="id80">14.6 Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id81">14.6.1 Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id82">14.6.1.1 DESCRIPTION file dependency fields</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dependency-environments" id="id83">14.6.2 Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id84">14.6.3 EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id85">14.6.4 Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id86">14.6.5 Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id87">14.6.6 Dependency Resolver</a></li>
</ul>
</li>
</ul>
@@ -521,11 +528,13 @@ references to other chapters (4-10) where required.</p>
</li>
<li><p class="first">argparse (<a class="reference external" href="http://code.google.com/p/argparse">http://code.google.com/p/argparse</a>)</p>
</li>
+<li><p class="first">setuptools (<a class="reference external" href="http://pypi.python.org/pypi/setuptools">http://pypi.python.org/pypi/setuptools</a>)</p>
+</li>
<li><p class="first">rsync (for using rsync repositories)</p>
</li>
<li><p class="first">for Manifest creation:</p>
<ul class="simple">
-<li>portage (<em>ebuild</em> and/or the <em>portage libs</em> directly)</li>
+<li>portage (<em>ebuild</em>)</li>
<li><em>true</em> or <em>echo</em> from coreutils or busybox for preventing
package downloads during Manifest creation (optional)</li>
</ul>
@@ -550,7 +559,7 @@ write mechanism in use. The amount can be halved (approximately) when
using a slower one.</p>
</dd>
<dt>time</dt>
-<dd><p class="first last">Expect 3-6h execution time for the first run, depending on computing
+<dd><p class="first last">Expect 1h execution time for the first run, depending on computing
and I/O speed. <em>roverlay</em> is able to work in incremental mode,
thus making subsequent runs need a lot less time.</p>
</dd>
@@ -637,6 +646,15 @@ directory. An example config file is available in the
<p>The config file is a text file with '<option> = <value>' syntax. Some options
accept multiple values (e.g. <option> = file1, file2), in which case the
values have to be enclosed with quotes (-> <tt class="docutils literal"><option> = "file1 file2"</tt>).</p>
+<p>If roverlay has been installed, then <tt class="docutils literal">emerge <span class="pre">--config</span> roverlay</tt> can be
+used to set up the config file as well as to create essential directories.
+It can be run multiple times in order to configure roverlay for more than
+one user.</p>
+<div class="important">
+<p class="first admonition-title">Important</p>
+<p class="last"><tt class="docutils literal">emerge <span class="pre">--config</span> roverlay</tt> will overwrite the user's config file (or
+/etc/roverlay/R-overlay.conf when configuring for root).</p>
+</div>
<p>The following options should be set before running <em>roverlay</em>:</p>
<blockquote>
<dl class="docutils">
@@ -761,6 +779,10 @@ Leaving this option as-is (<em>enabled</em>) is recommended if you want to use
DISTDIR as package mirror.</p>
<p class="last">Example: DISTDIR_FLAT = yes</p>
</dd>
+<dt>PORTDIR</dt>
+<dd><p class="first">Portage directory, which is used to scan for valid licenses.</p>
+<p class="last">Example: PORTDIR = /usr/portage</p>
+</dd>
</dl>
</blockquote>
<p>There is another option that is useful for creating new dependency rules,
@@ -978,6 +1000,9 @@ while those from 'Suggests' are optional)</p>
</li>
<li><p class="first"><strong>immediately stop</strong> processing <em>p</em> if a <em>required</em> dependency
cannot be resolved in which case a valid ebuild cannot be created</p>
+</li>
+<li><p class="first">verify dependencies on packages found in the overlay, whether their
+ebuilds already exist or not (<em>selfdep validation</em>)</p>
<p>See also: <a class="reference internal" href="#dependency-resolution">Dependency Resolution</a></p>
</li>
</ul>
@@ -1437,11 +1462,6 @@ ${CATEGORY}/${PN}/${PF}.ebuild
<p>Ebuilds imported that way can not be overwritten by generated ebuilds and
benefit from most overlay creation features, e.g. Manifest file creation.
However, they cannot be used for metadata creation.</p>
-<div class="important">
-<p class="first admonition-title">Important</p>
-<p class="last">Importing ebuilds is only supported by the default Manifest implementation
-(<em>ebuildmanifest</em>).</p>
-</div>
</div>
</div>
<div class="section" id="dependency-rules">
@@ -1622,7 +1642,15 @@ with the specified <em>dependency type</em>.</p>
<li><em>all</em> (no type restrictions)</li>
<li><em>pkg</em> (resolve only R package dependencies)</li>
<li><em>sys</em> (resolve only system dependencies)</li>
+<li><em>selfdep</em> (subtype: dependency is part of the overlay, see selfdep below)</li>
</ul>
+<p>The dependency type can also be a comma-separated list of the listed types.
+Actually, <em>all</em> is an abbreviated version of <tt class="docutils literal">pkg,sys</tt>.
+Specifying <em>selfdep</em> alone does not resolve anything.</p>
+<div class="hint">
+<p class="first admonition-title">Hint</p>
+<p class="last">Check the <em>dependency type</em> if a newly added rule has no effect.</p>
+</div>
<p class="last">The other keyword is <em>#! NOPARSE</em> which stops parsing of a rule file.</p>
</dd>
<dt>Dependencies</dt>
@@ -1716,29 +1744,32 @@ colong char <tt class="docutils literal">:</tt>:</p>
<em>#! NOPARSE</em> keywords. Comments inside rule blocks are not allowed and
will be read as normal <em>dependency strings</em>.</dd>
<dt>Selfdep</dt>
-<dd><p class="first">This is another name for <em>dependency strings</em> that are resolved by an
-R package with the same name, which is also part of the overlay being
-created.</p>
-<p>Example: <em>zoo</em> is resolved as <em>sci-R/zoo</em>, assuming that <a class="reference internal" href="#overlay-category">OVERLAY_CATEGORY</a>
-is set to <em>sci-R</em></p>
-<p>Writing selfdep rules is not necessary since <em>roverlay</em> automatically
-creates rules for all known R packages (see <a class="reference internal" href="#dynamic-selfdep-rule-pool">Dynamic Selfdep Rule Pool</a>
-for details).</p>
+<dd><p class="first">This is a classification for dependencies on packages which are also part
+of the overlay being created. Typically, selfdeps refer to other R
+packages, but there may be a few exceptions.</p>
+<p>roverlay validates <em>selfdeps</em> during overlay creation, which is the most
+significant difference to non-<em>selfdeps</em>.</p>
+<p>Selfdep rules can be written by prefixing a single rule with <tt class="docutils literal">@selfdep</tt>
+(in a separate text line) or by adding <tt class="docutils literal">selfdep</tt> to the dependency rule
+type.</p>
+<p>There is a second variant of selfdeps, <em>true selfdeps</em>, which resolve
+a <em>dependency string</em> as R package with the same name.</p>
+<p>Example: <em>zoo</em> is resolved as <em>sci-R/zoo</em>, assuming that
+<a class="reference internal" href="#overlay-category">OVERLAY_CATEGORY</a> is set to <em>sci-R</em>.</p>
+<p>Writing such selfdep rules is not necessary since <em>roverlay</em> automatically
+creates rules for all known R packages at runtime (see
+<a class="reference internal" href="#dynamic-selfdep-rule-pool">Dynamic Selfdep Rule Pool</a> for details).</p>
<p>There are a few exceptions to that in which case selfdep rules have to
be written:</p>
<ul class="simple">
<li>The <em>dependency string</em> is assumed to be a system dependency (not an
R package). This is likely a "bug" in the DESCRIPTION file of the
R package being processed.</li>
-<li>The R package name is not ebuild-name compliant (e.g. contains the '.'
-char, which is remapped to '_'.).
-Most <em>char remap</em> cases are handled properly, but there may be a few
-exceptions.</li>
</ul>
<div class="caution last">
<p class="first admonition-title">Caution!</p>
-<p class="last">Writing unnecessary selfdep rules slows dependency resolution down!
-Each rule will exist twice, once as <em>dynamic</em> rule and once as
+<p class="last">Writing unnecessary <em>true selfdep</em> rules slows dependency resolution
+down! Each rule will exist twice, once as <em>dynamic</em> rule and once as
the written one.</p>
</div>
</dd>
@@ -2676,8 +2707,7 @@ restrictions. Commenting it out is safe.</dd>
<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>
+<p class="last">This option is <strong>required</strong>.</p>
</dd>
</dl>
<dl class="docutils" id="distfiles">
@@ -2899,10 +2929,11 @@ per R package. All others will be removed.</p>
<dl class="docutils" id="overlay-manifest-implementation">
<dt>OVERLAY_MANIFEST_IMPLEMENTATION</dt>
<dd><p class="first">Sets the implementation that will be used for Manifest file writing.
-Available choices are <em>ebuild</em>, <em>portage</em>, <em>default</em> and <em>none</em>.
-Defaults to <em>default</em> (-> <em>ebuild</em>).
-<em>portage</em> is highly experimental and therefore not recommended
-for production usage.</p>
+Available choices are <em>ebuild</em>, <em>next</em>, <em>default</em> and <em>none</em>.
+Defaults to <em>default</em> (-> <em>next</em>).</p>
+<p><em>next</em> is an mostly internal implementation that is considerably faster
+than <em>ebuild</em>. <em>ebuild</em> is still used when creating Manifest files for
+imported ebuilds.</p>
<div class="note last">
<p class="first admonition-title">Note</p>
<p class="last">Choosing 'none' is destructive - <em>roverlay</em> will fail to function
@@ -3263,6 +3294,12 @@ by ',' and/or ';'.</dd>
<dd>Declares that a field's value is a list whose values are separated by
whitespace. Has no effect if <cite>field flag: isList</cite> is set.</dd>
</dl>
+<dl class="docutils" id="field-flag-islicense">
+<dt>isLicense</dt>
+<dd>Declares that a field's value should be interpreted as license string.
+This disables <em>allowed_value</em>/<em>allowed_values</em> and all other flags
+except for <em>mandatory</em>/<em>optional</em>.</dd>
+</dl>
<dl class="docutils" id="mandatory-field-flag">
<span id="field-flag-mandatory"></span><dt>mandatory</dt>
<dd>Declares that a field is required in <em>all</em> DESCRIPTION files.
@@ -3478,14 +3515,79 @@ cmd % exit
</dd>
</dl>
</div>
+<div class="section" id="roverlay-interface">
+<h1><a class="toc-backref" href="#contents">13 Roverlay Interface</a></h1>
+<p>Roverlay provides an API for accessing its functionality independently of
+R overlay creation. Only dependency resolution is available, currently.</p>
+<p>Note, however, that a minimal config file may still be required for accessing
+<em>roverlay interfaces</em>.</p>
+<p>The table below lists all interfaces and where to find them:</p>
+<table border="1" class="docutils">
+<caption>roverlay interfaces</caption>
+<colgroup>
+<col width="23%" />
+<col width="37%" />
+<col width="40%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">name</th>
+<th class="head">module</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>RootInterface</td>
+<td>roverlay.interface.root</td>
+<td>meta interface for managing
+other interfaces</td>
+</tr>
+<tr><td>MainInterface</td>
+<td>roverlay.interface.main</td>
+<td>RootInterface with delayed
+initialization</td>
+</tr>
+<tr><td>DepresInterface</td>
+<td>roverlay.interface.depres</td>
+<td>dependency resolution</td>
+</tr>
+</tbody>
+</table>
+<p>For extending the API, roverlay provides the abstract <em>RoverlayInterface</em> and
+<em>RoverlaySubInterface</em> classes.</p>
+<div class="section" id="depres-interface">
+<h2><a class="toc-backref" href="#contents">13.1 DepRes Interface</a></h2>
+<p>The <em>DepResInterface</em> offers the following functionality:</p>
+<ul class="simple">
+<li>rule creation<ul>
+<li>load rules from text input, files and/or configured files (<a class="reference internal" href="#simple-rules-file">SIMPLE_RULES_FILE</a>)</li>
+<li><em>compile</em> rules after loading them</li>
+</ul>
+</li>
+<li>manage dependency rule pools (container for rules)<ul>
+<li>rule pools are kept in a stack-like data structure, which makes it easy
+to "forget" the most recent rules (<em>discard_pool()</em> et al.)</li>
+<li><em>visualize</em> pools: convert rules into text (inverse of rule creation)</li>
+</ul>
+</li>
+<li>easy access to the resolver via <em>resolve()</em>, <em>can_resolve()</em>
+and <em>cannot_resolve()</em></li>
+<li>"low-level" access to dependency resolution, e.g. <em>EbuildJobChannels</em>, is
+also possible</li>
+</ul>
+<p>Refer to in-code documentation on how to use this interface.
+See the dependency resolution test suite for a usage example
+(<tt class="docutils literal">tests.depres</tt>, not part of the roverlay installation).
+(The depres console is also a candidate for using this interface in future.)</p>
+</div>
+</div>
<div class="section" id="implementation-overview">
-<h1><a class="toc-backref" href="#contents">13 Implementation Overview</a></h1>
+<h1><a class="toc-backref" href="#contents">14 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">13.1 PackageInfo</a></h2>
+<h2><a class="toc-backref" href="#contents">14.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>
@@ -3506,7 +3608,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">13.2 Repository Management</a></h2>
+<h2><a class="toc-backref" href="#contents">14.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>
@@ -3517,7 +3619,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">13.2.1 Repository</a></h3>
+<h3><a class="toc-backref" href="#contents">14.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,
@@ -3558,7 +3660,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">13.2.1.1 Adding new repository types</a></h4>
+<h4><a class="toc-backref" href="#contents">14.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.
@@ -3645,7 +3747,7 @@ to be accessible.</p>
</div>
</div>
<div class="section" id="overlay">
-<h2><a class="toc-backref" href="#contents">13.3 Overlay</a></h2>
+<h2><a class="toc-backref" href="#contents">14.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>
@@ -3676,7 +3778,7 @@ level</p>
</li>
</ul>
<div class="section" id="metadata-creation">
-<h3><a class="toc-backref" href="#contents">13.3.1 Metadata Creation</a></h3>
+<h3><a class="toc-backref" href="#contents">14.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
@@ -3685,16 +3787,21 @@ 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">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
-package files are passed in the PORTAGE_RO_DISTDIRS variable and DISTDIR
-is set to <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>/__tmp__.</p>
+<h3><a class="toc-backref" href="#contents">14.3.2 Manifest Creation</a></h3>
+<p>Two implementations for writing manifest files are available, <em>ebuild</em> and
+<em>next</em>.</p>
+<p>The <em>ebuild</em> implementation calls the <tt class="docutils literal">ebuild</tt> executable for each package
+directory in a filtered environment where where FETCHCOMMAND and
+RESUMECOMMAND are set to no-operation (/bin/true on systems that support it).</p>
+<p><em>next</em> is an internal implementation that uses the
+<tt class="docutils literal">roverlay.overlay.pkgdir.manifest</tt> module for creating Manifest files.
+It falls back to <em>ebuild</em> when creating Manifest entries for imported ebuilds,
+since roverlay does not support reading <em>SRC_URI</em> from ebuilds reliably (that
+would require variable interpolation, e.g. for <tt class="docutils literal">${PN}</tt>).</p>
</div>
</div>
<div class="section" id="ebuild-creation">
-<h2><a class="toc-backref" href="#contents">13.4 Ebuild Creation</a></h2>
+<h2><a class="toc-backref" href="#contents">14.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>
@@ -3702,6 +3809,13 @@ that tries to create an ebuild for it.</p>
<li>Read the DESCRIPTION file of <em>p</em> R package tarball and stores the
data in an associative array ('DESCRIPTION field' -> 'data')</li>
<li>Call <a class="reference internal" href="#dependency-resolution">dependency resolution</a></li>
+<li>If dependency resolution was successful and any <em>selfdeps</em> found
+(dependencies on other packages): <em>pause</em> ebuild creation for <em>p</em> until
+it has been verified whether these dependencies are satisfiable.
+This is necessary because dependency resolution does not know whether a
+resolved dependency is actually valid. To realize this, <em>roverlay</em> collects
+paused ebuild creation jobs after processing all packages, performs
+<em>selfdep validation</em> and then continues ebuild creation.</li>
<li>If dependency resolution was successful, dependency ebuild variables are
created (<em>DEPEND</em>, <em>RDEPEND</em> and <em>R_SUGGESTS</em>, also <em>IUSE</em>, <em>MISSINGDEPS</em>).
Otherwise <strong>ebuild creation stops</strong> and <em>p</em> is marked as
@@ -3713,7 +3827,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">13.4.1 Ebuild Variables</a></h3>
+<h3><a class="toc-backref" href="#contents">14.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
@@ -3721,7 +3835,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">13.5 Overlay Creation</a></h2>
+<h2><a class="toc-backref" href="#contents">14.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.
@@ -3733,9 +3847,13 @@ for a <em>PackageInfo</em> object and inform the <em>OverlayCreation</em> about
afterwards. Overlay creation keeps going if an ebuild cannot be created,
instead the event is logged. Running more than one <em>OverlayWorker</em> in parallel
is possible.</p>
+<div class="section" id="selfdep-validation">
+<h3><a class="toc-backref" href="#contents">14.5.1 Selfdep Validation</a></h3>
+<p><<TODO: specify algo here>></p>
+</div>
</div>
<div class="section" id="dependency-resolution">
-<h2><a class="toc-backref" href="#contents">13.6 Dependency Resolution</a></h2>
+<h2><a class="toc-backref" href="#contents">14.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
@@ -3757,7 +3875,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">13.6.1 Dependency types</a></h3>
+<h3><a class="toc-backref" href="#contents">14.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">
@@ -3772,6 +3890,12 @@ be resolved.</dd>
<dt>System Dependency</dt>
<dd>This declares that the <em>dependency string</em> could be a system dependency,
e.g. a scientific library or a video encoder.</dd>
+<dt>Selfdep</dt>
+<dd>This declares that the resolved dependency has to pass
+<em>selfdep validation</em>. While <em>selfdep</em> usually implies <em>package</em>, these
+types are not the same. The <em>package</em> type is applied to <em>dependency strings</em>
+based on their origin (DESCRIPTION field), whereas <em>selfdep</em> is a property
+of the resolving rule.</dd>
<dt>Try other dependency types</dt>
<dd>This declares that the <em>dependency string</em> can be resolved by ignoring its
dependency type partially. This property allows to resolve package
@@ -3786,7 +3910,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">13.6.1.1 DESCRIPTION file dependency fields</a></h4>
+<h4><a class="toc-backref" href="#contents">14.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>
@@ -3845,7 +3969,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">13.6.2 Dependency Environments</a></h3>
+<h3><a class="toc-backref" href="#contents">14.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
@@ -3855,7 +3979,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">13.6.3 EbuildJob Channel</a></h3>
+<h3><a class="toc-backref" href="#contents">14.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>
@@ -3892,7 +4016,7 @@ dependencies are unresolvable.</li>
</ol>
</div>
<div class="section" id="dependency-rule-pools">
-<h3><a class="toc-backref" href="#contents">13.6.4 Dependency Rule Pools</a></h3>
+<h3><a class="toc-backref" href="#contents">14.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>
@@ -3910,12 +4034,12 @@ consist of rules that exist in memory only.
These are called <strong>Dynamic Rule Pools</strong> and use runtime data like "all known
R packages" to create rules.</p>
<p id="dynamic-selfdep-rule-pool"><em>roverlay</em> uses one dynamic rule pool, the <strong>Dynamic Selfdep Rule Pool</strong>.
-This pool contains rules for all known R packages and is able to resolve
-R package dependencies.
+This pool contains <em>selfdep</em> rules for all known R packages and is able
+to resolve 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">13.6.5 Dependency Resolver Modules</a></h3>
+<h3><a class="toc-backref" href="#contents">14.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">
@@ -3935,7 +4059,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">13.6.6 Dependency Resolver</a></h3>
+<h3><a class="toc-backref" href="#contents">14.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
@@ -3993,7 +4117,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-07-10.
+Generated on: 2013-07-16.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-07-23 14:57 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-07-23 14:57 UTC (permalink / raw
To: gentoo-commits
commit: ba90ce8d9faceed63e8f012657c956bac22bc8db
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Jul 23 14:31:00 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Jul 23 14:31:00 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=ba90ce8d
doc/html: "fix" example 3 in dependency rules
---
doc/html/usage.html | 13 +++++--------
1 file changed, 5 insertions(+), 8 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 91453b8..2dbe25f 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -1556,14 +1556,11 @@ be resolved. See <em>Selfdep</em> in <a class="reference internal" href="#rule-f
</div>
</dd>
<dt>Example 3 - <em>default</em> simple rule</dt>
-<dd><p class="first">A rule that matches several <em>dependency strings</em> and resolves them
-as "sci-libs/gdal and sci-libs/proj":</p>
+<dd><p class="first">A rule that matches a <em>dependency string</em> and resolves it
+as "virtual/blas and virtual/lapack":</p>
<pre class="code text last literal-block">
-( sci-libs/gdal sci-libs/proj ) {
- for building from source: GDAL >= 1.3.1 && GDAL < 1.6.0 (until tested) library and PROJ.4 (proj >= 4.4.9)
- for building from source: GDAL >= 1.3.1 library and PROJ.4 (proj >= 4.4.9)
- for building from source: GDAL >= 1.3.1 library and PROJ.4(proj >= 4.4.9)
- for building from source: GDAL >= 1.6.0 library and PROJ.4(proj >= 4.4.9)
+( virtual/blas virtual/lapack ) {
+ BLAS/LAPACK libraries
}
</pre>
</dd>
@@ -4117,7 +4114,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-07-16.
+Generated on: 2013-07-23.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-08-02 14:30 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-08-02 14:30 UTC (permalink / raw
To: gentoo-commits
commit: edd0452a932e4fb0e063fd3c3aff11826bca6cfe
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Aug 2 14:29:39 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Aug 2 14:29:39 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=edd0452a
update doc/html/usage.html
---
doc/html/usage.html | 469 +++++++++++++++++++++++++++++++++++++---------------
1 file changed, 335 insertions(+), 134 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 2dbe25f..16fbbe9 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -329,141 +329,147 @@ ul.auto-toc {
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#introduction" id="id5">1 Introduction</a></li>
-<li><a class="reference internal" href="#installation" id="id6">2 Installation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#prerequisites" id="id7">2.1 Prerequisites</a></li>
-<li><a class="reference internal" href="#via-emerge-gentoo" id="id8">2.2 via emerge (Gentoo)</a></li>
-<li><a class="reference internal" href="#manual-installation" id="id9">2.3 Manual Installation</a></li>
-<li><a class="reference internal" href="#using-roverlay-without-installation" id="id10">2.4 Using <em>roverlay</em> without installation</a></li>
+<li><a class="reference internal" href="#introduction" id="id6">1 Introduction</a></li>
+<li><a class="reference internal" href="#installation" id="id7">2 Installation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#prerequisites" id="id8">2.1 Prerequisites</a></li>
+<li><a class="reference internal" href="#via-emerge-gentoo" id="id9">2.2 via emerge (Gentoo)</a></li>
+<li><a class="reference internal" href="#manual-installation" id="id10">2.3 Manual Installation</a></li>
+<li><a class="reference internal" href="#using-roverlay-without-installation" id="id11">2.4 Using <em>roverlay</em> without installation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-roverlay" id="id11">3 Running Roverlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#required-configuration-steps" id="id12">3.1 Required configuration steps</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id13">3.1.1 Extended Configuration / Where to go from here?</a></li>
+<li><a class="reference internal" href="#running-roverlay" id="id12">3 Running Roverlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#required-configuration-steps" id="id13">3.1 Required configuration steps</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id14">3.1.1 Extended Configuration / Where to go from here?</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-it" id="id14">3.2 Running it</a></li>
-<li><a class="reference internal" href="#providing-a-package-mirror" id="id15">3.3 Providing a package mirror</a></li>
+<li><a class="reference internal" href="#running-it" id="id15">3.2 Running it</a></li>
+<li><a class="reference internal" href="#providing-a-package-mirror" id="id16">3.3 Providing a package mirror</a></li>
+<li><a class="reference internal" href="#roverlay-helpers" id="id17">3.4 roverlay helpers</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#basic-implementation-overview" id="id16">4 Basic Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-roverlay-works" id="id17">4.1 How <em>roverlay</em> works</a></li>
-<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id18">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#expected-ebuild-result" id="id19">4.2.1 Expected Ebuild Result</a></li>
-<li><a class="reference internal" href="#expected-metadata-xml-result" id="id20">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
+<li><a class="reference internal" href="#basic-implementation-overview" id="id18">4 Basic Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#how-roverlay-works" id="id19">4.1 How <em>roverlay</em> works</a></li>
+<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id20">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#expected-ebuild-result" id="id21">4.2.1 Expected Ebuild Result</a></li>
+<li><a class="reference internal" href="#expected-metadata-xml-result" id="id22">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#repositories-getting-packages" id="id21">5 Repositories / Getting Packages</a><ul class="auto-toc">
-<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id22">5.1 A word about repo config files</a></li>
-<li><a class="reference internal" href="#rsync-repos" id="id23">5.2 Rsync repos</a></li>
-<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>
+<li><a class="reference internal" href="#repositories-getting-packages" id="id23">5 Repositories / Getting Packages</a><ul class="auto-toc">
+<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id24">5.1 A word about repo config files</a></li>
+<li><a class="reference internal" href="#rsync-repos" id="id25">5.2 Rsync repos</a></li>
+<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id26">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="id27">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="id28">5.5 Using local directories</a></li>
+<li><a class="reference internal" href="#distmap" id="id29">5.6 distmap</a></li>
</ul>
</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>
+<li><a class="reference internal" href="#additions-directory" id="id30">6 Additions Directory</a><ul class="auto-toc">
+<li><a class="reference internal" href="#patching-ebuilds" id="id31">6.1 Patching ebuilds</a></li>
+<li><a class="reference internal" href="#importing-ebuilds" id="id32">6.2 Importing ebuilds</a></li>
</ul>
</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>
+<li><a class="reference internal" href="#dependency-rules" id="id33">7 Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#simple-dependency-rules" id="id34">7.1 Simple Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#rule-variants" id="id35">7.1.1 Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id36">7.1.2 Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id37">7.1.3 Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id38">7.1.4 Rule File Syntax</a></li>
</ul>
</li>
</ul>
</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>
+<li><a class="reference internal" href="#package-rules" id="id39">8 Package Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#package-rule-file-syntax" id="id40">8.1 Package Rule File Syntax</a><ul class="auto-toc">
+<li><a class="reference internal" href="#match-blocks" id="id41">8.1.1 Match Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-match-block-syntax" id="id42">8.1.1.1 Extended Match Block Syntax</a></li>
</ul>
</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>
+<li><a class="reference internal" href="#action-blocks" id="id43">8.1.2 Action Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-action-block-syntax" id="id44">8.1.2.1 Extended Action Block Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#package-rule-examples" id="id43">8.1.3 Package Rule Examples</a></li>
+<li><a class="reference internal" href="#package-rule-examples" id="id45">8.1.3 Package Rule Examples</a></li>
</ul>
</li>
</ul>
</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>
+<li><a class="reference internal" href="#event-hooks" id="id46">9 Event Hooks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#default-event-script" id="id47">9.1 Default event script</a><ul class="auto-toc">
+<li><a class="reference internal" href="#activating-a-hook-script" id="id48">9.1.1 Activating a hook script</a></li>
+<li><a class="reference internal" href="#adding-a-new-hook-script" id="id49">9.1.2 Adding a new hook script</a></li>
</ul>
</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>
+<li><a class="reference internal" href="#event-policy" id="id50">9.2 Event Policy</a></li>
+<li><a class="reference internal" href="#hook-environment" id="id51">9.3 Hook Environment</a></li>
+<li><a class="reference internal" href="#adding-a-function-file" id="id52">9.4 Adding a function file</a></li>
+<li><a class="reference internal" href="#hook-event-table" id="id53">9.5 Hook event table</a></li>
+<li><a class="reference internal" href="#adding-a-hook-event" id="id54">9.6 Adding a hook event</a></li>
</ul>
</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>
+<li><a class="reference internal" href="#configuration-reference" id="id55">10 Configuration Reference</a><ul class="auto-toc">
+<li><a class="reference internal" href="#misc-options" id="id56">10.1 misc options</a></li>
+<li><a class="reference internal" href="#overlay-options" id="id57">10.2 overlay options</a></li>
+<li><a class="reference internal" href="#other-config-files" id="id58">10.3 other config files</a></li>
+<li><a class="reference internal" href="#shell-environment-hooks" id="id59">10.4 shell environment / hooks</a></li>
+<li><a class="reference internal" href="#logging" id="id60">10.5 logging</a><ul class="auto-toc">
+<li><a class="reference internal" href="#console-logging" id="id61">10.5.1 console logging</a></li>
+<li><a class="reference internal" href="#file-logging" id="id62">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>
+<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id63">10.6 options for debugging, manual dependency rule creation and testing</a></li>
</ul>
</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>
+<li><a class="reference internal" href="#id3" id="id64">11 Other config files</a><ul class="auto-toc">
+<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id65">11.1 USE_EXPAND flag rename file</a></li>
+<li><a class="reference internal" href="#field-definition-config" id="id66">11.2 Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id67">11.2.1 Example: The default field definition file</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution-console" id="id65">12 Dependency Resolution Console</a></li>
-<li><a class="reference internal" href="#roverlay-interface" id="id66">13 Roverlay Interface</a><ul class="auto-toc">
-<li><a class="reference internal" href="#depres-interface" id="id67">13.1 DepRes Interface</a></li>
+<li><a class="reference internal" href="#id5" id="id68">12 Roverlay Console</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-resolution-console" id="id69">12.1 Dependency Resolution Console</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#implementation-overview" id="id68">14 Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#packageinfo" id="id69">14.1 PackageInfo</a></li>
-<li><a class="reference internal" href="#repository-management" id="id70">14.2 Repository Management</a><ul class="auto-toc">
-<li><a class="reference internal" href="#repository" id="id71">14.2.1 Repository</a><ul class="auto-toc">
-<li><a class="reference internal" href="#adding-new-repository-types" id="id72">14.2.1.1 Adding new repository types</a></li>
+<li><a class="reference internal" href="#roverlay-interface" id="id70">13 Roverlay Interface</a><ul class="auto-toc">
+<li><a class="reference internal" href="#depres-interface" id="id71">13.1 DepRes Interface</a></li>
+<li><a class="reference internal" href="#remote-interface" id="id72">13.2 Remote Interface</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#implementation-overview" id="id73">14 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id74">14.1 PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id75">14.2 Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#repository" id="id76">14.2.1 Repository</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id77">14.2.1.1 Adding new repository types</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay" id="id73">14.3 Overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#metadata-creation" id="id74">14.3.1 Metadata Creation</a></li>
-<li><a class="reference internal" href="#manifest-creation" id="id75">14.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#ebuild-creation" id="id76">14.4 Ebuild Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#ebuild-variables" id="id77">14.4.1 Ebuild Variables</a></li>
+<li><a class="reference internal" href="#overlay" id="id78">14.3 Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id79">14.3.1 Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id80">14.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay-creation" id="id78">14.5 Overlay Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#selfdep-validation" id="id79">14.5.1 Selfdep Validation</a></li>
+<li><a class="reference internal" href="#ebuild-creation" id="id81">14.4 Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id82">14.4.1 Ebuild Variables</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution" id="id80">14.6 Dependency Resolution</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id81">14.6.1 Dependency types</a><ul class="auto-toc">
-<li><a class="reference internal" href="#description-file-dependency-fields" id="id82">14.6.1.1 DESCRIPTION file dependency fields</a></li>
+<li><a class="reference internal" href="#overlay-creation" id="id83">14.5 Overlay Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#selfdep-validation" id="id84">14.5.1 Selfdep Validation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-environments" id="id83">14.6.2 Dependency Environments</a></li>
-<li><a class="reference internal" href="#ebuildjob-channel" id="id84">14.6.3 EbuildJob Channel</a></li>
-<li><a class="reference internal" href="#dependency-rule-pools" id="id85">14.6.4 Dependency Rule Pools</a></li>
-<li><a class="reference internal" href="#dependency-resolver-modules" id="id86">14.6.5 Dependency Resolver Modules</a></li>
-<li><a class="reference internal" href="#dependency-resolver" id="id87">14.6.6 Dependency Resolver</a></li>
+<li><a class="reference internal" href="#dependency-resolution" id="id85">14.6 Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id86">14.6.1 Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id87">14.6.1.1 DESCRIPTION file dependency fields</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dependency-environments" id="id88">14.6.2 Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id89">14.6.3 EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id90">14.6.4 Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id91">14.6.5 Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id92">14.6.6 Dependency Resolver</a></li>
</ul>
</li>
</ul>
@@ -848,6 +854,9 @@ This also tries to recreate the distmap.</td></tr>
<kbd><span class="option">--no-incremental</span></kbd></td>
</tr>
<tr><td> </td><td>Force recreation of existing ebuilds</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--no-revbump</span></kbd></td>
+<td>Disable revbump checks in incremental overlay creation mode</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--immediate-ebuild-writes</span></kbd></td>
</tr>
@@ -897,6 +906,9 @@ an overlay that is not suitable for production usage.</p>
<kbd><span class="option">--no-write</span></kbd></td>
<td>Disable overlay writing</td></tr>
<tr><td class="option-group">
+<kbd><span class="option">--dump-stats</span></kbd></td>
+<td>Print all stats</td></tr>
+<tr><td class="option-group">
<kbd><span class="option">--show</span></kbd></td>
<td>Print all ebuilds and metadata to console</td></tr>
<tr><td class="option-group" colspan="2">
@@ -956,6 +968,35 @@ to symbolic links if hard links are not supported. This should be fine in
most cases, but fine-tuning can be done via <a class="reference internal" href="#overlay-distdir-strategy">OVERLAY_DISTDIR_STRATEGY</a> and
<a class="reference internal" href="#overlay-distdir-flat">OVERLAY_DISTDIR_FLAT</a>.</p>
</div>
+<div class="section" id="roverlay-helpers">
+<h2><a class="toc-backref" href="#contents">3.4 roverlay helpers</a></h2>
+<p>An installation of roverlay includes some helper programs:</p>
+<dl class="docutils">
+<dt><em>roverlay-sh</em></dt>
+<dd><p class="first">a wrapper around /bin/sh that runs a shell or shell script in roverlay's
+<a class="reference internal" href="#hook-environment">hook environment</a>.</p>
+<p>roverlay-related scripts can use it to automatically inherit roverlay's
+config and <tt class="docutils literal">$FUNCTIONS</tt> file:</p>
+<pre class="code sh literal-block">
+<span class="comment">#!/usr/bin/roverlay-sh
+</span>
+<span class="comment"># reset DEBUG, VERBOSE, QUIET
+</span><span class="name variable">DEBUG</span><span class="operator">=</span>n; <span class="name variable">QUIET</span><span class="operator">=</span>n; <span class="name variable">VERBOSE</span><span class="operator">=</span>y
+
+<span class="comment"># load the functions file (optional)
+</span>. <span class="literal string double">"${FUNCTIONS?}"</span> <span class="operator">||</span> <span class="name builtin">exit</span>
+
+<span class="comment"># script body
+</span><span class="name builtin">true</span>
+</pre>
+<p class="last"><<TODO: maybe there's a better place for the details>></p>
+</dd>
+<dt><em>name_is_todo--roverlay_creation_helper</em></dt>
+<dd><<TODO>>
+Safely runs overlay creation <<and $$afterwards>>.
+Suitable for being run as cron job.</dd>
+</dl>
+</div>
</div>
<div class="section" id="basic-implementation-overview">
<h1><a class="toc-backref" href="#contents">4 Basic Implementation Overview</a></h1>
@@ -1792,7 +1833,7 @@ as <em>sci-R/zoo</em>. This rule can be written as a single word, <em>zoo</em>.<
Each package rule consists of conditions, e.g. <em>package name contains amd64</em>,
and actions, e.g. <em>set KEYWORDS="-x86 amd64"</em>.
The actions of a rule will only be applied if a package meets all conditions,
-otherwise the rule does nothing.
+otherwise the rule applies alternative actions (if defined) or does nothing.
Moreover, rules can contain further rules which will only take effect if all
enclosing rules match a given package.</p>
<div class="section" id="package-rule-file-syntax">
@@ -1800,10 +1841,13 @@ enclosing rules match a given package.</p>
<p>As stated above, each rule has two parts, a <em>match block</em> that lists the
rule's conditions and an <em>action block</em> that defines which actions and
nested rules are applied to a package if the rule matches it, i.e. if all
-conditions are met.</p>
+conditions are met. A rule can also contain an <em>alternative action block</em>
+whose actions are applied to a package if the rule does not match it.</p>
<p>A rule file contains zero or more package rules.
-Each rule has to declare one <em>match</em> and one <em>action statement</em> at least.
-The basic syntax for a rule with 1..m <em>match</em> and 1..n <em>action statements</em> is</p>
+Each rule has to declare one <em>match</em> and one
+<em>[alternative] action statement</em> at least.
+The basic syntax for a rule with 1..m <em>match</em>, 1..n <em>action statements</em> and
+1..k <em>alternative action statements</em> is</p>
<pre class="code literal-block">
MATCH:
<match statement 1>
@@ -1815,13 +1859,20 @@ ACTION:
<action statement 2>
...
<action statement n>
+ELSE:
+ <alternative action statement 1>
+ <alternative action statement 2>
+ ...
+ <alternative action statement k>
END;
</pre>
<p>A rule is introduced by the <tt class="docutils literal">MATCH:</tt> keyword, which starts the
<em>match block</em> and is followed by one or more <em>match statements</em>, one per line.
The <em>match block</em> ends with the <tt class="docutils literal">ACTION:</tt> keyword, which also starts the
<em>action block</em> and is followed by one or more <em>action statements</em>
-(again, one per line). Finally, the rule is terminated by the <tt class="docutils literal">END;</tt> keyword.</p>
+(again, one per line). The <em>alternative action block</em> introduced by the
+<tt class="docutils literal">ELSE:</tt> keyword is optional and lists <em>action statements</em>.
+Finally, the rule is terminated by the <tt class="docutils literal">END;</tt> keyword.</p>
<p>Indention is purely optional, leading and ending whitespace will be discarded.
Lines starting with <tt class="docutils literal">#</tt> or <tt class="docutils literal">;</tt> are considered to be comments and will be
ignored.</p>
@@ -2119,6 +2170,15 @@ statements</td>
<tr><td>rename_<key></td>
<td>1</td>
</tr>
+<tr><td>null</td>
+<td rowspan="2"><em>n/a</em></td>
+<td rowspan="2">none</td>
+<td rowspan="2">does nothing
+(can be used for
+readability)</td>
+</tr>
+<tr><td>pass</td>
+</tr>
</tbody>
</table>
<p>The two-arg form of the set/rename keywords expect a <key> as first and
@@ -2190,6 +2250,19 @@ ACTION:
END;
# top-level rule, action block continues
...
+ELSE:
+ # top-level rule, alternative action block
+ ...
+ MATCH:
+ # (alternative) nested rule, match block
+ ...
+ ACTION:
+ # (alternative) nested rule, action block
+ ...
+ ELSE:
+ # (alternative) nested rule, alternative action block
+ ...
+ END;
END;
</pre>
<p>Rules can be nested indefinitely, whitespace indention is optional.
@@ -2201,13 +2274,19 @@ checks necessary for a given package.</p>
<div class="section" id="package-rule-examples">
<h3><a class="toc-backref" href="#contents">8.1.3 Package Rule Examples</a></h3>
<p>A rule that ignores the 'yaqcaffy' package from CRAN, which is also available
-from BIOC:</p>
+from BIOC. Additionally, it sets the category for all non-ignored packages
+from CRAN to sci-CRAN:</p>
<pre class="code literal-block">
MATCH:
- repo == CRAN
- package_name == yaqcaffy
+ repo CRAN
ACTION:
- do-not-process
+ MATCH:
+ package_name == yaqcaffy
+ ACTION:
+ do-not-process
+ ELSE:
+ set category sci-CRAN
+ END;
END;
</pre>
<p>A more complex example that sets the <tt class="docutils literal">KEYWORDS</tt> ebuild variable for
@@ -2219,11 +2298,12 @@ MATCH:
* package_name ~ x86_64
* package_name ~ amd64
ACTION:
- keywords "-x86 amd64"
MATCH:
repo == BIOC/experiment
ACTION:
keywords "-x86 ~amd64"
+ ELSE:
+ keywords "-x86 amd64"
END;
END;
</pre>
@@ -2258,6 +2338,13 @@ ACTION:
rename_destfile s=^=R-package/=
END;
</pre>
+<div class="hint">
+<p class="first admonition-title">Hint</p>
+<p class="last"><tt class="docutils literal">roverlay <span class="pre">[--nosync]</span> <span class="pre">[--dump-file</span> <file>] apply_rules</tt> can be used to
+test rules. It applies the rules to all packages without running overlay
+creation. Furthermore, <tt class="docutils literal">roverlay <span class="pre">--ppr</span></tt> parses the package rules,
+prints them and exits afterwards.</p>
+</div>
</div>
</div>
</div>
@@ -2389,16 +2476,30 @@ the config file. An empty string sets the policy to <em>deny all</em>.</p>
<td>event</td>
<td>event that caused the script to run</td>
</tr>
+<tr><td>HAS_CHANGES</td>
+<td><em>internal</em></td>
+<td>a shbool (<tt class="docutils literal">y</tt> or <tt class="docutils literal">n</tt>) that
+indicates whether the overlay has
+any changes</td>
+</tr>
+<tr><td>OVERLAY_NAME</td>
+<td>config</td>
+<td>name of the overlay</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>
+<td rowspan="2">overlay directory (<a class="reference internal" href="#overlay-dir">OVERLAY_DIR</a>),</td>
</tr>
<tr><td>S</td>
<td><em>$OVERLAY</em></td>
</tr>
<tr><td>PWD</td>
-<td><em>$OVERLAY</em></td>
+<td><em>$OVERLAY</em>
+<em>$ROVERLAY_PHASE</em></td>
+<td><p class="first">initial working directory</p>
+<p class="last">depends on $ROVERLAY_PHASE (usually set
+to $OVERLAY or left unchanged)</p>
+</td>
</tr>
<tr><td>DISTROOT</td>
<td>config</td>
@@ -2421,6 +2522,11 @@ initial working directory</td>
<tr><td>FILESDIR</td>
<td><em>$ADDITIONS_DIR</em></td>
</tr>
+<tr><td>WORKDIR</td>
+<td>config</td>
+<td>directory for work data
+(<a class="reference internal" href="#cachedir">CACHEDIR</a>)</td>
+</tr>
<tr><td>SHLIB</td>
<td><em>$ADDITIONS_DIR</em>,
<em>installed?</em></td>
@@ -2434,6 +2540,30 @@ function files
<td>file with essential shell functions
(optional, only set if it exists)</td>
</tr>
+<tr><td>DATADIR</td>
+<td><em>installed?</em></td>
+<td>location of installed data files
+(directory, usually
+<em>/usr/share/roverlay</em>)</td>
+</tr>
+<tr><td>ROVERLAY_HELPER_EXE</td>
+<td>sys.argv</td>
+<td>path to the roverlay executable that
+created the hook environment
+(usually <em>/usr/bin/roverlay</em> or
+<em>/usr/bin/roverlay-sh</em>)</td>
+</tr>
+<tr><td>ROVERLAY_EXE</td>
+<td>guessed,
+<em>$ROVERLAY_HELPER_EXE</em></td>
+<td>guessed path to the roverlay "main"
+executable (which creates the overlay)</td>
+</tr>
+<tr><td>STATS_DB</td>
+<td>config</td>
+<td>stats database file
+(optional, only set if configured)</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
@@ -2628,8 +2758,39 @@ They should, however, not execute any code directly.</p>
</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="hook-event-table">
+<h2><a class="toc-backref" href="#contents">9.5 Hook event table</a></h2>
+<p>The following table lists all known events (<tt class="docutils literal">ROVERLAY_PHASE</tt>):</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="25%" />
+<col width="36%" />
+<col width="39%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">name</th>
+<th class="head">initial working directory</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>overlay_success</td>
+<td><em>$OVERLAY</em></td>
+<td>overlay creation succeeded</td>
+</tr>
+<tr><td>db_written</td>
+<td><em>$OVERLAY</em></td>
+<td>stats database file written</td>
+</tr>
+<tr><td>user</td>
+<td>unchanged</td>
+<td>user-triggered event</td>
+</tr>
+</tbody>
+</table>
+</div>
<div class="section" id="adding-a-hook-event">
-<h2><a class="toc-backref" href="#contents">9.5 Adding a hook event</a></h2>
+<h2><a class="toc-backref" href="#contents">9.6 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>
@@ -2940,6 +3101,13 @@ writing.</p>
</div>
</dd>
</dl>
+<dl class="docutils" id="overlay-masters">
+<dt>OVERLAY_MASTERS</dt>
+<dd><p class="first">A list of repo names that are used as 'masters' attribute when generating
+<tt class="docutils literal"><span class="pre"><overlay>/metadata/layout.conf</span></tt>.</p>
+<p class="last">Defaults to "gentoo".</p>
+</dd>
+</dl>
<dl class="docutils" id="overlay-name">
<dt>OVERLAY_NAME</dt>
<dd><p class="first">Sets the name of the created overlay that will be written into
@@ -3277,9 +3445,9 @@ as flag.</dd>
<dl class="docutils" id="field-flag-joinvalues">
<dt>joinValues</dt>
<dd>Declares that a field's value is one string even if it spans over
-multiple lines.
-The lines will be joined with a single space character ' '.
-The default behavior is to merge lines.</dd>
+multiple lines. The lines will be joined with a single space
+character ' '. The default behavior is to merge lines.
+This flag can be used in conjunction with any "is list" flag.</dd>
</dl>
<dl class="docutils" id="field-flag-islist">
<dt>isList</dt>
@@ -3350,17 +3518,31 @@ such a field is found.</dd>
<span class="keyword">[OS_Type]</span>
<span class="name attribute">alias_nocase</span> <span class="operator">=</span> <span class="literal string">OS_TYPE</span>
<span class="name attribute">allowed_values</span> <span class="operator">=</span> <span class="literal string">unix</span>
+
+<span class="keyword">[License]</span>
+<span class="name attribute">alias_nocase</span> <span class="operator">=</span> <span class="literal string">License, Licence, Lisence</span>
+<span class="error">isLicense</span>
</pre>
</div>
</div>
</div>
+<div class="section" id="id5">
+<span id="roverlay-console"></span><h1><a class="toc-backref" href="#contents">12 Roverlay Console</a></h1>
+<p><<section is TODO>></p>
+<p><<links to depres console chapter may need to be fixed>></p>
+<p><<basic commands, table>></p>
+<p><<note regarding python -OO and missing help texts>></p>
<div class="section" id="dependency-resolution-console">
-<span id="depres-console"></span><h1><a class="toc-backref" href="#contents">12 Dependency Resolution Console</a></h1>
+<span id="depres-console"></span><h2><a class="toc-backref" href="#contents">12.1 Dependency Resolution Console</a></h2>
+<div class="warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This section is out-of-date.</p>
+</div>
<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">
<li>resolve dependencies</li>
-<li>create new dependency rules (<strong>only single line rules</strong>)</li>
+<li>create new dependency rules</li>
<li>create dependency rules for each R package found in a directory</li>
<li>load rules from files</li>
<li>save rules to a file</li>
@@ -3371,6 +3553,7 @@ to create or remove them easily at runtime.</p>
<p>Running <tt class="docutils literal">roverlay depres_console</tt> will print a welcome message that
lists all available commands and a few usage hints.</p>
<p>For reference, these commands are currently available:</p>
+<p><<TODO: rewrite/update command table, it's out-of-date>></p>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
@@ -3383,13 +3566,9 @@ lists all available commands and a few usage hints.</p>
</thead>
<tbody valign="top">
<tr><td>help,
-h</td>
+h, ?</td>
<td>lists all commands</td>
</tr>
-<tr><td>help --list,
-h --list</td>
-<td>lists all help topics for which help is available</td>
-</tr>
<tr><td>help <em><cmd></em>,
h <em><cmd></em></td>
<td>prints a command-specific help message</td>
@@ -3404,65 +3583,78 @@ lc</td>
<td>loads the rule files listed in the config file
into a new <em>rule pool</em></td>
</tr>
-<tr><td>addrule <em><rule></em>
+<tr><td>add_rule <em><rule></em>
+ <em><rule></em></td>
<td>creates a new rule and adds it to the topmost,
i.e. latest <em>rule pool</em>. This command uses
-<a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a>, but multi line rules are
-not supported.</td>
+<a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a>. Multi line rules are
+supported.</td>
</tr>
<tr><td>add_pool,
<<</td>
<td>creates a new <em>rule pool</em></td>
</tr>
-<tr><td>unwind,
+<tr><td>unwind_pool,
>></td>
<td>removes the topmost <em>rule pool</em> and all of its
rules</td>
</tr>
<tr><td>resolve <em><dep></em>,
-? <em><dep></em></td>
+?? <em><dep></em></td>
<td>tries to resolve the given dependency string and
prints the result</td>
</tr>
+<tr><td>!</td>
+<td>enter the resolve <em>command chroot</em>
+all input will be prefixed with "resolve"</td>
+</tr>
+<tr><td>!!</td>
+<td>leave any <em>command chroot</em></td>
+</tr>
<tr><td>print, p</td>
<td>prints the rules of the topmost <em>rule pool</em></td>
</tr>
-<tr><td>print all, p all</td>
+<tr><td>print --all|-a</td>
<td>prints the rules of all <em>rule pools</em></td>
</tr>
+<tr><td>print <id> [<id>..]</td>
+<td>prints the rules of a specific <em>rule pool</em></td>
+</tr>
<tr><td>write <em><file></em>,
w <em><file></em></td>
<td>writes the rules of the topmost <em>rule pool</em> into
-<em><file></em></td>
+<em><file></em>. See write --help for advanced usage.</td>
</tr>
<tr><td>cd <em><dir></em></td>
-<td>changes the working directory, also creates it if
-necessary</td>
+<td>changes the working directory
+This is a virtual command. <<TODO:EXPLAIN>></td>
+</tr>
+<tr><td>set VAR=VALUE</td>
+<td>set variables</td>
</tr>
-<tr><td>scandir <em><dir></em>,
-sd <em><dir></em></td>
-<td>creates dependency rules for each R package found
-in <em><dir></em></td>
+<tr><td>unset VAR</td>
+<td>unset variables</td>
</tr>
-<tr><td>set, unset</td>
-<td>prints the status of currently (in)active modes</td>
+<tr><td>declare</td>
+<td>show declared variables</td>
</tr>
-<tr><td>set <em><mode></em>,
-unset <em><mode></em></td>
-<td>sets or unsets <em><mode></em>. There is only one mode to
-control, the <em>shlex mode</em> which controls how
-command arguments are parsed</td>
+<tr><td>alias</td>
+<td>show command aliases</td>
</tr>
-<tr><td>mkhelp</td>
-<td>verifies that each accessible command has a help
-message</td>
+<tr><td>unalias</td>
+<td>reserved for future usage</td>
</tr>
<tr><td>exit, qq, q</td>
<td>exits the <em>DepRes Console</em></td>
</tr>
</tbody>
</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">Some commands also offer more detailed help via <tt class="docutils literal"><command> <span class="pre">--help</span></tt>.</p>
+</div>
+<p><<TODO>></p>
+<p><<Example Session is out-of-date>></p>
<dl class="docutils">
<dt>Example Session:</dt>
<dd><pre class="code first last literal-block">
@@ -3512,6 +3704,7 @@ cmd % exit
</dd>
</dl>
</div>
+</div>
<div class="section" id="roverlay-interface">
<h1><a class="toc-backref" href="#contents">13 Roverlay Interface</a></h1>
<p>Roverlay provides an API for accessing its functionality independently of
@@ -3547,6 +3740,10 @@ initialization</td>
<td>roverlay.interface.depres</td>
<td>dependency resolution</td>
</tr>
+<tr><td>RemoteInterface</td>
+<td>roverlay.interface.remote</td>
+<td>remote interaction (sync)</td>
+</tr>
</tbody>
</table>
<p>For extending the API, roverlay provides the abstract <em>RoverlayInterface</em> and
@@ -3572,9 +3769,13 @@ and <em>cannot_resolve()</em></li>
also possible</li>
</ul>
<p>Refer to in-code documentation on how to use this interface.
-See the dependency resolution test suite for a usage example
-(<tt class="docutils literal">tests.depres</tt>, not part of the roverlay installation).
-(The depres console is also a candidate for using this interface in future.)</p>
+See the dependency resolution test suite (<tt class="docutils literal">tests.depres</tt>, not part of the
+roverlay installation) and the dependency resolution console
+for usage examples.</p>
+</div>
+<div class="section" id="remote-interface">
+<h2><a class="toc-backref" href="#contents">13.2 Remote Interface</a></h2>
+<p><<TODO; this interface isn't mature enough yet (it will likely change in future)>></p>
</div>
</div>
<div class="section" id="implementation-overview">
@@ -4114,7 +4315,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-07-23.
+Generated on: 2013-08-02.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-08-06 16:02 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-08-06 16:02 UTC (permalink / raw
To: gentoo-commits
commit: 86b204c29cd4db9d7a404fa9f2738dd3be638f5c
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Aug 6 16:02:11 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Aug 6 16:02:11 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=86b204c2
update doc/html/usage.html (generated file)
---
doc/html/usage.html | 589 +++++++++++++++++++++++++++++++++++++---------------
1 file changed, 419 insertions(+), 170 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 16fbbe9..39d7e63 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -418,58 +418,59 @@ ul.auto-toc {
<li><a class="reference internal" href="#file-logging" id="id62">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="id63">10.6 options for debugging, manual dependency rule creation and testing</a></li>
+<li><a class="reference internal" href="#license-map-options" id="id63">10.6 license map options</a></li>
+<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id64">10.7 options for debugging, manual dependency rule creation and testing</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#id3" id="id64">11 Other config files</a><ul class="auto-toc">
-<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id65">11.1 USE_EXPAND flag rename file</a></li>
-<li><a class="reference internal" href="#field-definition-config" id="id66">11.2 Field Definition Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id67">11.2.1 Example: The default field definition file</a></li>
+<li><a class="reference internal" href="#id3" id="id65">11 Other config files</a><ul class="auto-toc">
+<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id66">11.1 USE_EXPAND flag rename file</a></li>
+<li><a class="reference internal" href="#field-definition-config" id="id67">11.2 Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id68">11.2.1 Example: The default field definition file</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#id5" id="id68">12 Roverlay Console</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-resolution-console" id="id69">12.1 Dependency Resolution Console</a></li>
+<li><a class="reference internal" href="#id5" id="id69">12 Roverlay Console</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-resolution-console" id="id70">12.1 Dependency Resolution Console</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#roverlay-interface" id="id70">13 Roverlay Interface</a><ul class="auto-toc">
-<li><a class="reference internal" href="#depres-interface" id="id71">13.1 DepRes Interface</a></li>
-<li><a class="reference internal" href="#remote-interface" id="id72">13.2 Remote Interface</a></li>
+<li><a class="reference internal" href="#roverlay-interface" id="id71">13 Roverlay Interface</a><ul class="auto-toc">
+<li><a class="reference internal" href="#depres-interface" id="id72">13.1 DepRes Interface</a></li>
+<li><a class="reference internal" href="#remote-interface" id="id73">13.2 Remote Interface</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#implementation-overview" id="id73">14 Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#packageinfo" id="id74">14.1 PackageInfo</a></li>
-<li><a class="reference internal" href="#repository-management" id="id75">14.2 Repository Management</a><ul class="auto-toc">
-<li><a class="reference internal" href="#repository" id="id76">14.2.1 Repository</a><ul class="auto-toc">
-<li><a class="reference internal" href="#adding-new-repository-types" id="id77">14.2.1.1 Adding new repository types</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id74">14 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id75">14.1 PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id76">14.2 Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#repository" id="id77">14.2.1 Repository</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id78">14.2.1.1 Adding new repository types</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay" id="id78">14.3 Overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#metadata-creation" id="id79">14.3.1 Metadata Creation</a></li>
-<li><a class="reference internal" href="#manifest-creation" id="id80">14.3.2 Manifest Creation</a></li>
+<li><a class="reference internal" href="#overlay" id="id79">14.3 Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id80">14.3.1 Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id81">14.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#ebuild-creation" id="id81">14.4 Ebuild Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#ebuild-variables" id="id82">14.4.1 Ebuild Variables</a></li>
+<li><a class="reference internal" href="#ebuild-creation" id="id82">14.4 Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id83">14.4.1 Ebuild Variables</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay-creation" id="id83">14.5 Overlay Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#selfdep-validation" id="id84">14.5.1 Selfdep Validation</a></li>
+<li><a class="reference internal" href="#overlay-creation" id="id84">14.5 Overlay Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#selfdep-validation" id="id85">14.5.1 Selfdep Validation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution" id="id85">14.6 Dependency Resolution</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id86">14.6.1 Dependency types</a><ul class="auto-toc">
-<li><a class="reference internal" href="#description-file-dependency-fields" id="id87">14.6.1.1 DESCRIPTION file dependency fields</a></li>
+<li><a class="reference internal" href="#dependency-resolution" id="id86">14.6 Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id87">14.6.1 Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id88">14.6.1.1 DESCRIPTION file dependency fields</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-environments" id="id88">14.6.2 Dependency Environments</a></li>
-<li><a class="reference internal" href="#ebuildjob-channel" id="id89">14.6.3 EbuildJob Channel</a></li>
-<li><a class="reference internal" href="#dependency-rule-pools" id="id90">14.6.4 Dependency Rule Pools</a></li>
-<li><a class="reference internal" href="#dependency-resolver-modules" id="id91">14.6.5 Dependency Resolver Modules</a></li>
-<li><a class="reference internal" href="#dependency-resolver" id="id92">14.6.6 Dependency Resolver</a></li>
+<li><a class="reference internal" href="#dependency-environments" id="id89">14.6.2 Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id90">14.6.3 EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id91">14.6.4 Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id92">14.6.5 Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id93">14.6.6 Dependency Resolver</a></li>
</ul>
</li>
</ul>
@@ -976,21 +977,19 @@ most cases, but fine-tuning can be done via <a class="reference internal" href="
<dd><p class="first">a wrapper around /bin/sh that runs a shell or shell script in roverlay's
<a class="reference internal" href="#hook-environment">hook environment</a>.</p>
<p>roverlay-related scripts can use it to automatically inherit roverlay's
-config and <tt class="docutils literal">$FUNCTIONS</tt> file:</p>
-<pre class="code sh literal-block">
+config and get access to its <tt class="docutils literal">$FUNCTIONS</tt> file:</p>
+<pre class="code sh last literal-block">
<span class="comment">#!/usr/bin/roverlay-sh
</span>
-<span class="comment"># reset DEBUG, VERBOSE, QUIET
-</span><span class="name variable">DEBUG</span><span class="operator">=</span>n; <span class="name variable">QUIET</span><span class="operator">=</span>n; <span class="name variable">VERBOSE</span><span class="operator">=</span>y
-
<span class="comment"># load the functions file (optional)
</span>. <span class="literal string double">"${FUNCTIONS?}"</span> <span class="operator">||</span> <span class="name builtin">exit</span>
<span class="comment"># script body
</span><span class="name builtin">true</span>
</pre>
-<p class="last"><<TODO: maybe there's a better place for the details>></p>
</dd>
+<dt><em>roverlay-mkconfig</em></dt>
+<dd>a script that creates a config file for roverlay</dd>
<dt><em>name_is_todo--roverlay_creation_helper</em></dt>
<dd><<TODO>>
Safely runs overlay creation <<and $$afterwards>>.
@@ -1341,7 +1340,9 @@ Options with whitespace are not supported.</li>
<p>This is your best bet if the remote is a repository but does not offer rsync
access. Basic digest verification is supported (MD5). The remote has to have
a package list file, typically named <em>PACKAGES</em>,
-with a special syntax (debian control file syntax).</p>
+with a special syntax (debian control file syntax). Syncing is retried up to
+3 times, for example if a connection timeout occurs or a remote file
+disappears after reading the package list file.</p>
<p>A package list example,
excerpt from <a class="reference external" href="http://www.omegahat.org/R/src/contrib/PACKAGES">omegahat's PACKAGES file</a> (as of Aug 2012):</p>
<pre class="code control literal-block">
@@ -1453,7 +1454,6 @@ reduces its size considerably.</p>
<p>The <em>additions directory</em> is a directory with overlay-like structure that
contains extra files for overlay creation. Currently, ebuild patches and
ebuild files are supported.</p>
-<p>To give an idea of how this directory could</p>
<div class="section" id="patching-ebuilds">
<h2><a class="toc-backref" href="#contents">6.1 Patching ebuilds</a></h2>
<p>Patches can apply to a <strong>specific version</strong> or to <strong>all versions</strong> of a
@@ -1496,13 +1496,13 @@ for collecting dependencies.</p>
<p>Foreign ebuilds can be imported into the overlay by simple putting them into
the additions directory.</p>
<p>The naming convention is similar to ebuild patches and identical to the
-portage tree:</p>
-<pre class="code literal-block">
-${CATEGORY}/${PN}/${PF}.ebuild
-</pre>
-<p>Ebuilds imported that way can not be overwritten by generated ebuilds and
+portage tree, <tt class="docutils literal"><span class="pre">${CATEGORY}/${PN}/${PF}.ebuild</span></tt>.</p>
+<p>Ebuilds imported that way cannot be overwritten by generated ebuilds and
benefit from most overlay creation features, e.g. Manifest file creation.
However, they cannot be used for metadata creation.</p>
+<p>The <tt class="docutils literal"><span class="pre">${CATEGORY}/${PN}/metadata.xml</span></tt> file will be imported if it exists and
+if <tt class="docutils literal">${PN}</tt> in the overlay (a) has no metadata.xml file or (b) has no
+generated ebuilds (only imports).</p>
</div>
</div>
<div class="section" id="dependency-rules">
@@ -1781,7 +1781,9 @@ colong char <tt class="docutils literal">:</tt>:</p>
<dd>start with <strong>#</strong>. There are a few exceptions to that, the <em>#deptype</em> and
<em>#! NOPARSE</em> keywords. Comments inside rule blocks are not allowed and
will be read as normal <em>dependency strings</em>.</dd>
-<dt>Selfdep</dt>
+</dl>
+<dl class="docutils" id="selfdeps">
+<span id="selfdep"></span><dt>Selfdep</dt>
<dd><p class="first">This is a classification for dependencies on packages which are also part
of the overlay being created. Typically, selfdeps refer to other R
packages, but there may be a few exceptions.</p>
@@ -2907,6 +2909,13 @@ This will pass '--bwlimit=<value>' to all rsync commands.</p>
<p class="last">Defaults to <not set>, which disables bandwidth limitation.</p>
</dd>
</dl>
+<dl class="docutils" id="portdir">
+<dt>PORTDIR</dt>
+<dd><p class="first">Path to the portage tree. This option is <strong>recommended</strong>, but not always
+required.</p>
+<p class="last">Defaults to "/usr/portage".</p>
+</dd>
+</dl>
</div>
<div class="section" id="overlay-options">
<h2><a class="toc-backref" href="#contents">10.2 overlay options</a></h2>
@@ -3342,8 +3351,41 @@ files will be kept.</p>
</dl>
</div>
</div>
+<div class="section" id="license-map-options">
+<h2><a class="toc-backref" href="#contents">10.6 license map options</a></h2>
+<dl class="docutils" id="create-license-file">
+<dt>CREATE_LICENSE_FILE</dt>
+<dd>Alias to <a class="reference internal" href="#create-licenses-file">CREATE_LICENSES_FILE</a>.</dd>
+</dl>
+<dl class="docutils" id="create-licenses-file">
+<dt>CREATE_LICENSES_FILE</dt>
+<dd><p class="first">Create the <a class="reference internal" href="#cachedir">CACHEDIR</a>/license file after scanning <a class="reference internal" href="#portdir">PORTDIR</a>/licenses for
+licenses. This file can serve as fallback if <a class="reference internal" href="#portdir">PORTDIR</a> is not available
+or if <a class="reference internal" href="#use-portage-licenses">USE_PORTAGE_LICENSES</a> is set to <em>no</em>.</p>
+<p class="last">Defaults to <em>yes</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="license-map">
+<dt>LICENSE_MAP</dt>
+<dd><p class="first">Path to the license map file, which is used to translate license strings
+into valid licenses (accepted by portage). Its syntax is similar to
+dependency rules.</p>
+<p>This option is <strong>not required</strong>, but recommended if the
+<a class="reference internal" href="#field-definition-config">field definition config</a> file contains a field with the <em>isLicense</em> flag.</p>
+<p class="last">Defaults to <not set>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="use-portage-licenses">
+<dt>USE_PORTAGE_LICENSES</dt>
+<dd><p class="first">A <em>bool</em> that controls whether <a class="reference internal" href="#portdir">PORTDIR</a>/licenses should be scanned for
+licenses. As fallback, or if this option is set to <em>no</em>, the
+<a class="reference internal" href="#cachedir">CACHEDIR</a>/license file is read.</p>
+<p class="last">Defaults to <em>yes</em>.</p>
+</dd>
+</dl>
+</div>
<div class="section" id="options-for-debugging-manual-dependency-rule-creation-and-testing">
-<h2><a class="toc-backref" href="#contents">10.6 options for debugging, manual dependency rule creation and testing</a></h2>
+<h2><a class="toc-backref" href="#contents">10.7 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
@@ -3528,178 +3570,262 @@ such a field is found.</dd>
</div>
<div class="section" id="id5">
<span id="roverlay-console"></span><h1><a class="toc-backref" href="#contents">12 Roverlay Console</a></h1>
-<p><<section is TODO>></p>
-<p><<links to depres console chapter may need to be fixed>></p>
-<p><<basic commands, table>></p>
-<p><<note regarding python -OO and missing help texts>></p>
+<p>roverlay provides an interactive console for accessing certain subsystems,
+e.g. dependency resolution. Its features include tab completion for filesystem
+paths and a command history that supports navigation with the arrow keys.</p>
+<p>The console also implements a subset of typical tools like <tt class="docutils literal">cat</tt>, which
+behave similar but not identical to their counterparts.</p>
+<p>See the following sections for how to run specific consoles.</p>
+<p>The following table lists all basic commands, which are available in all
+roverlay consoles. Some commands have more detailed help messages, which are
+printed when running <tt class="docutils literal"><cmd> <span class="pre">--help</span></tt>.</p>
+<table border="1" class="docutils">
+<caption>basic console commands (subsystem-independent)</caption>
+<colgroup>
+<col width="25%" />
+<col width="12%" />
+<col width="63%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">command</th>
+<th class="head">extended
+--help</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>exit, quit, q, qq</td>
+<td>no</td>
+<td>exit</td>
+</tr>
+<tr><td>help, ?</td>
+<td>no</td>
+<td>print help message (list known commands)</td>
+</tr>
+<tr><td>help <em>cmd</em></td>
+<td>no</td>
+<td>show command-specific help message</td>
+</tr>
+<tr><td>alias</td>
+<td>no</td>
+<td>show command aliases</td>
+</tr>
+<tr><td>unalias</td>
+<td>no</td>
+<td>unset command aliases (<em>not implemented</em>)</td>
+</tr>
+<tr><td>cat</td>
+<td><strong>yes</strong></td>
+<td>read files and print them (supports compressed
+files)</td>
+</tr>
+<tr><td>cd</td>
+<td>no</td>
+<td><p class="first">change working directory</p>
+<p class="last">Actually, this does not change the working
+directory. It simply sets the prefix which is used
+when dealing with relative filesystem paths.</p>
+</td>
+</tr>
+<tr><td>chroot</td>
+<td>no</td>
+<td><p class="first">enter/leave/show command chroot</p>
+<p class="last">A command chroot prefixes all input with a
+specific command.</p>
+</td>
+</tr>
+<tr><td>declare</td>
+<td>no</td>
+<td>show variables</td>
+</tr>
+<tr><td>echo</td>
+<td>no</td>
+<td>print text (supports python string formatting)</td>
+</tr>
+<tr><td>exec</td>
+<td>no</td>
+<td>switch to another subsystem (<em>not implemented</em>)</td>
+</tr>
+<tr><td>history</td>
+<td>no</td>
+<td>show command history</td>
+</tr>
+<tr><td>ls</td>
+<td>no</td>
+<td>print directory content</td>
+</tr>
+<tr><td>pwd</td>
+<td>no</td>
+<td>print current working directory</td>
+</tr>
+<tr><td>set</td>
+<td>no</td>
+<td>set variables</td>
+</tr>
+<tr><td>unset</td>
+<td>no</td>
+<td>unset variables</td>
+</tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">Running the console with <tt class="docutils literal">python <span class="pre">-OO</span></tt> removes most of the help messages.</p>
+</div>
<div class="section" id="dependency-resolution-console">
<span id="depres-console"></span><h2><a class="toc-backref" href="#contents">12.1 Dependency Resolution Console</a></h2>
-<div class="warning">
-<p class="first admonition-title">Warning</p>
-<p class="last">This section is out-of-date.</p>
-</div>
<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">
<li>resolve dependencies</li>
<li>create new dependency rules</li>
-<li>create dependency rules for each R package found in a directory</li>
<li>load rules from files</li>
<li>save rules to a file</li>
</ul>
<p>Rules are managed in a set. These so-called <em>rule pools</em> are organized in
-a <em>first-in-first-out</em> data structure that allows
-to create or remove them easily at runtime.</p>
-<p>Running <tt class="docutils literal">roverlay depres_console</tt> will print a welcome message that
-lists all available commands and a few usage hints.</p>
-<p>For reference, these commands are currently available:</p>
-<p><<TODO: rewrite/update command table, it's out-of-date>></p>
+a <em>first-in-first-out</em> data structure that allows to create or remove
+them easily at runtime.</p>
+<p>Running <tt class="docutils literal">roverlay depres_console</tt> prints a short welcome message and starts
+the console.</p>
+<p>For reference, these commands are available (in addition to the basic ones):</p>
<table border="1" class="docutils">
+<caption>depres commands</caption>
<colgroup>
-<col width="29%" />
-<col width="71%" />
+<col width="25%" />
+<col width="12%" />
+<col width="63%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">command</th>
+<th class="head">extended
+--help</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
-<tr><td>help,
-h, ?</td>
-<td>lists all commands</td>
-</tr>
-<tr><td>help <em><cmd></em>,
-h <em><cmd></em></td>
-<td>prints a command-specific help message</td>
-</tr>
-<tr><td>load <em><file|dir></em>,
-l <em><file|dir></em></td>
-<td>loads a rule file or a directory with rule files
-into a new <em>rule pool</em></td>
-</tr>
-<tr><td>load_conf,
-lc</td>
-<td>loads the rule files listed in the config file
-into a new <em>rule pool</em></td>
-</tr>
-<tr><td>add_rule <em><rule></em>
-+ <em><rule></em></td>
+<tr><td>add_pool, <<</td>
+<td>no</td>
+<td>creates a new, empty <em>rule pool</em></td>
+</tr>
+<tr><td>add_rule, +</td>
+<td>no</td>
<td>creates a new rule and adds it to the topmost,
i.e. latest <em>rule pool</em>. This command uses
<a class="reference internal" href="#rule-file-syntax">Rule File Syntax</a>. Multi line rules are
supported.</td>
</tr>
-<tr><td>add_pool,
-<<</td>
-<td>creates a new <em>rule pool</em></td>
+<tr><td>load, l</td>
+<td>yes</td>
+<td>load rule files</td>
</tr>
-<tr><td>unwind_pool,
->></td>
-<td>removes the topmost <em>rule pool</em> and all of its
-rules</td>
+<tr><td>load_conf, lc</td>
+<td>no</td>
+<td>load configured rule files</td>
+</tr>
+<tr><td>print_pool, print,
+p</td>
+<td>yes</td>
+<td>print one or more <em>rule pools</em></td>
</tr>
-<tr><td>resolve <em><dep></em>,
-?? <em><dep></em></td>
+<tr><td>resolve, ??</td>
+<td>no</td>
<td>tries to resolve the given dependency string and
prints the result</td>
</tr>
+<tr><td>unwind_pool, >></td>
+<td>yes</td>
+<td>removes the topmost <em>rule pool</em> and all of its
+rules</td>
+</tr>
+<tr><td>write, w</td>
+<td>yes</td>
+<td>writes rules to a file</td>
+</tr>
<tr><td>!</td>
-<td>enter the resolve <em>command chroot</em>
-all input will be prefixed with "resolve"</td>
+<td>no</td>
+<td>enter the <em>resolve command chroot</em>, which prefixes
+all input with <em>resolve</em></td>
</tr>
<tr><td>!!</td>
+<td>no</td>
<td>leave any <em>command chroot</em></td>
</tr>
-<tr><td>print, p</td>
-<td>prints the rules of the topmost <em>rule pool</em></td>
-</tr>
-<tr><td>print --all|-a</td>
-<td>prints the rules of all <em>rule pools</em></td>
-</tr>
-<tr><td>print <id> [<id>..]</td>
-<td>prints the rules of a specific <em>rule pool</em></td>
-</tr>
-<tr><td>write <em><file></em>,
-w <em><file></em></td>
-<td>writes the rules of the topmost <em>rule pool</em> into
-<em><file></em>. See write --help for advanced usage.</td>
-</tr>
-<tr><td>cd <em><dir></em></td>
-<td>changes the working directory
-This is a virtual command. <<TODO:EXPLAIN>></td>
-</tr>
-<tr><td>set VAR=VALUE</td>
-<td>set variables</td>
-</tr>
-<tr><td>unset VAR</td>
-<td>unset variables</td>
-</tr>
-<tr><td>declare</td>
-<td>show declared variables</td>
-</tr>
-<tr><td>alias</td>
-<td>show command aliases</td>
-</tr>
-<tr><td>unalias</td>
-<td>reserved for future usage</td>
-</tr>
-<tr><td>exit, qq, q</td>
-<td>exits the <em>DepRes Console</em></td>
-</tr>
</tbody>
</table>
-<div class="note">
-<p class="first admonition-title">Note</p>
-<p class="last">Some commands also offer more detailed help via <tt class="docutils literal"><command> <span class="pre">--help</span></tt>.</p>
-</div>
-<p><<TODO>></p>
-<p><<Example Session is out-of-date>></p>
<dl class="docutils">
<dt>Example Session:</dt>
<dd><pre class="code first last literal-block">
-== depres console ==
-Run 'help' to list all known commands
-More specifically, 'help <cmd>' prints a help message for the given
-command, and 'help --list' lists all help topics available
-Use 'load_conf' or 'lc' to load the configured rule files
-
-commands: load, unwind, set, help, >>, load_conf, <<, cd, mkhelp,
-resolve, lc, add_pool, addrule, h, +, l, li, write, p, r, ?, w, print,
-sd, unset, scandir
-exit-commands: q, qq, exit
+[roverlay depres_console]
+
+== dependency resolution console (r2) ==
+Run 'help' to list all known commands.
+More specifically, 'help <cmd>' prints a help message for
+the given command, and 'help --list' lists all help topics.
+Use 'load_conf' or 'lc' to load the configured rule files.
+
+cmd % help
+
+Documented commands (type help <topic>):
+========================================
+EOF cat echo history print qq unalias
+add_pool cd exec load print_pool quit unset
+add_rule chroot exit load_conf pwd resolve unwind_pool
+alias declare help ls q set write
+
+cmd % <tab><tab>
+EOF chroot history pwd unalias
+add_pool declare load q unset
+add_rule echo load_conf qq unwind_pool
+alias exec ls quit write
+cat exit print resolve
+cd help print_pool set
cmd % + ~dev-lang/R :: R language
-new rules:
+
+cmd % print --help
+usage: print_pool [-h] [--all] [<id> [<id> ...]]
+
+positional arguments:
+ <id> print specific pools (by id)
+
+optional arguments:
+ -h, --help show this help message and exit
+ --all, -a print all pools
+
+cmd % print -a
~dev-lang/R :: R language
---- ---
-command succeeded.
-cmd % ? R language
-Trying to resolve ('R language',).
-Resolved as: ('dev-lang/R',)
+cmd % !
+
+(resolve) % R language
+'R language' has been resolved as dev-lang/R.
-cmd % ? R language [ 2.15 ]
-Trying to resolve ('R language [ 2.15 ]',).
-Resolved as: ('>=dev-lang/R-2.15',)
+(resolve) % R language [ 2.15 ]
+'R language [ 2.15 ]' has been resolved as >=dev-lang/R-2.15.
-cmd % ? R
-Trying to resolve ('R',).
-Channel returned None. At least one dep could not be resolved.
+(resolve) % R
+'R' could not be resolved.
+
+(resolve) % !!
cmd % p
~dev-lang/R :: R language
cmd % >>
-Pool removed from resolver.
+pool has been removed.
+
+cmd % >>
+resolver has no pools.
cmd % p
-cmd % ? R language
-Trying to resolve ('R language',).
-Channel returned None. At least one dep could not be resolved.
-cmd % exit
+cmd % ?? R language
+'R language' could not be resolved.
+
+cmd % set PS1=#!
+
+#! exit
</pre>
</dd>
</dl>
@@ -3708,7 +3834,7 @@ cmd % exit
<div class="section" id="roverlay-interface">
<h1><a class="toc-backref" href="#contents">13 Roverlay Interface</a></h1>
<p>Roverlay provides an API for accessing its functionality independently of
-R overlay creation. Only dependency resolution is available, currently.</p>
+R overlay creation.</p>
<p>Note, however, that a minimal config file may still be required for accessing
<em>roverlay interfaces</em>.</p>
<p>The table below lists all interfaces and where to find them:</p>
@@ -3775,7 +3901,16 @@ for usage examples.</p>
</div>
<div class="section" id="remote-interface">
<h2><a class="toc-backref" href="#contents">13.2 Remote Interface</a></h2>
-<p><<TODO; this interface isn't mature enough yet (it will likely change in future)>></p>
+<p>The <em>RemoteInterface</em> is experimental/incomplete and currently offers the
+following functionality:</p>
+<ul class="simple">
+<li>set sync mode to online/offline</li>
+<li>sync/nosync</li>
+<li>load repo config</li>
+<li>list repos</li>
+<li>list repo packages</li>
+</ul>
+<p>Refer to in-code documentation for details.</p>
</div>
</div>
<div class="section" id="implementation-overview">
@@ -4002,12 +4137,12 @@ would require variable interpolation, e.g. for <tt class="docutils literal">${PN
<h2><a class="toc-backref" href="#contents">14.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>
+<p>An <em>EbuildCreationJob</em> does the following steps:</p>
<ol class="arabic simple">
<li>Read the DESCRIPTION file of <em>p</em> R package tarball and stores the
data in an associative array ('DESCRIPTION field' -> 'data')</li>
<li>Call <a class="reference internal" href="#dependency-resolution">dependency resolution</a></li>
-<li>If dependency resolution was successful and any <em>selfdeps</em> found
+<li>If dependency resolution was successful and any <a class="reference internal" href="#selfdeps">selfdeps</a> found
(dependencies on other packages): <em>pause</em> ebuild creation for <em>p</em> until
it has been verified whether these dependencies are satisfiable.
This is necessary because dependency resolution does not know whether a
@@ -4045,9 +4180,121 @@ for a <em>PackageInfo</em> object and inform the <em>OverlayCreation</em> about
afterwards. Overlay creation keeps going if an ebuild cannot be created,
instead the event is logged. Running more than one <em>OverlayWorker</em> in parallel
is possible.</p>
+<p>The following pseudo-code illustrates how overlay creation basically works:</p>
+<pre class="code text literal-block">
+ACCEPT_PACKAGES:
+
+for each received PackageInfo <p>
+
+ create an EbuildCreationJob for p and add it to the work queue
+
+end for
+
+
+
+CREATE_OVERLAY:
+
+while work_queue is not empty
+
+ work_queue_next <= empty
+
+
+ in parallel with N OverlayWorkers (>=0 threads):
+
+ for each EbuildCreationJob ebuild_job from the work_queue
+
+ run/resume ebuild_job (as described in Ebuild Creation)
+
+ if ebuild_job is paused
+
+ add ebuild_job to work_queue_next
+
+ end if
+
+ end for
+
+ end in parallel
+
+
+ if work_queue_next is not empty
+
+ <run selfdep validation>
+
+ work_queue <= work_queue_next
+
+ end if
+
+end while
+</pre>
<div class="section" id="selfdep-validation">
<h3><a class="toc-backref" href="#contents">14.5.1 Selfdep Validation</a></h3>
-<p><<TODO: specify algo here>></p>
+<p>EbuildCreationJobs are processed in no specific order and possibly
+concurrently. This leads to the problem that dependency resolution cannot
+know whether a successfully resolved <a class="reference internal" href="#selfdep">selfdep</a> is actually satisfiable.</p>
+<p>For example, if a package <em>A</em> depends on another package <em>B</em> and <em>B</em> is
+uncreatable (ebuild creation <em>will</em> fail for <em>B</em>), then dependency resolution
+still resolves <em>B</em> (e.g. as sci-R/B). <em>A</em> has a <strong>dangling selfdep</strong> now.</p>
+<p><em>Selfdep validation</em> is the process of <strong>identifying</strong> <em>dangling selfdeps</em> and
+<strong>removing</strong> packages with such dependencies or simply <strong>dropping</strong>
+the dependencies, depending on their <a class="reference internal" href="#dependency-type">dependency type</a>.</p>
+<p>It is an algorithm with 3 phases:</p>
+<ol class="arabic simple">
+<li><strong>prepare</strong>: create a graph containing all selfdeps<ul>
+<li><strong>collect</strong>: find ebuild creation jobs with selfdeps (<em>direct</em> selfdeps)</li>
+<li><strong>link</strong>: expand the selfdep graph, find selfdep-selfdep dependencies
+(<em>indirect</em> selfdeps)</li>
+</ul>
+</li>
+<li><strong>reduce</strong>: find <em>dangling selfdeps</em> and mark them as invalid<ul>
+<li>a selfdep is <em>dangling</em> iff the overlay contains no suitable
+<em>PackageInfo</em> with valid selfdeps</li>
+<li><strong>repeat this step</strong> until no more <em>dangling selfdeps</em> found</li>
+</ul>
+</li>
+<li><strong>balance</strong>: find ebuild creation jobs with invalid selfdeps (<em>inversed collect</em>)<ul>
+<li>drop optional dependencies</li>
+<li>let ebuild creation fail if a mandatory selfdep is not valid</li>
+</ul>
+</li>
+</ol>
+<p>The actual implementation in <em>roverlay</em> is spread across several modules:</p>
+<table border="1" class="docutils">
+<caption>modules/packages involved in selfdep validation</caption>
+<colgroup>
+<col width="42%" />
+<col width="58%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">module/package</th>
+<th class="head">phase(s) / description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>roverlay.overlay.creator</td>
+<td><strong>all</strong> (controls selfdep validation),
+especially <em>collect</em> and
+<em>reduction loop</em></td>
+</tr>
+<tr><td>roverlay.ebuild.creation
+roverlay.ebuild.depres</td>
+<td><strong>prepare</strong> (<em>collect</em>),
+<strong>balance</strong> (<em>drop dependencies</em>,
+<em>ebuild creation failure</em>)</td>
+</tr>
+<tr><td>roverlay.overlay.root
+roverlay.overlay.category
+roverlay.overlay.pkgdir</td>
+<td><strong>prepare</strong> (<em>link</em>),
+<strong>balance</strong> (<em>remove packages</em>)</td>
+</tr>
+<tr><td>roverlay.depres.depresult</td>
+<td><strong>all</strong> (selfdep data object)</td>
+</tr>
+<tr><td>roverlay.packageinfo</td>
+<td><strong>all</strong> (package data object),</td>
+</tr>
+</tbody>
+</table>
</div>
</div>
<div class="section" id="dependency-resolution">
@@ -4073,7 +4320,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">14.6.1 Dependency types</a></h3>
+<span id="dependency-type"></span><h3><a class="toc-backref" href="#contents">14.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">
@@ -4282,13 +4529,15 @@ while <dependencies queued for resolution>
else
if <a rule pool accepts depenv's type and resolves depenv>
+
resolved <= True
else if <depenv's type contains TRY_OTHER>
-
if <a rule pool supports TRY_OTHER and does not accept depenv's type and resolves depenv>
resolved <= True
+
+ end if
end if
end if
@@ -4315,7 +4564,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-08-02.
+Generated on: 2013-08-06.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-08-07 16:10 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-08-07 16:10 UTC (permalink / raw
To: gentoo-commits
commit: 5a515917f750a1ffe7e64dce2bf569a306b149f7
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Aug 7 15:56:18 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Aug 7 15:56:18 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=5a515917
update doc/html/usage.html (generated file)
---
doc/html/usage.html | 194 +++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 148 insertions(+), 46 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 39d7e63..55ad457 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -424,53 +424,54 @@ ul.auto-toc {
</li>
<li><a class="reference internal" href="#id3" id="id65">11 Other config files</a><ul class="auto-toc">
<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id66">11.1 USE_EXPAND flag rename file</a></li>
-<li><a class="reference internal" href="#field-definition-config" id="id67">11.2 Field Definition Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id68">11.2.1 Example: The default field definition file</a></li>
+<li><a class="reference internal" href="#license-map-file" id="id67">11.2 License Map File</a></li>
+<li><a class="reference internal" href="#field-definition-config" id="id68">11.3 Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id69">11.3.1 Example: The default field definition file</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#id5" id="id69">12 Roverlay Console</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-resolution-console" id="id70">12.1 Dependency Resolution Console</a></li>
+<li><a class="reference internal" href="#id5" id="id70">12 Roverlay Console</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-resolution-console" id="id71">12.1 Dependency Resolution Console</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#roverlay-interface" id="id71">13 Roverlay Interface</a><ul class="auto-toc">
-<li><a class="reference internal" href="#depres-interface" id="id72">13.1 DepRes Interface</a></li>
-<li><a class="reference internal" href="#remote-interface" id="id73">13.2 Remote Interface</a></li>
+<li><a class="reference internal" href="#roverlay-interface" id="id72">13 Roverlay Interface</a><ul class="auto-toc">
+<li><a class="reference internal" href="#depres-interface" id="id73">13.1 DepRes Interface</a></li>
+<li><a class="reference internal" href="#remote-interface" id="id74">13.2 Remote Interface</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#implementation-overview" id="id74">14 Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#packageinfo" id="id75">14.1 PackageInfo</a></li>
-<li><a class="reference internal" href="#repository-management" id="id76">14.2 Repository Management</a><ul class="auto-toc">
-<li><a class="reference internal" href="#repository" id="id77">14.2.1 Repository</a><ul class="auto-toc">
-<li><a class="reference internal" href="#adding-new-repository-types" id="id78">14.2.1.1 Adding new repository types</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id75">14 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id76">14.1 PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id77">14.2 Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#repository" id="id78">14.2.1 Repository</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id79">14.2.1.1 Adding new repository types</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay" id="id79">14.3 Overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#metadata-creation" id="id80">14.3.1 Metadata Creation</a></li>
-<li><a class="reference internal" href="#manifest-creation" id="id81">14.3.2 Manifest Creation</a></li>
+<li><a class="reference internal" href="#overlay" id="id80">14.3 Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id81">14.3.1 Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id82">14.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#ebuild-creation" id="id82">14.4 Ebuild Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#ebuild-variables" id="id83">14.4.1 Ebuild Variables</a></li>
+<li><a class="reference internal" href="#ebuild-creation" id="id83">14.4 Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id84">14.4.1 Ebuild Variables</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay-creation" id="id84">14.5 Overlay Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#selfdep-validation" id="id85">14.5.1 Selfdep Validation</a></li>
+<li><a class="reference internal" href="#overlay-creation" id="id85">14.5 Overlay Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#selfdep-validation" id="id86">14.5.1 Selfdep Validation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution" id="id86">14.6 Dependency Resolution</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id87">14.6.1 Dependency types</a><ul class="auto-toc">
-<li><a class="reference internal" href="#description-file-dependency-fields" id="id88">14.6.1.1 DESCRIPTION file dependency fields</a></li>
+<li><a class="reference internal" href="#dependency-resolution" id="id87">14.6 Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id88">14.6.1 Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id89">14.6.1.1 DESCRIPTION file dependency fields</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-environments" id="id89">14.6.2 Dependency Environments</a></li>
-<li><a class="reference internal" href="#ebuildjob-channel" id="id90">14.6.3 EbuildJob Channel</a></li>
-<li><a class="reference internal" href="#dependency-rule-pools" id="id91">14.6.4 Dependency Rule Pools</a></li>
-<li><a class="reference internal" href="#dependency-resolver-modules" id="id92">14.6.5 Dependency Resolver Modules</a></li>
-<li><a class="reference internal" href="#dependency-resolver" id="id93">14.6.6 Dependency Resolver</a></li>
+<li><a class="reference internal" href="#dependency-environments" id="id90">14.6.2 Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id91">14.6.3 EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id92">14.6.4 Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id93">14.6.5 Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id94">14.6.6 Dependency Resolver</a></li>
</ul>
</li>
</ul>
@@ -503,18 +504,23 @@ does and what to expect from the generated overlay.</p>
</li>
<li><p class="first"><em>roverlay</em> maintainers who <strong>control and test overlay creation</strong>,
e.g. configure which R packages will be part of the generated overlay</p>
-<p>Depending on what you want to configure, chapters 5-10 are relevant,
+<p>Depending on what you want to configure, chapters 5-11 are relevant,
namely <a class="reference internal" href="#repositories-getting-packages">Repositories / Getting Packages</a>, <cite>Additions Directory</cite>,
<a class="reference internal" href="#dependency-rules">Dependency Rules</a>, <a class="reference internal" href="#package-rules">Package Rules</a>, <a class="reference internal" href="#configuration-reference">Configuration Reference</a>
and <a class="reference internal" href="#field-definition-config">Field Definition Config</a>.</p>
<p>There is another chapter that is only interesting for testing, the
-<a class="reference internal" href="#dependency-resolution-console">Dependency Resolution Console</a> (11), which can be used to interactively
-test dependency rules.</p>
+<a class="reference internal" href="#dependency-resolution-console">Dependency Resolution Console</a> (12.1), which can be used to
+interactively test dependency rules.</p>
</li>
<li><p class="first"><em>roverlay</em> code maintainers who want to know <strong>how roverlay works</strong> for
code improvements etc.</p>
-<p>The most important chapter is <a class="reference internal" href="#implementation-overview">Implementation Overview</a> (12) which has
-references to other chapters (4-10) where required.</p>
+<p>The most important chapter is <a class="reference internal" href="#implementation-overview">Implementation Overview</a> (14) which has
+references to other chapters (4-13) where required.</p>
+</li>
+<li><p class="first">developers who intend to <strong>use roverlay's functionality outside of roverlay</strong></p>
+<p>The most important chapter is <a class="reference internal" href="#roverlay-interface">Roverlay Interface</a>, which gives an
+overview of <em>roverlay's</em> API.
+Reading the other chapters (4-14) is recommended.</p>
</li>
</ul>
</blockquote>
@@ -639,17 +645,15 @@ as the <em>R Overlay src directory</em> from now on.</p>
<div class="section" id="required-configuration-steps">
<h2><a class="toc-backref" href="#contents">3.1 Required configuration steps</a></h2>
<p><em>roverlay</em> needs a configuration file to run.
-If roverlay has been installed with <em>emerge</em>, it will look for the config file in
-that order:</p>
+If roverlay has been installed with <em>emerge</em>,
+it will look for the config file in that order:</p>
<ol class="arabic simple">
-<li><em><current directory>/R-overlay.conf</em></li>
<li><em>~/roverlay/R-overlay.conf</em></li>
<li><em>/etc/roverlay/R-overlay.conf</em>,
which is part of the installation but has to be modified.</li>
</ol>
-<p>Otherwise, <em>roverlay</em> will only look for <em>R-overlay.conf</em> in the current
-directory. An example config file is available in the
-<em>R Overlay src directory</em>.</p>
+<p>Otherwise, <em>roverlay</em> uses <em>R-overlay.conf</em> in the current directory.
+An example config file is available in the <em>R Overlay src directory</em>.</p>
<p>The config file is a text file with '<option> = <value>' syntax. Some options
accept multiple values (e.g. <option> = file1, file2), in which case the
values have to be enclosed with quotes (-> <tt class="docutils literal"><option> = "file1 file2"</tt>).</p>
@@ -846,6 +850,10 @@ to know in detail what <em>roverlay</em> does before running it.</p>
<kbd><span class="option">--nosync</span>, <span class="option">--no-sync</span></kbd></td>
</tr>
<tr><td> </td><td>Disable downloading of R packages.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--strict</span></kbd></td>
+<td>Enable strict behavior.
+For example, this causes <em>roverlay</em> to exit if any repo cannot be synced.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--distmap-verify</span></kbd></td>
</tr>
@@ -1086,6 +1094,7 @@ eclass file are used, the result should look like:</p>
<overlay root>/
<overlay root>/eclass
<overlay root>/eclass/R-packages.eclass
+<overlay root>/metadata/layout.conf
<overlay root>/profiles
<overlay root>/profiles/categories
<overlay root>/profiles/repo_name
@@ -3428,7 +3437,7 @@ on <em>roverlay</em> exit. Primarily useful for creating new rules.</p>
sound = audio snd
</pre>
<p>Each flag is renamed at most once, so the following example renames 'sound'
-to media, but 'audio' to 'sound':;</p>
+to media, but 'audio' to 'sound':</p>
<pre class="code text literal-block">
sound = audio snd
media = sound video
@@ -3439,8 +3448,56 @@ media = sound video
unpredictable results.</p>
</div>
</div>
+<div class="section" id="license-map-file">
+<h2><a class="toc-backref" href="#contents">11.2 License Map File</a></h2>
+<p>The license map file is a file with dictionary-like entries that is used
+to translate <em>license strings</em> (read from the package's DESCRIPTION) into
+licenses accepted by portage, e.g. <tt class="docutils literal"><span class="pre">GPL-3</span></tt> or <tt class="docutils literal">|| ( <span class="pre">GPL-3+</span> BSD )</tt>.
+Its syntax is similar to the dependency rule file syntax:</p>
+<pre class="code text literal-block">
+# this is a comment line
+
+# 1,1 mapping
+portage_license :: license_str
+
+# 1,n mapping (n>=0)
+portage_license {
+ license_str_0
+ license_str_1
+ ...
+ license_str_n
+}
+
+# 0,1 mapping (ignore license_str)
+! :: license_str
+
+# 0,n mapping (ignore several license_str)
+! {
+ license_str_0
+ license_str_1
+ ...
+ license_str_n
+}
+</pre>
+<p>Example (excerpt from <em>roverlay's</em> license map file):</p>
+<pre class="code text literal-block">
+# freestyle text
+! {
+ foo
+ freeforresearchpurpose.
+ whatlicenseisitunder?
+}
+
+BSD :: freebsd
+
+|| ( GPL-2+ BSD ) {
+ gpl>2|bsd
+ gpl>2|freebsd
+}
+</pre>
+</div>
<div class="section" id="field-definition-config">
-<span id="id4"></span><h2><a class="toc-backref" href="#contents">11.2 Field Definition Config</a></h2>
+<span id="id4"></span><h2><a class="toc-backref" href="#contents">11.3 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>
@@ -3528,7 +3585,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">11.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.3.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>
@@ -3572,7 +3629,8 @@ such a field is found.</dd>
<span id="roverlay-console"></span><h1><a class="toc-backref" href="#contents">12 Roverlay Console</a></h1>
<p>roverlay provides an interactive console for accessing certain subsystems,
e.g. dependency resolution. Its features include tab completion for filesystem
-paths and a command history that supports navigation with the arrow keys.</p>
+paths and a command history that supports navigation with the arrow keys.
+Line continuation with a backslash character <tt class="docutils literal">\</tt> is supported, too.</p>
<p>The console also implements a subset of typical tools like <tt class="docutils literal">cat</tt>, which
behave similar but not identical to their counterparts.</p>
<p>See the following sections for how to run specific consoles.</p>
@@ -3683,7 +3741,7 @@ It is an interactive console with the following features:</p>
<li>save rules to a file</li>
</ul>
<p>Rules are managed in a set. These so-called <em>rule pools</em> are organized in
-a <em>first-in-first-out</em> data structure that allows to create or remove
+a <em>last-in-first-out</em> data structure that allows to create or remove
them easily at runtime.</p>
<p>Running <tt class="docutils literal">roverlay depres_console</tt> prints a short welcome message and starts
the console.</p>
@@ -3874,6 +3932,42 @@ initialization</td>
</table>
<p>For extending the API, roverlay provides the abstract <em>RoverlayInterface</em> and
<em>RoverlaySubInterface</em> classes.</p>
+<p>The following code snippet gives an idea on how to include roverlay's API in
+your code:</p>
+<pre class="code python literal-block">
+<span class="comment">#!/usr/bin/python</span>
+<span class="comment">#</span>
+<span class="comment"># Initializes logging and roverlay's interfaces</span>
+<span class="comment">#</span>
+
+<span class="keyword namespace">import</span> <span class="name namespace">logging</span>
+
+<span class="keyword namespace">import</span> <span class="name namespace">roverlay.core</span>
+<span class="keyword namespace">import</span> <span class="name namespace">roverlay.interface.main</span>
+
+<span class="keyword">def</span> <span class="name function">main</span><span class="punctuation">():</span>
+ <span class="comment"># log everything to console</span>
+ <span class="name">roverlay</span><span class="operator">.</span><span class="name">core</span><span class="operator">.</span><span class="name">force_console_logging</span> <span class="punctuation">(</span> <span class="name">log_level</span><span class="operator">=</span><span class="name">logging</span><span class="operator">.</span><span class="name">INFO</span> <span class="punctuation">)</span>
+
+ <span class="comment"># load roverlay's config</span>
+ <span class="name">config</span> <span class="operator">=</span> <span class="name">roverlay</span><span class="operator">.</span><span class="name">core</span><span class="operator">.</span><span class="name">load_locate_config_file</span> <span class="punctuation">(</span>
+ <span class="name">ROVERLAY_INSTALLED</span><span class="operator">=</span><span class="name builtin pseudo">False</span><span class="punctuation">,</span> <span class="name">setup_logger</span><span class="operator">=</span><span class="name builtin pseudo">False</span>
+ <span class="punctuation">)</span>
+
+ <span class="comment"># create the main interface</span>
+ <span class="name">main_interface</span> <span class="operator">=</span> <span class="name">roverlay</span><span class="operator">.</span><span class="name">interface</span><span class="operator">.</span><span class="name">main</span><span class="operator">.</span><span class="name">MainInterface</span> <span class="punctuation">(</span> <span class="name">config</span><span class="operator">=</span><span class="name">config</span> <span class="punctuation">)</span>
+
+ <span class="comment"># create subinterfaces, as needed</span>
+ <span class="name">depres_interface</span> <span class="operator">=</span> <span class="name">main_interface</span><span class="operator">.</span><span class="name">spawn_interface</span> <span class="punctuation">(</span> <span class="literal string">"depres"</span> <span class="punctuation">)</span>
+ <span class="name">remote_interface</span> <span class="operator">=</span> <span class="name">main_interface</span><span class="operator">.</span><span class="name">spawn_interface</span> <span class="punctuation">(</span> <span class="literal string">"remote"</span> <span class="punctuation">)</span>
+
+ <span class="comment"># use them</span>
+ <span class="keyword">pass</span>
+<span class="comment"># --- end of main (...) ---</span>
+
+<span class="keyword">if</span> <span class="name">__name__</span> <span class="operator">==</span> <span class="literal string">'__main__'</span><span class="punctuation">:</span>
+ <span class="name">main</span><span class="punctuation">()</span>
+</pre>
<div class="section" id="depres-interface">
<h2><a class="toc-backref" href="#contents">13.1 DepRes Interface</a></h2>
<p>The <em>DepResInterface</em> offers the following functionality:</p>
@@ -4097,8 +4191,8 @@ is not.</p>
<li><p class="first">Write the overlay to its filesystem location</p>
<blockquote>
<ul class="simple">
-<li>initialize the overlay (write the <em>profiles/</em> directory,
-import eclass files)</li>
+<li>initialize the overlay (write the <em>profiles/</em> directory and
+<em>metadata</em>/layout.conf, import eclass files)</li>
<li>Write ebuilds; all <em>PackageInfo</em> instances with an ebuild will be written</li>
<li>Generate and write metadata</li>
<li>Write Manifest files</li>
@@ -4165,6 +4259,14 @@ as <em>ebuild successfully created</em></li>
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
to an <em>Ebuilder</em> that automatically sorts them and creates the ebuild.</p>
+<p>Most ebuild variables, e.g. all variables that contain text from a package's
+DESCRIPTION data, have basic protection against code injection:</p>
+<ul class="simple">
+<li>only ASCII characters are allowed</li>
+<li>the following chars are always removed: <tt class="docutils literal">"</tt>, <tt class="docutils literal">'</tt>, <tt class="docutils literal">`</tt> and <tt class="docutils literal">;</tt></li>
+<li>backslash chars <tt class="docutils literal">\</tt> at the end of the variable's value are removed</li>
+<li>any char sequence starting with <tt class="docutils literal">$(</tt> is completely dropped</li>
+</ul>
</div>
</div>
<div class="section" id="overlay-creation">
@@ -4564,7 +4666,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-08-06.
+Generated on: 2013-08-07.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-08-09 15:28 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-08-09 15:28 UTC (permalink / raw
To: gentoo-commits
commit: e6b6f976f718b048c80bd1ce707523c1f2fa7d97
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Aug 9 15:23:26 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Aug 9 15:23:26 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=e6b6f976
doc/html/usage.html (generated file)
---
doc/html/usage.html | 133 ++++++++++++++++++++++++++++++++++------------------
1 file changed, 87 insertions(+), 46 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 55ad457..86ea414 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -362,7 +362,7 @@ ul.auto-toc {
<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id26">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="id27">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="id28">5.5 Using local directories</a></li>
-<li><a class="reference internal" href="#distmap" id="id29">5.6 distmap</a></li>
+<li><a class="reference internal" href="#distmap" id="id29">5.6 Distmap</a></li>
</ul>
</li>
<li><a class="reference internal" href="#additions-directory" id="id30">6 Additions Directory</a><ul class="auto-toc">
@@ -537,46 +537,49 @@ Reading the other chapters (4-14) is recommended.</p>
<div class="section" id="prerequisites">
<h2><a class="toc-backref" href="#contents">2.1 Prerequisites</a></h2>
<ul>
-<li><p class="first">python >= 2.7 (tested with python 2.7 and 3.2)</p>
-</li>
-<li><p class="first">argparse (<a class="reference external" href="http://code.google.com/p/argparse">http://code.google.com/p/argparse</a>)</p>
+<li><p class="first">python >= 2.7 built with ssl support (tested with python 2.7 and 3.2)</p>
+<blockquote>
+<p>extra dependencies for python 2.7 (built-in since python 3.2)</p>
+<ul class="simple">
+<li>argparse (<a class="reference external" href="http://code.google.com/p/argparse">http://code.google.com/p/argparse</a>)</li>
+<li>concurrent.futures (<a class="reference external" href="http://pypi.python.org/pypi/futures">http://pypi.python.org/pypi/futures</a>) (optional)</li>
+</ul>
+</blockquote>
</li>
<li><p class="first">setuptools (<a class="reference external" href="http://pypi.python.org/pypi/setuptools">http://pypi.python.org/pypi/setuptools</a>)</p>
</li>
<li><p class="first">rsync (for using rsync repositories)</p>
</li>
-<li><p class="first">for Manifest creation:</p>
-<ul class="simple">
-<li>portage (<em>ebuild</em>)</li>
-<li><em>true</em> or <em>echo</em> from coreutils or busybox for preventing
-package downloads during Manifest creation (optional)</li>
-</ul>
+<li><p class="first">portage (<em>ebuild</em>) for Manifest creation and downloading source files for
+imported ebuilds</p>
+</li>
+<li><p class="first"><em>true</em> or <em>echo</em> from coreutils or busybox for preventing
+package downloads during Manifest creation (optional)</p>
</li>
<li><p class="first">for generating documentation files: python docutils >= 0.9</p>
</li>
<li><p class="first">hardware requirements (when using the default configuration):</p>
<blockquote>
-<dl class="docutils">
-<dt>disk</dt>
-<dd><ul class="first last simple">
+<p>disk</p>
+<ul class="simple">
<li>50-55GB disk space for the R packages</li>
<li>a filesystem that supports symbolic or hard links</li>
<li>there will be many small-sized files (ebuilds),
so a filesystem with lots of inodes and a small block size
may be advantageous</li>
</ul>
-</dd>
-<dt>memory</dt>
-<dd><p class="first last">up to 600MB which depends on the amount of processed packages and the
+<p>memory</p>
+<blockquote>
+<p>up to 600MB which depends on the amount of processed packages and the
write mechanism in use. The amount can be halved (approximately) when
using a slower one.</p>
-</dd>
-<dt>time</dt>
-<dd><p class="first last">Expect 1h execution time for the first run, depending on computing
+</blockquote>
+<p>time</p>
+<blockquote>
+<p>Expect 1h execution time for the first run, depending on computing
and I/O speed. <em>roverlay</em> is able to work in incremental mode,
thus making subsequent runs need a lot less time.</p>
-</dd>
-</dl>
+</blockquote>
</blockquote>
</li>
</ul>
@@ -816,10 +819,16 @@ they work.</dd>
<dt>Main Config</dt>
<dd>See <a class="reference internal" href="#configuration-reference">Configuration Reference</a> for all main config options like log file
rotation and assistance for writing new <em>dependency rules</em>.</dd>
+<dt>Patching generated ebuilds / Importing ebuilds</dt>
+<dd>See <a class="reference internal" href="#additions-directory">Additions Directory</a>.</dd>
+<dt>R_SUGGESTS</dt>
+<dd>See <a class="reference internal" href="#use-expand-flag-rename-file">USE_EXPAND flag rename file</a>, which describes how R_SUGGESTS
+USE_EXPAND flags can be renamed.</dd>
<dt>Field Definition</dt>
<dd>Refer to <a class="reference internal" href="#id4">Field Definition</a> in case you want to change <em>how</em> R packages
are being read, e.g. if you want the 'Depents' information field (obviously
-a typo) to be understood as 'Depends'.</dd>
+a typo) to be understood as 'Depends'. Also see <a class="reference internal" href="#license-map-file">License Map file</a> for
+translating <em>license strings</em> into valid portage licenses.</dd>
</dl>
</div>
</div>
@@ -963,6 +972,8 @@ been done, either to stdout or to <tt class="docutils literal"><span class="pre"
<p class="last">This command implies the <strong>sync</strong> command unless the <em>--nosync</em> option
is specified.</p>
</dd>
+<dt>setupdirs</dt>
+<dd>Creates all configured directories with proper permissions.</dd>
</dl>
</div>
<div class="section" id="providing-a-package-mirror">
@@ -986,7 +997,7 @@ most cases, but fine-tuning can be done via <a class="reference internal" href="
<a class="reference internal" href="#hook-environment">hook environment</a>.</p>
<p>roverlay-related scripts can use it to automatically inherit roverlay's
config and get access to its <tt class="docutils literal">$FUNCTIONS</tt> file:</p>
-<pre class="code sh last literal-block">
+<pre class="code sh literal-block">
<span class="comment">#!/usr/bin/roverlay-sh
</span>
<span class="comment"># load the functions file (optional)
@@ -995,13 +1006,20 @@ config and get access to its <tt class="docutils literal">$FUNCTIONS</tt> file:<
<span class="comment"># script body
</span><span class="name builtin">true</span>
</pre>
+<div class="note last">
+<p class="first admonition-title">Note</p>
+<p class="last"><em>roverlay-sh</em> requires a valid config file.</p>
+</div>
</dd>
<dt><em>roverlay-mkconfig</em></dt>
<dd>a script that creates a config file for roverlay</dd>
-<dt><em>name_is_todo--roverlay_creation_helper</em></dt>
-<dd><<TODO>>
-Safely runs overlay creation <<and $$afterwards>>.
-Suitable for being run as cron job.</dd>
+<dt><em>run-roverlay.sh</em></dt>
+<dd><p class="first">A script that safely runs overlay creation and repoman afterwards.
+Uses filesystem locks to ensure that it is run at most once at a time.
+Suitable for being run as cron job.</p>
+<p class="last">This file is not part of the roverlay installation. It can be found
+at <tt class="docutils literal"><span class="pre">files/scripts/run-roverlay.sh</span></tt> in the <a class="reference external" href="http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=summary">roverlay git repo</a>.</p>
+</dd>
</dl>
</div>
</div>
@@ -1023,19 +1041,21 @@ Suitable for being run as cron job.</dd>
<li><p class="first">all repositories are asked to list their packages which are then added
to a queue</p>
</li>
-<li><p class="first">packages may be declined by the overlay creator if they already have
-an ebuild</p>
-</li>
<li><p class="first">packages may be declined or manipulated by package rules</p>
<p>See also: <a class="reference internal" href="#package-rules">Package Rules</a></p>
</li>
+<li><p class="first">packages may be declined by the overlay creator if they already have
+an ebuild</p>
+<p>The overlay is able to detect changes to the package file, e.g. when
+upstream modified a package without renaming it. To realize this,
+the package file's checksum (sha256) is compared with the ebuild's
+entry in the <a class="reference internal" href="#distmap">distmap</a>. If they do match, then the package is declined
+as it already exists. Otherwise, a revision bump is triggered.</p>
+</li>
</ul>
</li>
<li><p class="first"><strong>create</strong> - process each package <em>p</em> from the package queue
(thread-able on a per package basis)</p>
-</li>
-</ol>
-<blockquote>
<ul>
<li><p class="first">read <em>p</em>'s DESCRIPTION file that contains information fields
like 'Depends', 'Description' and 'Suggests'</p>
@@ -1051,6 +1071,10 @@ cannot be resolved in which case a valid ebuild cannot be created</p>
</li>
<li><p class="first">verify dependencies on packages found in the overlay, whether their
ebuilds already exist or not (<em>selfdep validation</em>)</p>
+<ul class="simple">
+<li>drop unsatisfiable <em>selfdeps</em></li>
+<li><strong>stop</strong> processing <em>p</em> if a <em>required selfdep</em> is missing</li>
+</ul>
<p>See also: <a class="reference internal" href="#dependency-resolution">Dependency Resolution</a></p>
</li>
</ul>
@@ -1062,27 +1086,31 @@ and a few information fields like 'Description'</p>
and may decide to write <em>p</em>'s ebuild now (or later)</p>
</li>
</ul>
-</blockquote>
-<ol class="arabic simple" start="6">
-<li>write the overlay<ul>
-<li>write/update the profiles dir<ul>
+</li>
+<li><p class="first">write the overlay</p>
+<ul class="simple">
+<li>write/update the profiles dir and metadata/layout.conf<ul>
<li><em>roverlay</em> respects manual changes to USE_EXPAND description files</li>
</ul>
</li>
-<li>write all ebuilds and apply patches to them
-(supports threads on a per package basis)</li>
-<li>write the <em>metadata.xml</em> files
-(supports threads on a per package basis)<ul>
+<li>write all ebuilds and apply patches to them</li>
+<li>write the <em>metadata.xml</em> files<ul>
<li>this uses the latest created ebuild available for a package</li>
</ul>
</li>
-<li>write the <em>Manifest</em> files
-(does not support threads by default / supports threads on a per package
-basis when using <em>portage</em> directly)<ul>
+<li>write the <em>Manifest</em> files<ul>
<li>this uses all ebuilds availabe for a package</li>
</ul>
</li>
</ul>
+<p>Most write operations support threading.</p>
+</li>
+<li><p class="first">call the <em>overlay_success</em> hook</p>
+</li>
+<li><p class="first">write the stats database file (optional)</p>
+<ul class="simple">
+<li>call the <em>db_written</em> hook</li>
+</ul>
</li>
</ol>
</div>
@@ -1446,7 +1474,7 @@ consider using one of the <strong>websync</strong> repo types, <a class="referen
</div>
</div>
<div class="section" id="distmap">
-<h2><a class="toc-backref" href="#contents">5.6 distmap</a></h2>
+<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
@@ -2879,6 +2907,19 @@ the distmap file.</p>
<p class="last">This option is <strong>required</strong>.</p>
</dd>
</dl>
+<dl class="docutils" id="stats-db-file">
+<dt>STATS_DB</dt>
+<dd><p class="first">Path to the stats database file. This has to be a round-robin database
+file (rrdtool). <em>roverlay</em> creates it if necessary.</p>
+<p class="last">Defaults to <not set>, which disable database writing.</p>
+</dd>
+<dt>STATS_INTERVAL</dt>
+<dd><p class="first">Database update interval, which should be set to the expected timespan
+between running overlay creation, in seconds. Only meaningful when
+creating a new database file.</p>
+<p class="last">Defaults to 7200 (2 hours).</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>
@@ -4666,7 +4707,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-08-07.
+Generated on: 2013-08-09.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-08-19 15:42 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-08-19 15:42 UTC (permalink / raw
To: gentoo-commits
commit: 8b6dd116ee4a0e597a3c498c0b99af1d5ea2018d
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Mon Aug 19 15:41:46 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Mon Aug 19 15:41:46 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=8b6dd116
update doc/html/usage.html
---
doc/html/usage.html | 94 +++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 84 insertions(+), 10 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 62d3674..0f32e56 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -953,7 +953,7 @@ all other repositories. The <em>SRC_URI</em> ebuild variable will be invalid!</t
<dt>create</dt>
<dd>As described above, this will run ebuild, metadata creation, including
overlay and Manifest file writing.
-This command implies the <strong>sync</strong> command unless the <em>--nosync</em> option
+This command implies the <strong>sync</strong> command unless the <em>--no-sync</em> option
is specified.</dd>
<dt>sync</dt>
<dd>This will download all packages from the configured remotes.</dd>
@@ -968,7 +968,7 @@ and resolving dependencies.</p>
<dd><p class="first">Applies the package rules to all available packages and reports what has
been done, either to stdout or to <tt class="docutils literal"><span class="pre">--dump-file</span> <file></tt>.</p>
<p>Meant for testing.</p>
-<p class="last">This command implies the <strong>sync</strong> command unless the <em>--nosync</em> option
+<p class="last">This command implies the <strong>sync</strong> command unless the <em>--no-sync</em> option
is specified.</p>
</dd>
<dt>setupdirs</dt>
@@ -2067,7 +2067,7 @@ keyword(s)</th>
</thead>
<tbody valign="top">
<tr><td>AND</td>
-<td>and all &&</td>
+<td>all &&</td>
<td>all listed conditions must match</td>
</tr>
<tr><td>OR</td>
@@ -2085,6 +2085,14 @@ of the listed conditions must match</td>
<td>none
of the listed conditions must match</td>
</tr>
+<tr><td>VERUM</td>
+<td>any true</td>
+<td>always true</td>
+</tr>
+<tr><td>FALSUM</td>
+<td>none false</td>
+<td>always false</td>
+</tr>
</tbody>
</table>
<p>In other words, a (boolean) match keyword starts a <em>nested match block</em>
@@ -2100,8 +2108,9 @@ The nested block is terminated by indenting out, i.e. decreasing the
with a fixed number of conditions, e.g. 1. This is why there is no
<em>NOT</em> function. The definition for more than one condition would be
ambiguous, either <em>NOR</em> or <em>NAND</em>.</p>
-<p class="last">Correspondingly, the logic for the top-level match block is <em>AND</em> by
+<p>Correspondingly, the logic for the top-level match block is <em>AND</em> by
convention.</p>
+<p class="last"><em>VERUM</em> and <em>FALSUM</em> do accept any nested condition.</p>
</div>
<p>Using this syntax, match blocks can be nested indefinitely (minus technical
limitations):</p>
@@ -2242,8 +2251,11 @@ one only. The "/" delimitier in the sed expression can be any characte
<td>rename the ebuild</td>
</tr>
<tr><td>category</td>
-<td>yes / <strong>no</strong></td>
-<td>set package category</td>
+<td>yes / yes
+(<em>repo_name</em>)</td>
+<td>set or rename (based on the
+repository's name) the package's
+category</td>
</tr>
<tr><td>destfile</td>
<td>yes / yes</td>
@@ -2252,6 +2264,43 @@ one only. The "/" delimitier in the sed expression can be any characte
</tr>
</tbody>
</table>
+<p>The <em>set</em> action also supports variable substitution by means of python
+string formatting (<tt class="docutils literal">{info_key}</tt>), for example:</p>
+<pre class="code literal-block">
+set category sci-{repo_name}
+</pre>
+<p>The following <em>info keys</em> can be accessed:</p>
+<table border="1" class="docutils">
+<caption>info keys available for variable substitution</caption>
+<colgroup>
+<col width="29%" />
+<col width="71%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">info key</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>repo_name</td>
+<td>name of the repo, e.g. <em>CRAN</em></td>
+</tr>
+<tr><td>version</td>
+<td>package version <tt class="docutils literal">${PV}</tt></td>
+</tr>
+<tr><td>package_name</td>
+<td>package file name without version
+and file extension, e.g. <em>seewave</em></td>
+</tr>
+<tr><td>name</td>
+<td>ebuild name <tt class="docutils literal">${PN}</tt></td>
+</tr>
+<tr><td>package_filename</td>
+<td>package file name with file extension,
+e.g. <em>seewave_1.7.0.tar.gz</em></td>
+</tr>
+</tbody>
+</table>
<div class="caution">
<p class="first admonition-title">Caution!</p>
<p class="last">Category moves are not handled automatically. In incremental mode, overlay
@@ -2360,25 +2409,50 @@ ACTION:
set_category sci-bioc
END;
</pre>
+<p>A more generic rule that sets per-repo categories:</p>
+<pre class="code literal-block">
+MATCH:
+ any
+ACTION:
+ # set category
+ # CRAN->CRAN, CRAN-Archive->CRAN, BIOC-2.10/experimental->BIOC, ...
+ #
+ rename category s=^(?P<repo>[^-/]+)([-/].*)?$=sci-\g<repo>=
+END;
+</pre>
<p>The following example prefixes all <em>yaml</em> packages with <em>Rpkg_</em>:</p>
<pre class="code literal-block">
MATCH:
ebuild_name ,= yaml
ACTION:
+ set destfile Rpkg_{package_filename}
+END;
+
+# alternatively:
+MATCH:
+ ebuild_name ,= yaml
+ACTION:
rename destfile s/^/Rpkg_/
END;
</pre>
-<p>Moving such packages to a "R-package" sub directory would be possible, too:</p>
+<p>Moving such packages to a "R-packages" sub directory would be possible, too:</p>
<pre class="code literal-block">
MATCH:
name ,= yaml
ACTION:
- rename_destfile s=^=R-package/=
+ set_destfile R-packages/{package_filename}
+END;
+
+# alternatively:
+MATCH:
+ name ,= yaml
+ACTION:
+ rename_destfile s=^=R-packages/=
END;
</pre>
<div class="hint">
<p class="first admonition-title">Hint</p>
-<p class="last"><tt class="docutils literal">roverlay <span class="pre">[--nosync]</span> <span class="pre">[--dump-file</span> <file>] apply_rules</tt> can be used to
+<p class="last"><tt class="docutils literal">roverlay <span class="pre">[--no-sync]</span> <span class="pre">[--dump-file</span> <file>] apply_rules</tt> can be used to
test rules. It applies the rules to all packages without running overlay
creation. Furthermore, <tt class="docutils literal">roverlay <span class="pre">--ppr</span></tt> parses the package rules,
prints them and exits afterwards.</p>
@@ -4706,7 +4780,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-08-09.
+Generated on: 2013-08-19.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-08-23 13:52 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-08-23 13:52 UTC (permalink / raw
To: gentoo-commits
commit: af005edcf6bd6aeeeda7138be6a4b956f4a761a2
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Aug 23 13:33:02 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Aug 23 13:33:02 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=af005edc
doc/html, package rules: 'add' action
---
doc/html/usage.html | 72 ++++++++++++++++++++++++++++++++++-------------------
1 file changed, 47 insertions(+), 25 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 82d3f0e..dfa9c70 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -2151,10 +2151,10 @@ control <em>where</em>) and the number of values they accept:</p>
<table border="1" class="docutils">
<caption>action keywords</caption>
<colgroup>
-<col width="23%" />
-<col width="25%" />
+<col width="22%" />
+<col width="26%" />
<col width="18%" />
-<col width="34%" />
+<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">action keyword</th>
@@ -2193,9 +2193,9 @@ whenever this action
is applied</td>
</tr>
<tr><td>set</td>
-<td rowspan="2">package
-metadata,
-overlay creaton</td>
+<td rowspan="6">package metadata,
+overlay creation,
+ebuild creation</td>
<td>2</td>
<td rowspan="2">set package
information</td>
@@ -2204,9 +2204,6 @@ information</td>
<td>1</td>
</tr>
<tr><td>rename</td>
-<td rowspan="2">package
-metadata,
-overlay creation</td>
<td>2</td>
<td rowspan="2">modify package
information with
@@ -2217,51 +2214,76 @@ statements</td>
<tr><td>rename_<key></td>
<td>1</td>
</tr>
+<tr><td>add</td>
+<td>2</td>
+<td rowspan="2">similar to <em>set</em>, but
+can be applied
+multiple times without
+overwriting existing
+information</td>
+</tr>
+<tr><td>add_<key></td>
+<td>1</td>
+</tr>
<tr><td>null</td>
<td rowspan="2"><em>n/a</em></td>
<td rowspan="2">none</td>
<td rowspan="2">does nothing
(can be used for
-readability)</td>
+improving readability)</td>
</tr>
<tr><td>pass</td>
</tr>
</tbody>
</table>
-<p>The two-arg form of the set/rename keywords expect a <key> as first and
+<p>The two-arg form of the set/rename/add keywords expect a <key> as first and
a value / sed expression as second arg. The one-arg form expects the latter
-one only. The "/" delimitier in the sed expression can be any character.</p>
+one only. keys are case-insensitive. The "/" delimitier in the sed expression
+can be any other character.</p>
<p>The following <em>info keys</em> can be set and/or modified:</p>
<table border="1" class="docutils">
-<caption>info keys for set/rename</caption>
+<caption>info keys for set/rename/add</caption>
<colgroup>
-<col width="19%" />
-<col width="29%" />
-<col width="51%" />
+<col width="18%" />
+<col width="33%" />
+<col width="49%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">info key</th>
-<th class="head">supports set/rename</th>
+<th class="head">supports set/rename/add</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>name</td>
-<td>yes / yes</td>
+<td>yes / yes / no</td>
<td>rename the ebuild</td>
</tr>
<tr><td>category</td>
-<td>yes / yes
-(<em>repo_name</em>)</td>
+<td>yes / yes (<em>repo name</em>)
+/ no</td>
<td>set or rename (based on the
repository's name) the package's
category</td>
</tr>
<tr><td>destfile</td>
-<td>yes / yes</td>
+<td>yes / yes / no</td>
<td>rename ebuild destfile by using the
'->' operator in <tt class="docutils literal">${SRC_URI}</tt></td>
</tr>
+<tr><td>DEPEND</td>
+<td rowspan="3">no / no / <strong>yes</strong></td>
+<td rowspan="3"><p class="first">add additional dependencies to
+<em>DEPEND/RDEPEND/RSUGGESTS</em></p>
+<p class="last">The value has to be a string
+accepted by the package manager,
+e.g. a <em>DEPEND Atom</em>.</p>
+</td>
+</tr>
+<tr><td>RDEPEND</td>
+</tr>
+<tr><td>RSUGGESTS</td>
+</tr>
</tbody>
</table>
<p>The <em>set</em> action also supports variable substitution by means of python
@@ -2313,9 +2335,9 @@ followed by <tt class="docutils literal">roverlay create</tt>.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
-<p class="last">Applying the same (non-incremental) ebuild variable, set or rename action
-more than once is possible, but only the last one will have an effect
-on ebuild creation.</p>
+<p class="last">Applying the same ebuild variable, set or rename action more than once
+is possible, but only the last one will have an effect on ebuild creation.
+add actions are cumulative by definition.</p>
</div>
<div class="section" id="extended-action-block-syntax">
<h4><a class="toc-backref" href="#contents">8.1.2.1 Extended Action Block Syntax</a></h4>
@@ -4781,7 +4803,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-08-20.
+Generated on: 2013-08-23.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-08-27 15:39 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-08-27 15:39 UTC (permalink / raw
To: gentoo-commits
commit: 3ce975f9963111ad440c7e626552ed4de496e302
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Aug 27 15:34:03 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Aug 27 15:34:03 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=3ce975f9
doc/html: #! ERROR, deptype logging
---
doc/html/usage.html | 15 +++++++++++----
1 file changed, 11 insertions(+), 4 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index dfa9c70..153084d 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -1706,7 +1706,7 @@ is ignored.</p>
simple rule.</p>
</dd>
<dt>Keywords</dt>
-<dd><p class="first">There are two keywords that control how a rule file is read.</p>
+<dd><p class="first">There are three keywords that control how a rule file is read.</p>
<p>The important one is the <em>#deptype <dependency type></em> directive that
defines that all rules until the next <em>deptype</em> directory or end of file,
whatever comes first, will only match <em>dependency strings</em>
@@ -1725,7 +1725,9 @@ Specifying <em>selfdep</em> alone does not resolve anything.</p>
<p class="first admonition-title">Hint</p>
<p class="last">Check the <em>dependency type</em> if a newly added rule has no effect.</p>
</div>
-<p class="last">The other keyword is <em>#! NOPARSE</em> which stops parsing of a rule file.</p>
+<p class="last">The other keywords are <em>#! NOPARSE</em>, which stops parsing of a rule file
+(ignore remaining file content), and <em>#! ERROR</em>, which raises a python
+exception (program exits).</p>
</dd>
<dt>Dependencies</dt>
<dd><p class="first">are strings that are recognized by portage as <strong>Dynamic DEPENDs</strong>
@@ -3543,7 +3545,12 @@ results.</p>
<dl class="docutils" id="log-file-unresolvable">
<dt>LOG_FILE_UNRESOLVABLE</dt>
<dd><p class="first">A file where all unresolved dependency strings will be written into
-on <em>roverlay</em> exit. Primarily useful for creating new rules.</p>
+on <em>roverlay</em> exit. Primarily useful for creating new rules.
+The file's format is <tt class="docutils literal"><dependency type mask in hex>, <dependency string></tt>,
+where the <em>dependency type mask</em> is usually
+<tt class="docutils literal">0x7</tt> (mandatory system dependency),
+<tt class="docutils literal">0x8</tt> (optional R package dependency)
+or <tt class="docutils literal">0xb</tt> (mandatory R package dependency).</p>
<p class="last">Defaults to <not set>, which disables this feature.</p>
</dd>
</dl>
@@ -4803,7 +4810,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-08-23.
+Generated on: 2013-08-27.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-09-03 14:32 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-09-03 14:32 UTC (permalink / raw
To: gentoo-commits
commit: 714332a03d9ee88c8d050c8490df6e8360750c5c
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Sep 3 14:30:53 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Sep 3 14:30:53 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=714332a0
update doc/html
---
doc/html/usage.html | 9 ++++++---
1 file changed, 6 insertions(+), 3 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index dd321ea..a37ecc9 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -4733,8 +4733,11 @@ These are called <strong>Dynamic Rule Pools</strong> and use runtime data like &
R packages" to create rules.</p>
<p id="dynamic-selfdep-rule-pool"><em>roverlay</em> uses one dynamic rule pool, the <strong>Dynamic Selfdep Rule Pool</strong>.
This pool contains <em>selfdep</em> rules for all known R packages and is able
-to resolve R package dependencies.
-By convention, it will never resolve any system dependencies.</p>
+to resolve R package dependencies. Moreover, it knows to which repository
+a rule belongs, and tries to satisfy dependencies on a package within its
+own repository first, before trying the other repositories in the order as
+they appear in the repo config file(s).</p>
+<p>By convention, this rule pool never resolves any system dependencies.</p>
</div>
<div class="section" id="dependency-resolver-modules">
<h3><a class="toc-backref" href="#contents">14.6.5 Dependency Resolver Modules</a></h3>
@@ -4817,7 +4820,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-08-29.
+Generated on: 2013-09-03.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-09-23 12:34 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-09-23 12:34 UTC (permalink / raw
To: gentoo-commits
commit: a6e226a730fd6605ecd3e0a0a3d56709ceeb9949
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Mon Sep 23 12:34:33 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Mon Sep 23 12:34:33 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=a6e226a7
doc/html/usage.rst: roverlay-setup[-interactive]
---
doc/html/usage.html | 278 ++++++++++++++++++++++++++++++++--------------------
1 file changed, 169 insertions(+), 109 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 754daff..54ddc38 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -339,139 +339,141 @@ ul.auto-toc {
</li>
<li><a class="reference internal" href="#running-roverlay" id="id12">3 Running Roverlay</a><ul class="auto-toc">
<li><a class="reference internal" href="#required-configuration-steps" id="id13">3.1 Required configuration steps</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id14">3.1.1 Extended Configuration / Where to go from here?</a></li>
+<li><a class="reference internal" href="#automated-configuration-and-setup" id="id14">3.1.1 Automated configuration and setup</a></li>
+<li><a class="reference internal" href="#manual-configuration" id="id15">3.1.2 Manual configuration</a></li>
+<li><a class="reference internal" href="#extended-configuration-where-to-go-from-here" id="id16">3.1.3 Extended Configuration / Where to go from here?</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#running-it" id="id15">3.2 Running it</a></li>
-<li><a class="reference internal" href="#providing-a-package-mirror" id="id16">3.3 Providing a package mirror</a></li>
-<li><a class="reference internal" href="#roverlay-helpers" id="id17">3.4 roverlay helpers</a></li>
+<li><a class="reference internal" href="#running-it" id="id17">3.2 Running it</a></li>
+<li><a class="reference internal" href="#providing-a-package-mirror" id="id18">3.3 Providing a package mirror</a></li>
+<li><a class="reference internal" href="#roverlay-helpers" id="id19">3.4 roverlay helpers</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#basic-implementation-overview" id="id18">4 Basic Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#how-roverlay-works" id="id19">4.1 How <em>roverlay</em> works</a></li>
-<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id20">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#expected-ebuild-result" id="id21">4.2.1 Expected Ebuild Result</a></li>
-<li><a class="reference internal" href="#expected-metadata-xml-result" id="id22">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
+<li><a class="reference internal" href="#basic-implementation-overview" id="id20">4 Basic Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#how-roverlay-works" id="id21">4.1 How <em>roverlay</em> works</a></li>
+<li><a class="reference internal" href="#expected-overlay-result-structure-of-the-generated-overlay" id="id22">4.2 Expected Overlay Result / Structure of the generated overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#expected-ebuild-result" id="id23">4.2.1 Expected Ebuild Result</a></li>
+<li><a class="reference internal" href="#expected-metadata-xml-result" id="id24">4.2.2 Expected <em>metadata.xml</em> Result</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#repositories-getting-packages" id="id23">5 Repositories / Getting Packages</a><ul class="auto-toc">
-<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id24">5.1 A word about repo config files</a></li>
-<li><a class="reference internal" href="#rsync-repos" id="id25">5.2 Rsync repos</a></li>
-<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id26">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="id27">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="id28">5.5 Using local directories</a></li>
-<li><a class="reference internal" href="#distmap" id="id29">5.6 Distmap</a></li>
+<li><a class="reference internal" href="#repositories-getting-packages" id="id25">5 Repositories / Getting Packages</a><ul class="auto-toc">
+<li><a class="reference internal" href="#a-word-about-repo-config-files" id="id26">5.1 A word about repo config files</a></li>
+<li><a class="reference internal" href="#rsync-repos" id="id27">5.2 Rsync repos</a></li>
+<li><a class="reference internal" href="#getting-packages-from-a-repository-that-supports-http-only" id="id28">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="id29">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="id30">5.5 Using local directories</a></li>
+<li><a class="reference internal" href="#distmap" id="id31">5.6 Distmap</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#additions-directory" id="id30">6 Additions Directory</a><ul class="auto-toc">
-<li><a class="reference internal" href="#patching-ebuilds" id="id31">6.1 Patching ebuilds</a></li>
-<li><a class="reference internal" href="#importing-ebuilds" id="id32">6.2 Importing ebuilds</a></li>
+<li><a class="reference internal" href="#additions-directory" id="id32">6 Additions Directory</a><ul class="auto-toc">
+<li><a class="reference internal" href="#patching-ebuilds" id="id33">6.1 Patching ebuilds</a></li>
+<li><a class="reference internal" href="#importing-ebuilds" id="id34">6.2 Importing ebuilds</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-rules" id="id33">7 Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#simple-dependency-rules" id="id34">7.1 Simple Dependency Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#rule-variants" id="id35">7.1.1 Rule Variants</a></li>
-<li><a class="reference internal" href="#rule-types" id="id36">7.1.2 Rule types</a></li>
-<li><a class="reference internal" href="#rule-file-examples" id="id37">7.1.3 Rule File Examples</a></li>
-<li><a class="reference internal" href="#rule-file-syntax" id="id38">7.1.4 Rule File Syntax</a></li>
+<li><a class="reference internal" href="#dependency-rules" id="id35">7 Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#simple-dependency-rules" id="id36">7.1 Simple Dependency Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#rule-variants" id="id37">7.1.1 Rule Variants</a></li>
+<li><a class="reference internal" href="#rule-types" id="id38">7.1.2 Rule types</a></li>
+<li><a class="reference internal" href="#rule-file-examples" id="id39">7.1.3 Rule File Examples</a></li>
+<li><a class="reference internal" href="#rule-file-syntax" id="id40">7.1.4 Rule File Syntax</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#package-rules" id="id39">8 Package Rules</a><ul class="auto-toc">
-<li><a class="reference internal" href="#package-rule-file-syntax" id="id40">8.1 Package Rule File Syntax</a><ul class="auto-toc">
-<li><a class="reference internal" href="#match-blocks" id="id41">8.1.1 Match Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-match-block-syntax" id="id42">8.1.1.1 Extended Match Block Syntax</a></li>
+<li><a class="reference internal" href="#package-rules" id="id41">8 Package Rules</a><ul class="auto-toc">
+<li><a class="reference internal" href="#package-rule-file-syntax" id="id42">8.1 Package Rule File Syntax</a><ul class="auto-toc">
+<li><a class="reference internal" href="#match-blocks" id="id43">8.1.1 Match Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-match-block-syntax" id="id44">8.1.1.1 Extended Match Block Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#action-blocks" id="id43">8.1.2 Action Blocks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#extended-action-block-syntax" id="id44">8.1.2.1 Extended Action Block Syntax</a></li>
+<li><a class="reference internal" href="#action-blocks" id="id45">8.1.2 Action Blocks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#extended-action-block-syntax" id="id46">8.1.2.1 Extended Action Block Syntax</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#package-rule-examples" id="id45">8.1.3 Package Rule Examples</a></li>
+<li><a class="reference internal" href="#package-rule-examples" id="id47">8.1.3 Package Rule Examples</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#event-hooks" id="id46">9 Event Hooks</a><ul class="auto-toc">
-<li><a class="reference internal" href="#default-event-script" id="id47">9.1 Default event script</a><ul class="auto-toc">
-<li><a class="reference internal" href="#activating-a-hook-script" id="id48">9.1.1 Activating a hook script</a></li>
-<li><a class="reference internal" href="#adding-a-new-hook-script" id="id49">9.1.2 Adding a new hook script</a></li>
+<li><a class="reference internal" href="#event-hooks" id="id48">9 Event Hooks</a><ul class="auto-toc">
+<li><a class="reference internal" href="#default-event-script" id="id49">9.1 Default event script</a><ul class="auto-toc">
+<li><a class="reference internal" href="#activating-a-hook-script" id="id50">9.1.1 Activating a hook script</a></li>
+<li><a class="reference internal" href="#adding-a-new-hook-script" id="id51">9.1.2 Adding a new hook script</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#event-policy" id="id50">9.2 Event Policy</a></li>
-<li><a class="reference internal" href="#hook-environment" id="id51">9.3 Hook Environment</a></li>
-<li><a class="reference internal" href="#adding-a-function-file" id="id52">9.4 Adding a function file</a></li>
-<li><a class="reference internal" href="#hook-event-table" id="id53">9.5 Hook event table</a></li>
-<li><a class="reference internal" href="#adding-a-hook-event" id="id54">9.6 Adding a hook event</a></li>
+<li><a class="reference internal" href="#event-policy" id="id52">9.2 Event Policy</a></li>
+<li><a class="reference internal" href="#hook-environment" id="id53">9.3 Hook Environment</a></li>
+<li><a class="reference internal" href="#adding-a-function-file" id="id54">9.4 Adding a function file</a></li>
+<li><a class="reference internal" href="#hook-event-table" id="id55">9.5 Hook event table</a></li>
+<li><a class="reference internal" href="#adding-a-hook-event" id="id56">9.6 Adding a hook event</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#configuration-reference" id="id55">10 Configuration Reference</a><ul class="auto-toc">
-<li><a class="reference internal" href="#misc-options" id="id56">10.1 misc options</a></li>
-<li><a class="reference internal" href="#overlay-options" id="id57">10.2 overlay options</a></li>
-<li><a class="reference internal" href="#other-config-files" id="id58">10.3 other config files</a></li>
-<li><a class="reference internal" href="#shell-environment-hooks" id="id59">10.4 shell environment / hooks</a></li>
-<li><a class="reference internal" href="#logging" id="id60">10.5 logging</a><ul class="auto-toc">
-<li><a class="reference internal" href="#console-logging" id="id61">10.5.1 console logging</a></li>
-<li><a class="reference internal" href="#file-logging" id="id62">10.5.2 file logging</a></li>
+<li><a class="reference internal" href="#configuration-reference" id="id57">10 Configuration Reference</a><ul class="auto-toc">
+<li><a class="reference internal" href="#misc-options" id="id58">10.1 misc options</a></li>
+<li><a class="reference internal" href="#overlay-options" id="id59">10.2 overlay options</a></li>
+<li><a class="reference internal" href="#other-config-files" id="id60">10.3 other config files</a></li>
+<li><a class="reference internal" href="#shell-environment-hooks" id="id61">10.4 shell environment / hooks</a></li>
+<li><a class="reference internal" href="#logging" id="id62">10.5 logging</a><ul class="auto-toc">
+<li><a class="reference internal" href="#console-logging" id="id63">10.5.1 console logging</a></li>
+<li><a class="reference internal" href="#file-logging" id="id64">10.5.2 file logging</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#license-map-options" id="id63">10.6 license map options</a></li>
-<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id64">10.7 options for debugging, manual dependency rule creation and testing</a></li>
+<li><a class="reference internal" href="#license-map-options" id="id65">10.6 license map options</a></li>
+<li><a class="reference internal" href="#options-for-debugging-manual-dependency-rule-creation-and-testing" id="id66">10.7 options for debugging, manual dependency rule creation and testing</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#id3" id="id65">11 Other config files</a><ul class="auto-toc">
-<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id66">11.1 USE_EXPAND flag rename file</a></li>
-<li><a class="reference internal" href="#license-map-file" id="id67">11.2 License Map File</a></li>
-<li><a class="reference internal" href="#field-definition-config" id="id68">11.3 Field Definition Config</a><ul class="auto-toc">
-<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id69">11.3.1 Example: The default field definition file</a></li>
+<li><a class="reference internal" href="#id3" id="id67">11 Other config files</a><ul class="auto-toc">
+<li><a class="reference internal" href="#use-expand-flag-rename-file" id="id68">11.1 USE_EXPAND flag rename file</a></li>
+<li><a class="reference internal" href="#license-map-file" id="id69">11.2 License Map File</a></li>
+<li><a class="reference internal" href="#field-definition-config" id="id70">11.3 Field Definition Config</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id71">11.3.1 Example: The default field definition file</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#id5" id="id70">12 Roverlay Console</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-resolution-console" id="id71">12.1 Dependency Resolution Console</a></li>
+<li><a class="reference internal" href="#id5" id="id72">12 Roverlay Console</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-resolution-console" id="id73">12.1 Dependency Resolution Console</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#roverlay-interface" id="id72">13 Roverlay Interface</a><ul class="auto-toc">
-<li><a class="reference internal" href="#depres-interface" id="id73">13.1 DepRes Interface</a></li>
-<li><a class="reference internal" href="#remote-interface" id="id74">13.2 Remote Interface</a></li>
+<li><a class="reference internal" href="#roverlay-interface" id="id74">13 Roverlay Interface</a><ul class="auto-toc">
+<li><a class="reference internal" href="#depres-interface" id="id75">13.1 DepRes Interface</a></li>
+<li><a class="reference internal" href="#remote-interface" id="id76">13.2 Remote Interface</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#implementation-overview" id="id75">14 Implementation Overview</a><ul class="auto-toc">
-<li><a class="reference internal" href="#packageinfo" id="id76">14.1 PackageInfo</a></li>
-<li><a class="reference internal" href="#repository-management" id="id77">14.2 Repository Management</a><ul class="auto-toc">
-<li><a class="reference internal" href="#repository" id="id78">14.2.1 Repository</a><ul class="auto-toc">
-<li><a class="reference internal" href="#adding-new-repository-types" id="id79">14.2.1.1 Adding new repository types</a></li>
+<li><a class="reference internal" href="#implementation-overview" id="id77">14 Implementation Overview</a><ul class="auto-toc">
+<li><a class="reference internal" href="#packageinfo" id="id78">14.1 PackageInfo</a></li>
+<li><a class="reference internal" href="#repository-management" id="id79">14.2 Repository Management</a><ul class="auto-toc">
+<li><a class="reference internal" href="#repository" id="id80">14.2.1 Repository</a><ul class="auto-toc">
+<li><a class="reference internal" href="#adding-new-repository-types" id="id81">14.2.1.1 Adding new repository types</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay" id="id80">14.3 Overlay</a><ul class="auto-toc">
-<li><a class="reference internal" href="#metadata-creation" id="id81">14.3.1 Metadata Creation</a></li>
-<li><a class="reference internal" href="#manifest-creation" id="id82">14.3.2 Manifest Creation</a></li>
+<li><a class="reference internal" href="#overlay" id="id82">14.3 Overlay</a><ul class="auto-toc">
+<li><a class="reference internal" href="#metadata-creation" id="id83">14.3.1 Metadata Creation</a></li>
+<li><a class="reference internal" href="#manifest-creation" id="id84">14.3.2 Manifest Creation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#ebuild-creation" id="id83">14.4 Ebuild Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#ebuild-variables" id="id84">14.4.1 Ebuild Variables</a></li>
+<li><a class="reference internal" href="#ebuild-creation" id="id85">14.4 Ebuild Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#ebuild-variables" id="id86">14.4.1 Ebuild Variables</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#overlay-creation" id="id85">14.5 Overlay Creation</a><ul class="auto-toc">
-<li><a class="reference internal" href="#selfdep-validation" id="id86">14.5.1 Selfdep Validation</a></li>
+<li><a class="reference internal" href="#overlay-creation" id="id87">14.5 Overlay Creation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#selfdep-validation" id="id88">14.5.1 Selfdep Validation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-resolution" id="id87">14.6 Dependency Resolution</a><ul class="auto-toc">
-<li><a class="reference internal" href="#dependency-types" id="id88">14.6.1 Dependency types</a><ul class="auto-toc">
-<li><a class="reference internal" href="#description-file-dependency-fields" id="id89">14.6.1.1 DESCRIPTION file dependency fields</a></li>
+<li><a class="reference internal" href="#dependency-resolution" id="id89">14.6 Dependency Resolution</a><ul class="auto-toc">
+<li><a class="reference internal" href="#dependency-types" id="id90">14.6.1 Dependency types</a><ul class="auto-toc">
+<li><a class="reference internal" href="#description-file-dependency-fields" id="id91">14.6.1.1 DESCRIPTION file dependency fields</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dependency-environments" id="id90">14.6.2 Dependency Environments</a></li>
-<li><a class="reference internal" href="#ebuildjob-channel" id="id91">14.6.3 EbuildJob Channel</a></li>
-<li><a class="reference internal" href="#dependency-rule-pools" id="id92">14.6.4 Dependency Rule Pools</a></li>
-<li><a class="reference internal" href="#dependency-resolver-modules" id="id93">14.6.5 Dependency Resolver Modules</a></li>
-<li><a class="reference internal" href="#dependency-resolver" id="id94">14.6.6 Dependency Resolver</a></li>
+<li><a class="reference internal" href="#dependency-environments" id="id92">14.6.2 Dependency Environments</a></li>
+<li><a class="reference internal" href="#ebuildjob-channel" id="id93">14.6.3 EbuildJob Channel</a></li>
+<li><a class="reference internal" href="#dependency-rule-pools" id="id94">14.6.4 Dependency Rule Pools</a></li>
+<li><a class="reference internal" href="#dependency-resolver-modules" id="id95">14.6.5 Dependency Resolver Modules</a></li>
+<li><a class="reference internal" href="#dependency-resolver" id="id96">14.6.6 Dependency Resolver</a></li>
</ul>
</li>
</ul>
@@ -629,18 +631,9 @@ installed!</p>
Make sure to meet the dependencies as listed in <a class="reference internal" href="#prerequisites">Prerequisites</a>.
Then, simply clone the git repository to a local directory that is referenced
as the <em>R Overlay src directory</em> from now on.</p>
-<div class="note">
-<p class="first admonition-title">Note</p>
-<p>You have to <em>cd</em> into the <em>R Overlay src directory</em> before running
-<em>roverlay</em> to ensure that the python modules can be imported correctly.</p>
-<p>You can work around this by setting up a wrapper script:</p>
-<pre class="code sh last literal-block">
-<span class="comment">#!/bin/sh
-# /usr/local/bin/roverlay.sh
-# example wrapper script for roverlay
-</span><span class="name builtin">cd</span> <span class="keyword">${</span><span class="name variable">ROVERLAY_SRC</span><span class="keyword">:-</span><span class="punctuation">~/roverlay/src</span><span class="keyword">}</span> <span class="operator">&&</span> ./roverlay.py <span class="literal string double">"$@"</span>
-</pre>
-</div>
+<p>The <em>R Overlay src directory</em> provides a wrapper script (<tt class="docutils literal">roverlay.py</tt> or
+<tt class="docutils literal">bin/roverlay</tt>) which changes the working directory and adjusts the
+<tt class="docutils literal">PYTHONPATH</tt> variable so that <em>roverlay</em> can be run from anywhere.</p>
</div>
</div>
<div class="section" id="running-roverlay">
@@ -655,20 +648,74 @@ it will look for the config file in that order:</p>
<li><em>/etc/roverlay/R-overlay.conf</em>,
which is part of the installation but has to be modified.</li>
</ol>
-<p>Otherwise, <em>roverlay</em> uses <em>R-overlay.conf</em> in the current directory.
+<p>Otherwise, <em>roverlay</em> uses <em>R-overlay.conf.local</em> or <em>R-overlay.conf</em>
+in the current directory.
An example config file is available in the <em>R Overlay src directory</em>.</p>
-<p>The config file is a text file with '<option> = <value>' syntax. Some options
-accept multiple values (e.g. <option> = file1, file2), in which case the
-values have to be enclosed with quotes (-> <tt class="docutils literal"><option> = "file1 file2"</tt>).</p>
-<p>If roverlay has been installed, then <tt class="docutils literal">emerge <span class="pre">--config</span> roverlay</tt> can be
-used to set up the config file as well as to create essential directories.
-It can be run multiple times in order to configure roverlay for more than
-one user.</p>
+<p>Overall, the following steps have to be taken before running <em>roverlay</em>:</p>
+<ul class="simple">
+<li>create/adjust the main config file</li>
+<li>provide additional files (dependency rule files, hook event script etc.)
+at the locations pointed out in the main config file</li>
+<li>optional: create directories in advance with proper permissions, e.g.
+a shared package files directory</li>
+</ul>
+<p>These steps can be automated by using <em>roverlay-setup</em>.
+See <cite>Automated configuration and setup</cite> for details.
+<cite>Manual configuration</cite> covers how to configure <em>roverlay</em> by hand.</p>
+<div class="section" id="automated-configuration-and-setup">
+<h3><a class="toc-backref" href="#contents">3.1.1 Automated configuration and setup</a></h3>
+<p><tt class="docutils literal"><span class="pre">roverlay-setup</span></tt> (<tt class="docutils literal"><span class="pre">bin/roverlay-setup</span></tt> in the <em>R overlay src directory</em>)
+is a script that is able to generate <em>roverlay's</em> main config file, import
+other config files, create essential directories and activate/manage
+<em>event hooks</em>.</p>
+<p>It accepts a number of options, in particular:</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">--pretend</span>, <span class="option">-p</span></kbd></td>
+<td>Show what would be done. <strong>Recommended</strong> (prior to running the command
+without --pretend).</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">--ask</span>, <span class="option">-a</span></kbd></td>
+<td>Ask for confirmation before each action. This allows to skip certain
+actions by answering with <em>n</em>, <em>no</em> or <em>skip</em>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--work-root <var><dir></var></span>, <span class="option">-W <var><dir></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>The user's root directory for work data (distfiles, overlay, ...).
+Defaults to <tt class="docutils literal"><span class="pre">${HOME}/roverlay</span></tt>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--conf-dir <var><dir></var></span>, <span class="option">--my-conf-root <var><dir></var></span>, <span class="option">-C <var><dir></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Directory for the user's private config.
+Defaults to <tt class="docutils literal"><span class="pre">${HOME}/roverlay/config</span></tt>.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--variable <var><name=value></var></span>, <span class="option">-v <var><name=value></var></span></kbd></td>
+</tr>
+<tr><td> </td><td><p class="first">This can be used to set config options.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">--variable</span> <span class="pre">DISTFILES=/nfs/roverlay/distfiles</span></tt> for setting
+up a shared package files directory.</p>
+</td></tr>
+</tbody>
+</table>
+<p>See <tt class="docutils literal"><span class="pre">roverlay-setup</span> <span class="pre">--help</span></tt> for a full listing.</p>
+<p><tt class="docutils literal"><span class="pre">roverlay-setup-interactive</span></tt> (<tt class="docutils literal"><span class="pre">bin/roverlay-setup-interactive</span></tt>) is a
+script that asks a few questions and then calls <tt class="docutils literal"><span class="pre">roverlay-setup</span></tt> based on
+the answers.
+It's also accessible via <tt class="docutils literal">emerge <span class="pre">--config</span> roverlay</tt> if roverlay
+has been installed.</p>
<div class="important">
<p class="first admonition-title">Important</p>
-<p class="last"><tt class="docutils literal">emerge <span class="pre">--config</span> roverlay</tt> will overwrite the user's config file (or
-/etc/roverlay/R-overlay.conf when configuring for root).</p>
+<p class="last"><tt class="docutils literal"><span class="pre">roverlay-setup[-interactive]</span></tt> overwrites the user's config.</p>
+</div>
</div>
+<div class="section" id="manual-configuration">
+<h3><a class="toc-backref" href="#contents">3.1.2 Manual configuration</a></h3>
+<p>The config file is a text file with '<option> = <value>' syntax. Some options
+accept multiple values (e.g. <option> = file1, file2), in which case the
+values have to be enclosed with quotes (-> <tt class="docutils literal"><option> = "file1 file2"</tt>).</p>
<p>The following options should be set before running <em>roverlay</em>:</p>
<blockquote>
<dl class="docutils">
@@ -802,8 +849,9 @@ DISTDIR as package mirror.</p>
<p>There is another option that is useful for creating new dependency rules,
<a class="reference internal" href="#log-file-unresolvable">LOG_FILE_UNRESOLVABLE</a>, which will write all unresolvable dependencies
to the specified file (one dependency string per line).</p>
+</div>
<div class="section" id="extended-configuration-where-to-go-from-here">
-<h3><a class="toc-backref" href="#contents">3.1.1 Extended Configuration / Where to go from here?</a></h3>
+<h3><a class="toc-backref" href="#contents">3.1.3 Extended Configuration / Where to go from here?</a></h3>
<p>Proceed with <a class="reference internal" href="#running-it">Running it</a> if the default configuration and the changes already
made are fine, otherwise the following chapters are relevant and should
provide you with the knowledge to determine the ideal configuration.</p>
@@ -971,8 +1019,6 @@ been done, either to stdout or to <tt class="docutils literal"><span class="pre"
<p class="last">This command implies the <strong>sync</strong> command unless the <em>--no-sync</em> option
is specified.</p>
</dd>
-<dt>setupdirs</dt>
-<dd>Creates all configured directories with proper permissions.</dd>
</dl>
</div>
<div class="section" id="providing-a-package-mirror">
@@ -1010,8 +1056,22 @@ config and get access to its <tt class="docutils literal">$FUNCTIONS</tt> file:<
<p class="last"><em>roverlay-sh</em> requires a valid config file.</p>
</div>
</dd>
-<dt><em>roverlay-mkconfig</em></dt>
-<dd>a script that creates a config file for roverlay</dd>
+<dt><em>roverlay-setup</em></dt>
+<dd><p class="first">A script with various subcommands for setting up roverlay:</p>
+<ul class="last simple">
+<li><tt class="docutils literal">init</tt> for initial setup as described in
+<a class="reference internal" href="#automated-configuration-and-setup">Automated Configuration and Setup</a></li>
+<li><tt class="docutils literal">mkconfig</tt> for generating the main config file</li>
+<li><tt class="docutils literal">hooks</tt> for managings hooks<ul>
+<li><tt class="docutils literal"><span class="pre">roverlay-setup</span> hooks [show]</tt> prints information</li>
+<li><tt class="docutils literal"><span class="pre">roverlay-setup</span> hooks add <hook> <event> <span class="pre">[<event>...]</span></tt> adds a hook
+(referenced by name) to one or more <em>events</em></li>
+<li><tt class="docutils literal"><span class="pre">roverlay-setup</span> hooks del <hook> <span class="pre"><event|"all"></span> <span class="pre">[<event|"all">...]</span></tt>
+removes a hook (referenced by name) from one or more (or all) <em>events</em></li>
+</ul>
+</li>
+</ul>
+</dd>
<dt><em>run-roverlay.sh</em></dt>
<dd><p class="first">A script that safely runs overlay creation and repoman afterwards.
Uses filesystem locks to ensure that it is run at most once at a time.
@@ -4841,7 +4901,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-09-06.
+Generated on: 2013-09-23.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-09-23 15:30 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-09-23 15:30 UTC (permalink / raw
To: gentoo-commits
commit: 0704a4435a207c4059699565cfda3a4ea5136455
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Mon Sep 23 13:27:01 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Mon Sep 23 13:27:01 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=0704a443
doc/html: roverlay-status script
---
doc/html/usage.html | 59 +++++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 50 insertions(+), 9 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 54ddc38..c00960a 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -1035,7 +1035,8 @@ most cases, but fine-tuning can be done via <a class="reference internal" href="
</div>
<div class="section" id="roverlay-helpers">
<h2><a class="toc-backref" href="#contents">3.4 roverlay helpers</a></h2>
-<p>An installation of roverlay includes some helper programs:</p>
+<p>An installation of roverlay includes some helper programs, most of them
+can also be found in <tt class="docutils literal"><R overlay src <span class="pre">directory>/bin/</span></tt>:</p>
<dl class="docutils">
<dt><em>roverlay-sh</em></dt>
<dd><p class="first">a wrapper around /bin/sh that runs a shell or shell script in roverlay's
@@ -1072,6 +1073,37 @@ removes a hook (referenced by name) from one or more (or all) <em>events</em></l
</li>
</ul>
</dd>
+<dt><em>roverlay-status</em></dt>
+<dd><p class="first">A script that generates status reports based on <a class="reference external" href="http://www.makotemplates.org/">mako templates</a>
+and roverlay's stats (<a class="reference internal" href="#stats-db-file">STATS_DB_FILE</a>). Supported output formats include
+html, cgi (html with cgi header) and plain text.</p>
+<p>Notable options accepted by <em>roverlay-status</em>:</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--output <var><file|"-"></var></span>, <span class="option">-O <var><file|"-"></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>output file/stream, defaults to stdout ("-")</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--template <var><file|name></var></span>, <span class="option">-t <var><file|name></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>name of or path to the mako template file. A <tt class="docutils literal"><span class="pre">--mode</span></tt> specific
+file extension is automatically appended when searching for the template
+file.</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--mode <var><"cli"|"cgi"|"html"></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Sets the output format. Defaults to <em>cli</em> (plain text).</td></tr>
+<tr><td class="option-group" colspan="2">
+<kbd><span class="option">--config <var><file></var></span>, <span class="option">-c <var><file></var></span></kbd></td>
+</tr>
+<tr><td> </td><td>Path to roverlay's main config file.</td></tr>
+</tbody>
+</table>
+<p class="last">See <tt class="docutils literal"><span class="pre">roverlay-status</span> <span class="pre">--help</span></tt> for a full listing.</p>
+</dd>
<dt><em>run-roverlay.sh</em></dt>
<dd><p class="first">A script that safely runs overlay creation and repoman afterwards.
Uses filesystem locks to ensure that it is run at most once at a time.
@@ -3095,15 +3127,24 @@ the distmap file.</p>
</dl>
<dl class="docutils" id="stats-db-file">
<dt>STATS_DB</dt>
-<dd><p class="first">Path to the stats database file. This has to be a round-robin database
-file (rrdtool). <em>roverlay</em> creates it if necessary.</p>
-<p class="last">Defaults to <not set>, which disable database writing.</p>
+<dd><p class="first">Path to the stats database file. <em>roverlay</em> creates it if necessary.</p>
+<p class="last">Defaults to <not set>, which disables database writing.</p>
</dd>
-<dt>STATS_INTERVAL</dt>
-<dd><p class="first">Database update interval, which should be set to the expected timespan
-between running overlay creation, in seconds. Only meaningful when
-creating a new database file.</p>
-<p class="last">Defaults to 7200 (2 hours).</p>
+</dl>
+<dl class="docutils" id="template-root">
+<dt>TEMPLATE_ROOT</dt>
+<dd><p class="first">List of directories with templates for generating status reports.</p>
+<p><em>/usr/share/roverlay/mako_templates</em> is automatically added to this list
+if roverlay has been installed.</p>
+<p>This option is <strong>required</strong> for <em>roverlay-status</em>, but doesn't need to be
+set if roverlay has been installed.</p>
+<p class="last">Defaults to <not set>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="template-module-dir">
+<dt>TEMPLATE_MODULE_DIR</dt>
+<dd><p class="first">Directory for caching mako templates.</p>
+<p class="last">Defaults to <a class="reference internal" href="#cachedir">CACHEDIR</a>/mako_templates.</p>
</dd>
</dl>
<dl class="docutils" id="distfiles">
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2013-11-14 18:24 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2013-11-14 18:24 UTC (permalink / raw
To: gentoo-commits
commit: aebe54a4dca50a983494197727e2ec7b40217291
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Thu Nov 14 17:57:38 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Thu Nov 14 17:57:38 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=aebe54a4
doc/html: hook env, EVENT_HOOK_RC config entry
---
doc/html/usage.html | 26 +++++++++++++++++++++++++-
1 file changed, 25 insertions(+), 1 deletion(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 2ca9847..acffffd 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -2715,6 +2715,15 @@ the config file. An empty string sets the policy to <em>deny all</em>.</p>
<td>os.environ</td>
<td> </td>
</tr>
+<tr><td>LANG</td>
+<td>os.environ</td>
+<td> </td>
+</tr>
+<tr><td><em>LC_*</em></td>
+<td>os.environ</td>
+<td>all environment variables starting
+with LC_</td>
+</tr>
<tr><td>ROVERLAY_PHASE</td>
<td>event</td>
<td>event that caused the script to run</td>
@@ -2802,6 +2811,11 @@ created the hook environment
<td>guessed path to the roverlay "main"
executable (which creates the overlay)</td>
</tr>
+<tr><td>ROVERLAY_HOOKRC</td>
+<td>config</td>
+<td>hook config file (<a class="reference internal" href="#event-hook-rc">EVENT_HOOK_RC</a>,
+optional)</td>
+</tr>
<tr><td>STATS_DB</td>
<td>config</td>
<td>stats database file
@@ -3498,6 +3512,12 @@ much without dependency resolution.</p>
and <a class="reference internal" href="#additions-dir">ADDITIONS_DIR</a>/hooks/mux.sh otherwise.</p>
</dd>
</dl>
+<dl class="docutils" id="event-hook-rc">
+<dt>EVENT_HOOK_RC</dt>
+<dd><p class="first">Config file for hook scripts (in shell script syntax).</p>
+<p class="last">Defaults to <not set>.</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
@@ -3521,6 +3541,10 @@ or not.</p>
<dt>HOOK</dt>
<dd>Alias to <a class="reference internal" href="#event-hook">EVENT_HOOK</a>.</dd>
</dl>
+<dl class="docutils" id="hook-rc">
+<dt>HOOK_RC</dt>
+<dd>Alias to <a class="reference internal" href="#event-hook-rc">EVENT_HOOK_RC</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>
@@ -4945,7 +4969,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-09-26.
+Generated on: 2013-11-14.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/html/
@ 2014-04-01 16:38 André Erdmann
0 siblings, 0 replies; 27+ messages in thread
From: André Erdmann @ 2014-04-01 16:38 UTC (permalink / raw
To: gentoo-commits
commit: fac405678163d6b19db1c4a230724e663474f619
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Apr 1 16:35:12 2014 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Apr 1 16:36:37 2014 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=fac40567
doc/html: update
---
doc/html/usage.html | 16 ++++++++++++++--
1 file changed, 14 insertions(+), 2 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index ffc3d5f..2892bcb 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -2946,12 +2946,21 @@ when included in the hook script, most of the enviroment variables readonly.</p>
<tr><td>DEVNULL</td>
<td><em>/dev/null</em> target (could also be a file)</td>
</tr>
+<tr><td>EX_OK</td>
+<td><em>success</em> exit code</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>EX_CANNOT_RUN</td>
+<td><p class="first">default exit code when a hook cannot run,
+e.g. if an essential program is missing</p>
+<p class="last">Defaults to <tt class="docutils literal">$EX_OK</tt>.</p>
+</td>
+</tr>
<tr><td>EX_GIT_ERR
EX_GIT_ADD_ERR
EX_GIT_COMMIT_ERR
@@ -2999,6 +3008,9 @@ function files</td>
# @noreturn die ( [message], [exit_code] ), raises exit()
# Lets the script die with the given message/exit code.
#
+# @noreturn die_cannot_run ( [reason] ), raises die (**EX_CANNOT_RUN)
+# Lets the script die due to missing preconditions.
+#
# @noreturn OUT_OF_BOUNDS(), raises die()
# Lets the script die due to insufficient arg count.
#
@@ -3023,7 +3035,7 @@ function files</td>
# 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.
+# Returns 0 if all listed commands could be found, else 1.
#
# int sync_allowed ( action_name, [msg_nosync], [msg_sync] )
# Returns 0 if syncing for the given action is allowed, else 1.
@@ -5038,7 +5050,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2014-02-21.
+Generated on: 2014-04-01.
</div>
</body>
^ permalink raw reply related [flat|nested] 27+ messages in thread
end of thread, other threads:[~2014-04-01 16:39 UTC | newest]
Thread overview: 27+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-08-27 15:39 [gentoo-commits] proj/R_overlay:master commit in: doc/html/ André Erdmann
-- strict thread matches above, loose matches on Subject: below --
2014-04-01 16:38 André Erdmann
2013-11-14 18:24 André Erdmann
2013-09-23 15:30 André Erdmann
2013-09-23 12:34 André Erdmann
2013-09-03 14:32 André Erdmann
2013-08-23 13:52 André Erdmann
2013-08-19 15:42 André Erdmann
2013-08-09 15:28 André Erdmann
2013-08-07 16:10 André Erdmann
2013-08-06 16:02 André Erdmann
2013-08-02 14:30 André Erdmann
2013-07-23 14:57 André Erdmann
2013-07-16 16:35 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
2013-07-16 16:36 ` [gentoo-commits] proj/R_overlay:master " André Erdmann
2013-07-10 16:16 André Erdmann
2013-07-03 10:04 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
2013-07-03 10:05 ` [gentoo-commits] proj/R_overlay:master " André Erdmann
2013-06-26 17:29 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
2013-06-30 15:58 ` [gentoo-commits] proj/R_overlay:master " André Erdmann
2013-06-18 14:12 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
2013-06-18 14:12 ` [gentoo-commits] proj/R_overlay:master " André Erdmann
2013-06-12 21:10 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
2013-06-13 16:34 ` [gentoo-commits] proj/R_overlay:master " André Erdmann
2013-06-05 18:08 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
2013-06-13 16:34 ` [gentoo-commits] proj/R_overlay:master " André Erdmann
2013-04-25 16:44 André Erdmann
2013-03-05 11:27 André Erdmann
2013-01-09 19:15 André Erdmann
2012-08-20 11:16 André Erdmann
2012-08-16 16:28 André Erdmann
2012-08-10 17:56 André Erdmann
2012-08-10 15:16 André Erdmann
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox