* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
@ 2015-01-26 17:41 André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2015-01-26 17:41 UTC (permalink / raw
To: gentoo-commits
commit: 5a767d95450d48aed547234114c486142d97186b
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Dec 16 00:42:40 2014 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Mon Jan 26 17:33:56 2015 +0000
URL: http://sources.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=5a767d95
doc/, hook env: document stdin==/dev/null
---
doc/html/usage.html | 38 ++++++++++++++++++++++++++++++--------
doc/rst/usage.rst | 9 ++++++++-
2 files changed, 38 insertions(+), 9 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index a8075cb..440896e 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.10: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.12: 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 7514 2012-09-14 14:27:12Z milde $
+:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
@@ -313,6 +313,21 @@ table.docutils th.field-name, table.docinfo th.docinfo-name {
white-space: nowrap ;
padding-left: 0 }
+/* "booktabs" style (no vertical lines) */
+table.docutils.booktabs {
+ border: 0px;
+ border-top: 2px solid;
+ border-bottom: 2px solid;
+ border-collapse: collapse;
+}
+table.docutils.booktabs * {
+ border: 0px;
+}
+table.docutils.booktabs th {
+ border-bottom: thin solid;
+ text-align: left;
+}
+
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
@@ -2740,7 +2755,10 @@ 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,
+script.
+As these scripts are supposed to be non-interactive,
+<em>stdin</em> gets redirected to <tt class="docutils literal">/dev/null</tt>, except for <em>user</em>-event hooks.
+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>
@@ -2812,7 +2830,7 @@ template gives an idea of how to write them:</p>
</span>
<span class="comment"># the script must not exit if everything went well (return is ok)
-</span><span class="keyword">return </span>0
+</span><span class="keyword">return</span> 0
</pre>
</div>
</div>
@@ -3193,8 +3211,8 @@ They should, however, not execute any code directly.</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><span class="keyword">if</span> <span class="operator">[</span> -z <span class="literal string double">"${__HAVE_<name>__-}"</span> <span class="operator">]</span><span class="punctuation">;</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
# ...
@@ -3229,7 +3247,11 @@ They should, however, not execute any code directly.</p>
</tr>
<tr><td>user</td>
<td>unchanged</td>
-<td>user-triggered event</td>
+<td><p class="first">user-triggered event</p>
+<p class="last">This is the only event for
+which stdin does not get
+redirected.</p>
+</td>
</tr>
</tbody>
</table>
@@ -5146,7 +5168,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2014-08-23.
+Generated on: 2015-01-26.
</div>
</body>
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index c6046c0..78acdff 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -2360,7 +2360,10 @@ without touching *roverlay's* source code.
To realize this, *roverlay* determines whether a given event is permitted
(`event policy`_) and, if so, creates a `hook environment`_ and runs the
-script. Additionally, shell scripts can load *roverlay's* *$FUNCTIONS* file,
+script.
+As these scripts are supposed to be non-interactive,
+*stdin* gets redirected to ``/dev/null``, except for *user*-event hooks.
+Additionally, shell scripts can load *roverlay's* *$FUNCTIONS* file,
which provides extra functionality.
.. Note::
@@ -2772,6 +2775,10 @@ The following table lists all known events (``ROVERLAY_PHASE``):
| db_written | *$OVERLAY* | stats database file written |
+-------------------+---------------------------+------------------------------+
| user | unchanged | user-triggered event |
+ | | | |
+ | | | This is the only event for |
+ | | | which stdin does not get |
+ | | | redirected. |
+-------------------+---------------------------+------------------------------+
^ permalink raw reply related [flat|nested] 10+ messages in thread* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
@ 2014-02-21 17:36 André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2014-02-21 17:36 UTC (permalink / raw
To: gentoo-commits
commit: 4a2a5a13e5d8ac1d062346ae3461da09ee68de7c
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Feb 21 17:34:11 2014 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Feb 21 17:34:11 2014 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=4a2a5a13
doc/: some updates
---
doc/html/usage.html | 78 +++++++++++++++++++++++++++++++++++++++++++-----
doc/rst/usage.rst | 85 +++++++++++++++++++++++++++++++++++++++++++++++++----
2 files changed, 150 insertions(+), 13 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 4a48388..ffc3d5f 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -1574,9 +1574,54 @@ 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>
+ebuild for the <em>new</em> package file. A revision-bump is triggered if the
+package files (new/old) originate from the same repository,
+but their checksums differ. Otherwise, the new package is discarded.</p>
<p>The <em>distmap file</em> can optionally be compressed (bzip2 or gzip), which
reduces its size considerably.</p>
+<p>The first line of the <em>distmap file</em> specifies its field separator and version:</p>
+<pre class="code text literal-block">
+<FIELD_SEPARATOR<DISTMAP_VERSION
+</pre>
+<p>It is followed by zero or more entries whose format is version-dependent:</p>
+<pre class="code text literal-block">
+# version 0 (field separator = "|")
+<package mirror file>|<repo name>|<repo file>|<sha256>
+</pre>
+<p>Description of these fields:</p>
+<blockquote>
+<dl class="docutils">
+<dt>package mirror file</dt>
+<dd><p class="first">Path of the package file relative to the package mirror dir.
+Usually the name of the package file.</p>
+<p class="last">Special values: <em><none></em></p>
+</dd>
+<dt>repo name</dt>
+<dd><p class="first">Name of the package's repository.</p>
+<p>Special values:</p>
+<ul class="simple">
+<li><tt class="docutils literal">U</tt> if unknown</li>
+</ul>
+<div class="note last">
+<p class="first admonition-title">Note</p>
+<p class="last">"U" is reserved and should not be used as name in the repo
+config file.</p>
+</div>
+</dd>
+<dt>repo file</dt>
+<dd><p class="first">Path of the package file relative to the repository's directory.
+Differs from <em>package mirror file</em> if the file had to be renamed in
+order to avoid collisions.</p>
+<p>Special values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal">U</tt> if unknown (<em>repo file</em> is assumed to equal <em>package mirror file</em>)</li>
+<li><tt class="docutils literal">_</tt> if <em>repo file</em> equals <em>package mirror file</em></li>
+</ul>
+</dd>
+<dt>sha256</dt>
+<dd>Checksum of the package file.</dd>
+</dl>
+</blockquote>
</div>
</div>
<div class="section" id="additions-directory">
@@ -2017,7 +2062,8 @@ ignored.</p>
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>.
+<p>Except for <em>always true/false</em>,
+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.
@@ -2206,7 +2252,7 @@ with a fixed number of conditions, e.g. 1. This is why there is no
ambiguous, either <em>NOR</em> or <em>NAND</em>.</p>
<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>
+<p class="last"><em>VERUM</em> and <em>FALSUM</em> do not accept any nested condition.</p>
</div>
<p>Using this syntax, match blocks can be nested indefinitely (minus technical
limitations):</p>
@@ -2626,7 +2672,19 @@ 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>
+<p>Use <tt class="docutils literal"><span class="pre">roverlay-setup</span> hooks</tt> for managing hooks:</p>
+<pre class="literal-block">
+# activate a hook by adding it to one or more events
+# the script's default event is used if <event> is omitted.
+roverlay-setup hooks add <name> [<event>...]
+
+# deactive a hook (remove it from one or more events)
+roverlay-setup hooks del <name> [<event>...]
+
+# list all hooks and show for which events they are run
+roverlay-setup hooks [show]
+</pre>
+<p>Alternatively, hook scripts can be activated by means of symlinking:</p>
<pre class="code text literal-block">
ln -s <real script> ${ADDITIONS_DIR}/hooks/<event>/<name>.sh
# or
@@ -3208,10 +3266,16 @@ 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="websync-timeout">
+<dt>WEBSYNC_TIMEOUT</dt>
+<dd><p class="first">Set the timeout for websync repo connections, in seconds.</p>
+<p class="last">Defaults to 10.</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>
+required (see <a class="reference internal" href="#use-portage-licenses">USE_PORTAGE_LICENSES</a>).</p>
<p class="last">Defaults to "/usr/portage".</p>
</dd>
</dl>
@@ -3356,7 +3420,7 @@ config file, "hardlink symlink".</p>
<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>
+file has to be read once.</p>
<p class="last">Defaults to <em>no</em> as the verification is normally not needed.</p>
</dd>
</dl>
@@ -4974,7 +5038,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2014-01-25.
+Generated on: 2014-02-21.
</div>
</body>
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index d70d951..c2d8bc9 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1221,12 +1221,64 @@ created (in previous runs).
With the help of the *distmap file*, *roverlay* is able to determine whether
upstream has changed a package file silently and creates a revision-bumped
-ebuild for the *new* package file.
+ebuild for the *new* package file. A revision-bump is triggered if the
+package files (new/old) originate from the same repository,
+but their checksums differ. Otherwise, the new package is discarded.
The *distmap file* can optionally be compressed (bzip2 or gzip), which
reduces its size considerably.
+The first line of the *distmap file* specifies its field separator and version:
+
+.. code:: text
+
+ <FIELD_SEPARATOR<DISTMAP_VERSION
+
+
+It is followed by zero or more entries whose format is version-dependent:
+
+.. code:: text
+
+ # version 0 (field separator = "|")
+ <package mirror file>|<repo name>|<repo file>|<sha256>
+
+
+Description of these fields:
+
+ package mirror file
+ Path of the package file relative to the package mirror dir.
+ Usually the name of the package file.
+
+ Special values: *<none>*
+
+ repo name
+ Name of the package's repository.
+
+ Special values:
+
+ * ``U`` if unknown
+
+ .. Note::
+
+ "U" is reserved and should not be used as name in the repo
+ config file.
+
+ repo file
+ Path of the package file relative to the repository's directory.
+ Differs from *package mirror file* if the file had to be renamed in
+ order to avoid collisions.
+
+ Special values:
+
+ * ``U`` if unknown (*repo file* is assumed to equal *package mirror file*)
+ * ``_`` if *repo file* equals *package mirror file*
+
+ sha256
+ Checksum of the package file.
+
+
+
=====================
Additions Directory
=====================
@@ -1727,7 +1779,8 @@ There are two types of conditions, *trivial* conditions,
e.g. *always true/false* or *random - flip a coin*, and *non-trivial* ones
that depend on the information a package has, e.g. its repository or name.
-Only *non-trivial* conditions can be defined in *match statements*.
+Except for *always true/false*,
+only *non-trivial* conditions can be defined in *match statements*.
The consist of a **match keyword** that defines *what* should be matched, an
**accepted value** to compare against and an **operator** that defines the
relation *accepted value - package's information*, i.e. *how* to compare.
@@ -1873,7 +1926,7 @@ The nested block is terminated by indenting out, i.e. decreasing the
Correspondingly, the logic for the top-level match block is *AND* by
convention.
- *VERUM* and *FALSUM* do accept any nested condition.
+ *VERUM* and *FALSUM* do not accept any nested condition.
Using this syntax, match blocks can be nested indefinitely (minus technical
@@ -2256,7 +2309,20 @@ Having the same script at both locations results in executing it twice.
Activating a hook script
++++++++++++++++++++++++++
-Activating a hook script can be done by symlinking it:
+Use ``roverlay-setup hooks`` for managing hooks::
+
+ # activate a hook by adding it to one or more events
+ # the script's default event is used if <event> is omitted.
+ roverlay-setup hooks add <name> [<event>...]
+
+ # deactive a hook (remove it from one or more events)
+ roverlay-setup hooks del <name> [<event>...]
+
+ # list all hooks and show for which events they are run
+ roverlay-setup hooks [show]
+
+
+Alternatively, hook scripts can be activated by means of symlinking:
.. code-block:: text
@@ -2766,11 +2832,18 @@ RSYNC_BWLIMIT
Defaults to <not set>, which disables bandwidth limitation.
+.. _WEBSYNC_TIMEOUT:
+
+WEBSYNC_TIMEOUT
+ Set the timeout for websync repo connections, in seconds.
+
+ Defaults to 10.
+
.. _PORTDIR:
PORTDIR
Path to the portage tree. This option is **recommended**, but not always
- required.
+ required (see USE_PORTAGE_LICENSES_).
Defaults to "/usr/portage".
@@ -2926,7 +2999,7 @@ OVERLAY_DISTDIR_STRATEGY
OVERLAY_DISTDIR_VERIFY
A *bool* that controls whether file integrity of *OVERLAY_DISTDIR_ROOT*
should be checked on startup. This is an expensive operation since each
- file have to be read once.
+ file has to be read once.
Defaults to *no* as the verification is normally not needed.
^ permalink raw reply related [flat|nested] 10+ messages in thread* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
@ 2013-09-26 22:34 André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2013-09-26 22:34 UTC (permalink / raw
To: gentoo-commits
commit: ca3cb997fc66649964ab7062914742bd3b70a2ba
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Thu Sep 26 22:34:17 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Thu Sep 26 22:34:17 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=ca3cb997
minor usage doc change
---
doc/html/usage.html | 13 +++++++------
doc/rst/usage.rst | 3 ++-
2 files changed, 9 insertions(+), 7 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 939bf10..2ca9847 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -2325,13 +2325,14 @@ information</td>
<tr><td>add_<key></td>
<td>1</td>
</tr>
-<tr><td>depstr_ignore
-depres_ignore</td>
-<td>ebuild creation</td>
-<td>1</td>
-<td>ignore
+<tr><td>depstr_ignore</td>
+<td rowspan="2">ebuild creation</td>
+<td rowspan="2">1</td>
+<td rowspan="2">ignore
<em>dependency strings</em></td>
</tr>
+<tr><td>depres_ignore</td>
+</tr>
<tr><td>null</td>
<td rowspan="2"><em>n/a</em></td>
<td rowspan="2">none</td>
@@ -4944,7 +4945,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-09-23.
+Generated on: 2013-09-26.
</div>
</body>
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index d3e004f..c341d42 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1961,7 +1961,8 @@ control *where*) and the number of values they accept:
| | | | information |
+----------------+-------------------+-------------+------------------------+
| depstr_ignore | ebuild creation | 1 | ignore |
- | depres_ignore | | | *dependency strings* |
+ +----------------+ | | *dependency strings* |
+ | depres_ignore | | | |
+----------------+-------------------+-------------+------------------------+
| null | *n/a* | none | does nothing |
+----------------+ | | (can be used for |
^ permalink raw reply related [flat|nested] 10+ messages in thread* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
@ 2013-09-23 15:30 André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2013-09-23 15:30 UTC (permalink / raw
To: gentoo-commits
commit: ca55b908e18fb904d612940505147b93d72ed92b
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Mon Sep 23 14:14:38 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Mon Sep 23 14:14:38 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=ca55b908
doc/: add Bash as dependency for standalone roverlay
---
doc/html/usage.html | 4 +++-
doc/rst/usage.rst | 4 +++-
2 files changed, 6 insertions(+), 2 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index c00960a..939bf10 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -548,7 +548,9 @@ Reading the other chapters (4-14) is recommended.</p>
</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><p class="first">setuptools for installing <em>roverlay</em> (<a class="reference external" href="http://pypi.python.org/pypi/setuptools">http://pypi.python.org/pypi/setuptools</a>)</p>
+</li>
+<li><p class="first">Bash for using <em>roverlay</em> standalone</p>
</li>
<li><p class="first">rsync (for using rsync repositories)</p>
</li>
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 803be6d..d3e004f 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -99,7 +99,9 @@ Expected prior knowlegde:
* argparse (http://code.google.com/p/argparse)
* concurrent.futures (http://pypi.python.org/pypi/futures) (optional)
-* setuptools (http://pypi.python.org/pypi/setuptools)
+* setuptools for installing *roverlay* (http://pypi.python.org/pypi/setuptools)
+
+* Bash for using *roverlay* standalone
* rsync (for using rsync repositories)
^ permalink raw reply related [flat|nested] 10+ messages in thread* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
@ 2013-09-06 11:10 André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2013-09-06 11:10 UTC (permalink / raw
To: gentoo-commits
commit: d1a648e7e859382dddd81636754ee1877b36bc73
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Sep 6 11:10:07 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Sep 6 11:10:07 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=d1a648e7
usage doc: package rules 'license' action
+ error codes for git hooks
---
doc/html/usage.html | 14 ++++++++++++--
doc/rst/usage.rst | 10 +++++++++-
2 files changed, 21 insertions(+), 3 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index b5fe42f..754daff 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -2176,11 +2176,15 @@ an ebuild for it</td>
<tr><td>do-not-process</td>
</tr>
<tr><td>keywords</td>
-<td>ebuild variables</td>
+<td rowspan="2">ebuild variables</td>
<td>>= 1</td>
<td>set per-package
<tt class="docutils literal">KEYWORDS</tt></td>
</tr>
+<tr><td>license</td>
+<td>1</td>
+<td>set <tt class="docutils literal">LICENSE</tt></td>
+</tr>
<tr><td rowspan="2">trace</td>
<td rowspan="2">package rules</td>
<td>none</td>
@@ -2776,6 +2780,12 @@ when included in the hook script, most of the enviroment variables readonly.</p>
<tr><td>EX_ARG_ERR</td>
<td>default exit code for arg errors</td>
</tr>
+<tr><td>EX_GIT_ERR
+EX_GIT_ADD_ERR
+EX_GIT_COMMIT_ERR
+EX_GIT_PUSH_ERR</td>
+<td>git-related error codes</td>
+</tr>
<tr><td>SCRIPT_FILENAME</td>
<td>file name of the hook script</td>
</tr>
@@ -2843,7 +2853,7 @@ function files</td>
# int qwhich ( *command )
# Returns 0 if all listed commands are found by "which", else 1.
#
-# int sync_allowed ( action_name, [msg_nosync], [msg_sync] )
+# int sync_allowed ( action_name, [msg_nosync], [msg_sync] )
# Returns 0 if syncing for the given action is allowed, else 1.
# Also prints a message.
#
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 0b670fc..6a48e99 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1844,6 +1844,8 @@ control *where*) and the number of values they accept:
+----------------+-------------------+-------------+------------------------+
| keywords | ebuild variables | >= 1 | set per-package |
| | | | ``KEYWORDS`` |
+ +----------------+ +-------------+------------------------+
+ | license | | 1 | set ``LICENSE`` |
+----------------+-------------------+-------------+------------------------+
| trace | package rules | none | mark a package as |
| | | | modified |
@@ -2345,6 +2347,12 @@ when included in the hook script, most of the enviroment variables readonly.
+-----------------+-------------------------------------------------------+
| EX_ARG_ERR | default exit code for arg errors |
+-----------------+-------------------------------------------------------+
+ | EX_GIT_ERR | git-related error codes |
+ | EX_GIT_ADD_ERR | |
+ | EX_GIT_COMMIT\ | |
+ | _ERR | |
+ | EX_GIT_PUSH_ERR | |
+ +-----------------+-------------------------------------------------------+
| SCRIPT_FILENAME | file name of the hook script |
+-----------------+-------------------------------------------------------+
| SCRIPT_NAME | name of the hook script (without file extension) |
@@ -2410,7 +2418,7 @@ when included in the hook script, most of the enviroment variables readonly.
# int qwhich ( *command )
# Returns 0 if all listed commands are found by "which", else 1.
#
- # int sync_allowed ( action_name, [msg_nosync], [msg_sync] )
+ # int sync_allowed ( action_name, [msg_nosync], [msg_sync] )
# Returns 0 if syncing for the given action is allowed, else 1.
# Also prints a message.
#
^ permalink raw reply related [flat|nested] 10+ messages in thread* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
@ 2013-08-29 12:36 André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2013-08-29 12:36 UTC (permalink / raw
To: gentoo-commits
commit: a66b4c2e97c9e8ec14e30a68f3fd3ecaa0356b0b
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Thu Aug 29 12:35:57 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Thu Aug 29 12:35:57 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=a66b4c2e
doc/: add depstr_ignore action
---
doc/html/usage.html | 9 ++++++++-
doc/rst/usage.rst | 3 +++
2 files changed, 11 insertions(+), 1 deletion(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 153084d..dd321ea 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -2227,6 +2227,13 @@ information</td>
<tr><td>add_<key></td>
<td>1</td>
</tr>
+<tr><td>depstr_ignore
+depres_ignore</td>
+<td>ebuild creation</td>
+<td>1</td>
+<td>ignore
+<em>dependency strings</em></td>
+</tr>
<tr><td>null</td>
<td rowspan="2"><em>n/a</em></td>
<td rowspan="2">none</td>
@@ -4810,7 +4817,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-08-27.
+Generated on: 2013-08-29.
</div>
</body>
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 10da45a..9db0ff3 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1870,6 +1870,9 @@ control *where*) and the number of values they accept:
| | | | overwriting existing |
| | | | information |
+----------------+-------------------+-------------+------------------------+
+ | depstr_ignore | ebuild creation | 1 | ignore |
+ | depres_ignore | | | *dependency strings* |
+ +----------------+-------------------+-------------+------------------------+
| null | *n/a* | none | does nothing |
+----------------+ | | (can be used for |
| pass | | | improving readability) |
^ permalink raw reply related [flat|nested] 10+ messages in thread* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
@ 2013-08-20 7:50 André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2013-08-20 7:50 UTC (permalink / raw
To: gentoo-commits
commit: cffdc1c8405d1c74d8188e161ccdd91af39e5c7d
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Aug 20 07:49:09 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Aug 20 07:49:09 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=cffdc1c8
doc/: clarify package rule example
---
doc/html/usage.html | 5 +++--
doc/rst/usage.rst | 3 ++-
2 files changed, 5 insertions(+), 3 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 0f32e56..82d3f0e 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -2415,7 +2415,8 @@ MATCH:
any
ACTION:
# set category
- # CRAN->CRAN, CRAN-Archive->CRAN, BIOC-2.10/experimental->BIOC, ...
+ # CRAN->sci-CRAN, CRAN-Archive->sci-CRAN,
+ # BIOC-2.10/experimental->sci-BIOC, ...
#
rename category s=^(?P<repo>[^-/]+)([-/].*)?$=sci-\g<repo>=
END;
@@ -4780,7 +4781,7 @@ becomes "loop until resolver closes".</p>
</div>
<div class="footer">
<hr class="footer" />
-Generated on: 2013-08-19.
+Generated on: 2013-08-20.
</div>
</body>
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index e493420..991a4b9 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -2048,7 +2048,8 @@ A more generic rule that sets per-repo categories:
any
ACTION:
# set category
- # CRAN->CRAN, CRAN-Archive->CRAN, BIOC-2.10/experimental->BIOC, ...
+ # CRAN->sci-CRAN, CRAN-Archive->sci-CRAN,
+ # BIOC-2.10/experimental->sci-BIOC, ...
#
rename category s=^(?P<repo>[^-/]+)([-/].*)?$=sci-\g<repo>=
END;
^ permalink raw reply related [flat|nested] 10+ messages in thread* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/, doc/html/
@ 2013-06-05 18:11 André Erdmann
2013-06-13 16:34 ` [gentoo-commits] proj/R_overlay:master " André Erdmann
0 siblings, 1 reply; 10+ messages in thread
From: André Erdmann @ 2013-06-05 18:11 UTC (permalink / raw
To: gentoo-commits
commit: 7f7e0a65375dacbfad71d95ded2a034c6b41c555
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jun 5 18:11:01 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jun 5 18:11:01 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=7f7e0a65
doc/{rst,html}: fix typo in package rule examples
---
doc/html/usage.html | 2 +-
doc/rst/usage.rst | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index a02a772..9ab7683 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -2020,7 +2020,7 @@ END;
MATCH:
name ,= yaml
ACTION:
- rename_destfile s=^=R-package=
+ rename_destfile s=^=R-package/=
END;
</pre>
</div>
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index e74c091..adf26da 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1647,7 +1647,7 @@ Moving such packages to a "R-package" sub directory would be possible, too:
MATCH:
name ,= yaml
ACTION:
- rename_destfile s=^=R-package=
+ rename_destfile s=^=R-package/=
END;
^ permalink raw reply related [flat|nested] 10+ messages in thread* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
2013-06-05 18:11 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
@ 2013-06-13 16:34 ` André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2013-06-13 16:34 UTC (permalink / raw
To: gentoo-commits
commit: 7f7e0a65375dacbfad71d95ded2a034c6b41c555
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jun 5 18:11:01 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jun 5 18:11:01 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=7f7e0a65
doc/{rst,html}: fix typo in package rule examples
---
doc/html/usage.html | 2 +-
doc/rst/usage.rst | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index a02a772..9ab7683 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -2020,7 +2020,7 @@ END;
MATCH:
name ,= yaml
ACTION:
- rename_destfile s=^=R-package=
+ rename_destfile s=^=R-package/=
END;
</pre>
</div>
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index e74c091..adf26da 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1647,7 +1647,7 @@ Moving such packages to a "R-package" sub directory would be possible, too:
MATCH:
name ,= yaml
ACTION:
- rename_destfile s=^=R-package=
+ rename_destfile s=^=R-package/=
END;
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
@ 2012-08-20 14:04 André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2012-08-20 14:04 UTC (permalink / raw
To: gentoo-commits
commit: 149ebf6b03f7df5d341f350ecdc1a00712467d79
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Mon Aug 20 13:56:00 2012 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Mon Aug 20 13:56:00 2012 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=149ebf6b
documentation, usage.rst / usage.html
* avoid contracted forms
* minor additional info added
---
doc/html/usage.html | 234 +++++++++++++++++++++++++-------------------------
doc/rst/usage.rst | 238 +++++++++++++++++++++++++--------------------------
2 files changed, 233 insertions(+), 239 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 71d60df..836b031 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -427,9 +427,9 @@ system level which cannot be done by <em>install.packages()</em> in R.</p>
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>.
+It is 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
+<p><em>roverlay</em> is written in python. A homepage is not 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>
@@ -445,7 +445,7 @@ 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
+<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
test dependency rules.</p>
</li>
@@ -456,8 +456,13 @@ 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>
+<p>Expected prior knowlegde:</p>
+<blockquote>
+<ul class="simple">
+<li>a few <em>R package</em> basics</li>
+<li>portage basics, e.g. <em>Depend Atoms</em> and what an overlay is</li>
+</ul>
+</blockquote>
</div>
<div class="section" id="installation">
<h1><a class="toc-backref" href="#contents">2 Installation</a></h1>
@@ -512,9 +517,8 @@ all necessary config files into <em>/etc/roverlay</em>.</p>
</div>
<div class="section" id="manual-installation">
<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>
+<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
@@ -540,8 +544,8 @@ 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 doesn't create/install
-any config files!</p>
+<p class="last">Support for this installation type is limited - no config files will be
+installed!</p>
</div>
</div>
<div class="section" id="using-roverlay-without-installation">
@@ -569,20 +573,20 @@ 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 you've installed <em>roverlay</em> 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 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>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>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">
@@ -610,14 +614,14 @@ see <a class="reference internal" href="#providing-a-package-mirror">Providing a
</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>
+without an own log level. 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="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>
+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>
</div>
</dd>
<dt>LOG_LEVEL_CONSOLE</dt>
@@ -665,22 +669,21 @@ named <em>R-packages.eclass</em> should be part of your installation.</p>
</dd>
</dl>
</blockquote>
-<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
+<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 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>
+<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>
<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>
+<dd>See <a class="reference internal" href="#dependency-rules">Dependency Rules</a>, which explains the dependency rule syntax amd how
+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>
@@ -693,8 +696,8 @@ a typo) to be understood as 'Depends'.</dd>
</div>
<div class="section" id="running-it">
<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>If <em>roverlay</em> has been installed, you can run it with <tt class="docutils literal">roverlay</tt>, otherwise
+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>]
@@ -703,13 +706,12 @@ roverlay --config <config file> [<options>] [<commands>]
<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. 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>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. See <a class="reference internal" href="#basic-implementation-overview">Basic Implementation Overview</a> if you want
+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" />
@@ -718,7 +720,7 @@ in detail what <em>roverlay</em> does before running it.</p>
<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> </td><td>Disable downloading of R packages.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--no-incremental</span></kbd></td>
</tr>
@@ -726,11 +728,10 @@ in detail what <em>roverlay</em> does before running it.</p>
<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.
+<tr><td> </td><td><p class="first">Immediately write ebuilds when they are 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>
@@ -748,8 +749,8 @@ the default package repositories.</p>
</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.
+<p class="last"><em>--no-incremental</em> does not delete an existing overlay, it 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>
@@ -766,7 +767,7 @@ 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>
+<td>Disable overlay writing</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>
@@ -877,8 +878,8 @@ and may decide to write <em>p</em>'s ebuild now (or later)</p>
</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>
+<p>Assuming that the default configuration (where possible) and the <em>R-packages</em>
+eclass file are used, the result should look like:</p>
<pre class="code text literal-block">
<overlay root>/
<overlay root>/eclass
@@ -917,7 +918,7 @@ RDEPEND="${DEPEND:-}
_UNRESOLVED_PACKAGES=(<unresolvable, but optional dependencies>)
</pre>
-<p>Some of the variables may be missing if they're not needed.</p>
+<p>Some of the variables may be missing if they are not needed.</p>
<p>A really minimal ebuild would look like:</p>
<pre class="code text last literal-block">
<ebuild header>
@@ -1030,8 +1031,8 @@ if a package has more than one, e.g. one in its <em>Title</em> and one in its
<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 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>
+use the packages is determined by the concrete <strong>type of a repository</strong>,
+which is the topic of this section. It also covers repository configuration.</p>
<div class="section" id="a-word-about-repo-config-files">
<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>
@@ -1116,10 +1117,10 @@ Options with whitespace are not supported.</li>
</div>
<div class="section" id="getting-packages-from-a-repository-that-supports-http-only">
<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
-<em>PACKAGES</em>, with a special syntax (debian control file syntax).</p>
+<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>
<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">
@@ -1202,15 +1203,15 @@ file would be:</p>
<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>
+that they are 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>
+the <em>SRC_URI</em> variable in created ebuilds will be invalid unless you have
+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>
@@ -1230,7 +1231,7 @@ dictionary entry.</p>
<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>
+<em>dependency string(s)</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>
@@ -1270,7 +1271,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 !=dev-lang/R-2.10 )"</li>
+<li>"R ( !2.10 )" as "( !=dev-lang/R-2.10 dev-lang/R )"</li>
</ul>
</dd>
</dl>
@@ -1331,9 +1332,8 @@ in some R package DESCRIPTION files.</p>
</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>
+They can be found in <em>/etc/roverlay/simple-deprules.d</em> if <em>roverlay</em> has been
+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>
@@ -1361,7 +1361,7 @@ simple rule.</p>
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>
+<p>Available dependency types are</p>
<ul class="simple">
<li><em>all</em> (no type restrictions)</li>
<li><em>pkg</em> (resolve only R package dependencies)</li>
@@ -1418,7 +1418,7 @@ Their rule block begins with '{' + newline, followed by one
<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,
+zero or more <em>dependency strings</em>. An empty rule makes little sense,
though.</p>
</div>
</dd>
@@ -1454,10 +1454,9 @@ the written one.</p>
</div>
</dd>
<dt>Rule Stubs</dt>
-<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>
+<dd><p class="first">Selfdeps can be written using a shorter syntax.
+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">
@@ -1520,14 +1519,14 @@ be replaced by the user's home etc.).
Additionaly the value has to be a file (or directory) if it exists.</dd>
<dt><empty></dt>
<dd>Specifying empty values often leads to errors if an option has value type
-restrictions. It's better to comment out options.</dd>
+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>
<dl class="docutils" id="distfiles">
<dt>DISTFILES</dt>
-<dd>Alias for <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
+<dd>Alias to <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
</dl>
<dl class="docutils" id="distfiles-root">
<dt>DISTFILES_ROOT</dt>
@@ -1539,7 +1538,22 @@ location (see <a class="reference internal" href="#repo-config-options">repo con
</dl>
<dl class="docutils" id="distroot">
<dt>DISTROOT</dt>
-<dd>Alias for <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
+<dd>Alias to <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
+</dl>
+<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>
+<p class="last">Defaults to <em>ebuild</em>, which should be fine in most cases.</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.
+This will pass '--bwlimit=<value>' to all rsync commands.</p>
+<p class="last">Defaults to <not set>, which disables bandwidth limitation.</p>
+</dd>
</dl>
</div>
<div class="section" id="overlay-options">
@@ -1658,8 +1672,8 @@ to actually get any log messages.</p>
</dl>
<dl class="docutils" id="log-level">
<dt>LOG_LEVEL</dt>
-<dd><p class="first">Sets the default log level. Log targets that don't have their own log
-level set will use this value.</p>
+<dd><p class="first">Sets the default log level. Log targets will use this value unless they
+have their own log level.</p>
<p class="last">Defaults to <not set> - all log targets will use their own defaults</p>
</dd>
</dl>
@@ -1695,7 +1709,7 @@ exist or is commented out even if <a class="reference internal" href="#log-file-
</dl>
<dl class="docutils" id="log-file-buffered">
<dt>LOG_FILE_BUFFERED</dt>
-<dd><p class="first">Enable/Disable buffering of log entries in memory before they're written
+<dd><p class="first">Enable/Disable buffering of log entries in memory before they are written
to the log file. Enabling this reduces I/O blocking, especially when using
low log levels. The value must be a <em>bool</em>.</p>
<p class="last">Defaults to enabled.</p>
@@ -1753,14 +1767,6 @@ results.</p>
<p class="last">Defaults to <not set>, which disables writing of description data files.</p>
</dd>
</dl>
-<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>
-<p class="last">Defaults to <em>ebuild</em>, which should be fine in most cases.</p>
-</dd>
-</dl>
<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
@@ -1768,13 +1774,6 @@ on <em>roverlay</em> exit. Primarily useful for creating new rules.</p>
<p class="last">Defaults to <not set>, which disables this feature.</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.
-This will pass '--bwlimit=<value>' to all rsync commands.</p>
-<p class="last">Defaults to <not set>, which disables bandwidth limitation.</p>
-</dd>
-</dl>
</div>
</div>
<div class="section" id="field-definition-config">
@@ -1783,9 +1782,9 @@ 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-insensitive options without a value - they're
+and flags. Flags are case-insensitive options without a value - they are
enabled by listing them.</p>
-<p id="field-options"><span id="field-option"></span>Known field options:</p>
+<p id="field-options"><span id="field-option"></span>Available field options:</p>
<blockquote>
<dl class="docutils" id="field-option-default-value">
<dt>default_value</dt>
@@ -1857,7 +1856,7 @@ such a field is found.</dd>
</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>
+<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>
@@ -1898,7 +1897,7 @@ such a field is found.</dd>
<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>
+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>
@@ -1991,7 +1990,7 @@ in <em><dir></em></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
+<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>
@@ -2034,7 +2033,7 @@ Resolved as: ('>=dev-lang/R-2.15',)
cmd % ? R
Trying to resolve ('R',).
-Channel returned None. At least one dep couldn't be resolved.
+Channel returned None. At least one dep could not be resolved.
cmd % p
~dev-lang/R :: R language
@@ -2046,7 +2045,7 @@ cmd % p
cmd % ? R language
Trying to resolve ('R language',).
-Channel returned None. At least one dep couldn't be resolved.
+Channel returned None. At least one dep could not be resolved.
cmd % exit
</pre>
@@ -2076,7 +2075,7 @@ 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
+the overlay. The overlay may refuse to accept <em>p</em> if an ebuild already exists
for it. Otherwise, <em>p</em> is now part of the overlay and has to pass
<em>ebuild creation</em>.</p>
</div>
@@ -2129,14 +2128,14 @@ 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
+<em>BasicRepos</em> are used to realize <em>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.
+awareness concerning <em>sync()</em> 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">
@@ -2222,7 +2221,7 @@ to be accessible.</p>
<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,
+overlay</em>. It is 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>
@@ -2303,7 +2302,7 @@ 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,
+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>
@@ -2323,7 +2322,7 @@ R_SUGGESTS).</p>
<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
+<li><strong>Stop ebuild creation</strong> if a channel reports that it could not 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>
@@ -2407,7 +2406,7 @@ This section describes which <em>dependency fields</em> are used and how.</p>
<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
+This is not 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
@@ -2446,7 +2445,7 @@ strings</em> have been added.</p>
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
+been resolved or waiting does not 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>
@@ -2455,16 +2454,18 @@ been resolved or waiting doesn't make sense anymore, i.e. at least one
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><p class="first">The <em>channel</em> returns the result to the ebuild creation:</p>
+<ul class="simple">
+<li>a 2-tuple of resolved and unresolvable dependencies or</li>
+<li>"nothing" if the request is not satisfiable, i.e. one or more required
+dependencies are unresolvable.</li>
+</ul>
</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>.
+<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>
<p>A <em>dependency rule pool</em> combines a list of <em>dependency rules</em> with a
@@ -2508,7 +2509,7 @@ resolution, wait for results, and send them to the other end.</p>
<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
+<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
their origin (an <em>EbuildJob channel</em>).</p>
<p>Besides that, it also offers functionality to register new channels, add
@@ -2535,8 +2536,7 @@ while <dependencies queued for resolution>
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>
+ if <a rule pool supports TRY_OTHER and does not accept depenv's type and resolves depenv>
resolved <= True
end if
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 5e04d49..39cdac8 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -34,10 +34,10 @@ done during the *Google Summer of Code 2012*.
At its current state, *roverlay* 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 *R Overlay*.
+It is also able to work incrementally, i.e. update an existing *R Overlay*.
Most aspects of overlay creation are configurable with text files.
-*roverlay* is written in python. There's no homepage available, only a
+*roverlay* is written in python. A homepage is not available, only a
`git repository`_ that contains the source code.
This document is targeted at
@@ -56,7 +56,7 @@ This document is targeted at
namely `Repositories / Getting Packages`_, `Dependency Rules`_,
`Configuration Reference`_ and `Field Definition Config`_.
- There's another chapter that is only interesting for testing, the
+ There is another chapter that is only interesting for testing, the
`Dependency Resolution Console`_ (9), which can be used to interactively
test dependency rules.
@@ -66,8 +66,10 @@ This document is targeted at
The most important chapter is `Implementation Overview`_ (10) which has
references to other chapters (4-8) where required.
-It's expected that you already know about *R packages* (basically a tarball)
-and some portage basics, e.g. *Depend Atoms* and what an overlay is.
+Expected prior knowlegde:
+
+ * a few *R package* basics
+ * portage basics, e.g. *Depend Atoms* and what an overlay is
==============
@@ -121,9 +123,8 @@ all necessary config files into */etc/roverlay*.
Manual Installation
---------------------
-After installing the dependencies as listed in `Prerequisites`_,
-clone the `roverlay git repo`_ and then
-install *roverlay* and its python modules:
+After installing the dependencies as listed in `Prerequisites`_, clone the
+`roverlay git repo`_ and then install *roverlay* and its python modules:
.. code-block:: sh
@@ -156,8 +157,8 @@ install *roverlay* and its python modules:
.. Warning::
- Support for this installation type is limited - it doesn't create/install
- any config files!
+ Support for this installation type is limited - no config files will be
+ installed!
---------------------------------------
Using *roverlay* without installation
@@ -191,22 +192,21 @@ as the *R Overlay src directory* from now on.
------------------------------
*roverlay* needs a configuration file to run.
-If you've installed *roverlay* with *emerge*, it will look for the config
-file in that order:
+If roverlay has been installed with *emerge*, it will for the config file in
+that order:
1. *<current directory>/R-overlay.conf*
-2. *~/.R-overlay.conf*
-3. */etc/roverlay/R-overlay.conf*,
+#. *~/.R-overlay.conf*
+#. */etc/roverlay/R-overlay.conf*,
which is part of the installation but has to be modified.
-Otherwise, an example config file is available in the *R Overlay src directory*
-and *roverlay* will only look for *R-overlay.conf* in the current directory.
-
-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 (-> ``<option> = "file1 file2"``).
+Otherwise, *roverlay* will only look for *R-overlay.conf* in the current
+directory. An example config file is available in the
+*R Overlay src directory*.
+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 (-> ``<option> = "file1 file2"``).
The following options should be set before running *roverlay*:
@@ -237,16 +237,16 @@ The following options should be set before running *roverlay*:
LOG_LEVEL
This sets the global log level, which is used for all log formats
- that don't override this option. Valid log levels are
- ``DEBUG``, ``INFO``, ``WARN``/``WARNING``, ``ERROR`` and ``CRITICAL``.
+ without an own log level. Valid log levels are ``DEBUG``, ``INFO``,
+ ``WARN``/``WARNING``, ``ERROR`` and ``CRITICAL``.
Example: LOG_LEVEL = WARNING
.. Note::
Be careful with low log levels, especially *DEBUG*.
- They produce a lot of messages that you probably don't want to see
- and increase the size of log files dramatically.
+ They produce a lot of messages that help to track ebuild creation of
+ the R packages, but increase the size of log files dramatically.
LOG_LEVEL_CONSOLE
This sets the console log level.
@@ -294,26 +294,25 @@ have reasonable defaults if *roverlay* has been installed using *emerge*:
Example: OVERLAY_ECLASS = ~/roverlay/eclass/R-packages.eclass
-There's another option that is useful if you want to create new dependency
-rules, LOG_FILE_UNRESOLVABLE_, which will write all unresolvable dependencies
+There is another option that is useful for creating new dependency rules,
+LOG_FILE_UNRESOLVABLE_, which will write all unresolvable dependencies
to the specified file (one dependency string per line).
+++++++++++++++++++++++++++++++++++++++++++++++++
Extended Configuration / Where to go from here?
+++++++++++++++++++++++++++++++++++++++++++++++++
-Proceed with `Running it`_ 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.
+Proceed with `Running it`_ 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.
Repositories
See `Repositories / Getting Packages`_, which describes how repositories
can be configured.
Dependency Rules
- See `Dependency Rules`_, which explains how dependency rules work and
- how they're written.
+ See `Dependency Rules`_, which explains the dependency rule syntax amd how
+ they work.
Main Config
See `Configuration Reference`_ for all main config options like log file
@@ -328,8 +327,8 @@ Field Definition
Running it
------------
-If you've installed *roverlay*, you can run it with ``roverlay``, otherwise
-you'll have to cd into the *R overlay src directory* and run ``./roverlay.py``.
+If *roverlay* has been installed, you can run it with ``roverlay``, otherwise
+cd into the *R overlay src directory* and run ``./roverlay.py``.
In any case, the basic *roverlay* script usage is
@@ -343,29 +342,27 @@ or
roverlay [<options>] [<commands>]
-which will search for the config file
-as described in `Required configuration steps`_.
-The default command is *create*, 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 ``roverlay`` should be
-fine. See `Basic Implementation Overview`_ if you'd rather like to know
-in detail what *roverlay* does before running it.
+which will search for the config file as described in
+`Required configuration steps`_. The default command is *create*, 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
+``roverlay`` should be fine. See `Basic Implementation Overview`_ if you want
+to know in detail what *roverlay* does before running it.
*roverlay* also accepts some **options**, most notably:
--nosync, --no-sync
- Don't download R packages.
+ Disable downloading of R packages.
--no-incremental
Force recreation of existing ebuilds
--immediate-ebuild-writes
- Immediately write ebuilds when they're ready.
+ Immediately write ebuilds when they are ready.
- 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.
+ 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 ???>>.
@@ -381,8 +378,8 @@ in detail what *roverlay* does before running it.
.. Note::
- *--no-incremental* doesn't delete an existing overlay, it will merely
- ignores and, potentially, overwrites existing ebuilds.
+ *--no-incremental* does not delete an existing overlay, it merely ignores
+ and, potentially, overwrites existing ebuilds.
Use *rm -rf <overlay>* to do that.
@@ -396,7 +393,7 @@ For **testing** *roverlay*, these **options** may be convenient:
an overlay that is not suitable for production usage.
--no-write
- Don't write the overlay
+ Disable overlay writing
--show
Print all ebuilds and metadata to console
@@ -508,8 +505,8 @@ These are the steps that *roverlay* performs:
Expected Overlay Result / Structure of the generated overlay
--------------------------------------------------------------
-Assuming that you're using the default configuration (where possible) and
-the *R-packages* eclass file, the result should look like:
+Assuming that the default configuration (where possible) and the *R-packages*
+eclass file are used, the result should look like:
.. code-block:: text
@@ -553,7 +550,7 @@ Ebuild Template
_UNRESOLVED_PACKAGES=(<unresolvable, but optional dependencies>)
- Some of the variables may be missing if they're not needed.
+ Some of the variables may be missing if they are not needed.
A really minimal ebuild would look like:
@@ -673,8 +670,8 @@ Example: seewave from CRAN
*roverlay* is capable of downloading R packages via rsync and http,
and is able to use any packages locally available. The method used to get and
-use the packages is determined by the concrete **type of a repository** and
-that's what this section is about. It also covers repository configuration.
+use the packages is determined by the concrete **type of a repository**,
+which is the topic of this section. It also covers repository configuration.
.. _repo config:
@@ -775,10 +772,10 @@ Examples:
Getting packages from a repository that supports http only
------------------------------------------------------------
-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
-*PACKAGES*, with a special syntax (debian control file syntax).
+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 *PACKAGES*,
+with a special syntax (debian control file syntax).
A package list example,
excerpt from `omegahat's PACKAGES file`_ (as of Aug 2012):
@@ -886,17 +883,17 @@ Example:
src_uri = http://localhost/R-packages
This will use all packages from */var/local/R-packages* and assumes
-that they're available via *http://localhost/R-packages*.
+that they are available via *http://localhost/R-packages*.
A local directory will never be modified.
.. Important::
Using this repo type is **not recommended for production usage** because
- the *SRC_URI* 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 **websync** repo types,
- websync_repo_ and websync_pkglist_.
+ the *SRC_URI* variable in created ebuilds will be invalid unless you have
+ downloaded all packages from the same remote in which case you should
+ consider using one of the **websync** repo types, websync_repo_ and
+ websync_pkglist_.
==================
@@ -922,7 +919,7 @@ This is the only rule implementation currently available.
default
The expected behavior of a dictionary-based rule: It matches one or more
- *dependency strings* and resolves them as a *dependency*
+ *dependency string(s)* and resolves them as a *dependency*.
ignore
This variant will ignore *dependency strings*. Technically, it will
@@ -964,7 +961,7 @@ Fuzzy Rules
* "R 2.12" as ">=dev-lang/R-2.12"
* "The R PROGRAMMING LANGUAGE [<2.14] from http://www.r-project.org/"
as "<dev-lang/R-2.14"
- * "R ( !2.10 )" as "( dev-lang/R !=dev-lang/R-2.10 )"
+ * "R ( !2.10 )" as "( !=dev-lang/R-2.10 dev-lang/R )"
++++++++++++++++++++
@@ -1029,9 +1026,8 @@ Example 4 - *ignore* simple rule
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 */etc/roverlay/simple-deprules.d*
-if you've installed *roverlay* with *emerge*,
-else in *<R Overlay src directory>/simple-deprules.d*.
+They can be found in */etc/roverlay/simple-deprules.d* if *roverlay* has been
+installed with *emerge*, else in *<R Overlay src directory>/simple-deprules.d*.
.. _Dependency Rule File Syntax:
@@ -1067,7 +1063,7 @@ Keywords
whatever comes first, will only match *dependency strings*
with the specified *dependency type*.
- Available dependency types choices are
+ Available dependency types are
* *all* (no type restrictions)
* *pkg* (resolve only R package dependencies)
@@ -1121,7 +1117,7 @@ Multi line rules
.. Note::
Technically, this rule syntax can be used to specify rules with
- zero or more *dependency strings*. An empty rule doesn't make much sense,
+ zero or more *dependency strings*. An empty rule makes little sense,
though.
Comments
@@ -1161,10 +1157,9 @@ Selfdep
Rule Stubs
- There's a shorter syntax for selfdeps.
- For example, if your OVERLAY_CATEGORY is *sci-R*,
- *zoo* should be resolved as *sci-R/zoo*.
- This rule can be written as a single word, *zoo*.
+ Selfdeps can be written using a shorter syntax.
+ For example, if your OVERLAY_CATEGORY is *sci-R*, *zoo* should be resolved
+ as *sci-R/zoo*. This rule can be written as a single word, *zoo*.
Syntax:
.. code:: text
@@ -1217,7 +1212,7 @@ file, dir
<empty>
Specifying empty values often leads to errors if an option has value type
- restrictions. It's better to comment out options.
+ restrictions. Commenting it out is safe.
The following sections will list all config entries.
@@ -1229,7 +1224,7 @@ The following sections will list all config entries.
.. _DISTFILES:
DISTFILES
- Alias for DISTFILES_ROOT_.
+ Alias to DISTFILES_ROOT_.
.. _DISTFILES_ROOT:
@@ -1243,7 +1238,24 @@ DISTFILES_ROOT
.. _DISTROOT:
DISTROOT
- Alias for DISTFILES_ROOT_.
+ Alias to DISTFILES_ROOT_.
+
+.. _EBUILD_PROG:
+
+EBUILD_PROG
+ 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.
+
+ Defaults to *ebuild*, which should be fine in most cases.
+
+.. _RSYNC_BWLIMIT:
+
+RSYNC_BWLIMIT
+ Set a max. average bandwidth usage in kilobytes per second.
+ This will pass '--bwlimit=<value>' to all rsync commands.
+
+ Defaults to <not set>, which disables bandwidth limitation.
-----------------
@@ -1383,8 +1395,8 @@ LOG_ENABLED
.. _LOG_LEVEL:
LOG_LEVEL
- Sets the default log level. Log targets that don't have their own log
- level set will use this value.
+ Sets the default log level. Log targets will use this value unless they
+ have their own log level.
Defaults to <not set> - all log targets will use their own defaults
@@ -1428,7 +1440,7 @@ LOG_FILE
.. _LOG_FILE_BUFFERED:
LOG_FILE_BUFFERED
- Enable/Disable buffering of log entries in memory before they're written
+ Enable/Disable buffering of log entries in memory before they are written
to the log file. Enabling this reduces I/O blocking, especially when using
low log levels. The value must be a *bool*.
@@ -1493,15 +1505,6 @@ DESCRIPTION_DIR
Defaults to <not set>, which disables writing of description data files.
-.. _EBUILD_PROG:
-
-EBUILD_PROG
- 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.
-
- Defaults to *ebuild*, which should be fine in most cases.
-
.. _LOG_FILE_UNRESOLVABLE:
LOG_FILE_UNRESOLVABLE
@@ -1510,14 +1513,6 @@ LOG_FILE_UNRESOLVABLE
Defaults to <not set>, which disables this feature.
-.. _RSYNC_BWLIMIT:
-
-RSYNC_BWLIMIT
- Set a max. average bandwidth usage in kilobytes per second.
- This will pass '--bwlimit=<value>' to all rsync commands.
-
- Defaults to <not set>, which disables bandwidth limitation.
-
.. _Field Definition:
@@ -1530,13 +1525,13 @@ how an R package's DESCRIPTION file is read.
See the next section, `default field definition file`_, for an example.
Each information field has its own section which declares a set of options
-and flags. Flags are case-insensitive options without a value - they're
+and flags. Flags are case-insensitive options without a value - they are
enabled by listing them.
.. _field option:
.. _field options:
-Known field options:
+Available field options:
.. _field option\: default_value:
@@ -1623,7 +1618,7 @@ Known field flags:
.. Note::
- It won't be checked whether a flag is known or not.
+ It is not checked whether a flag is known or not.
.. _default field definition file:
@@ -1675,7 +1670,7 @@ This is the default field definition file (without any ignored fields):
===============================
As previously stated, the *DepRes Console* is only meant for **testing**.
-It's an interactive console with the following features:
+It is an interactive console with the following features:
* resolve dependencies
* create new dependency rules (**only single line rules**)
@@ -1739,7 +1734,7 @@ For reference, these commands are currently available:
+---------------------+----------------------------------------------------+
| set, unset | prints the status of currently (in)active modes |
+---------------------+----------------------------------------------------+
-| set *<mode>*, | sets or unsets *<mode>*. There's only one mode to |
+| set *<mode>*, | sets or unsets *<mode>*. There is only one mode to |
| unset *<mode>* | control, the *shlex mode* which controls how |
| | command arguments are parsed |
+---------------------+----------------------------------------------------+
@@ -1781,7 +1776,7 @@ Example Session:
cmd % ? R
Trying to resolve ('R',).
- Channel returned None. At least one dep couldn't be resolved.
+ Channel returned None. At least one dep could not be resolved.
cmd % p
~dev-lang/R :: R language
@@ -1793,7 +1788,7 @@ Example Session:
cmd % ? R language
Trying to resolve ('R language',).
- Channel returned None. At least one dep couldn't be resolved.
+ Channel returned None. At least one dep could not be resolved.
cmd % exit
@@ -1829,7 +1824,7 @@ Initialization may fail if the package's name cannot be understood, which is
most likely due to unsupported versioning schemes.
It is then checked whether the newly created *PackageInfo p* can be part of
-the overlay. The overlay may refuse to accept *p* if there's already an ebuild
+the overlay. The overlay may refuse to accept *p* if an ebuild already exists
for it. Otherwise, *p* is now part of the overlay and has to pass
*ebuild creation*.
@@ -1880,7 +1875,7 @@ implementing class. The most basic implementation that provides all common
data, status indicator functions and *PackageInfo* creation is called
*BasicRepo*. It also implements a rather abstract sync function that calls
subclass-specifc *_sync()*/*_nosync()* functions if available.
-*BasicRepo*s are used to realize *local repositories*. The other available
+*BasicRepos* are used to realize *local repositories*. The other available
repository types, *rsync*, *websync_repo* and *websync_pkglist* derive from
*BasicRepo*.
@@ -1890,7 +1885,7 @@ Adding new repository types
Adding new repository types is best done by creating a new repo class
that inherits *BasicRepo*. The table below shows *BasicRepo*'s subclass
-awareness (concerning sync) and what may be changed if required.
+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 *_dosync()*:
@@ -1949,7 +1944,7 @@ to be accessible.
---------
The *overlay* is roverlay's central data structure that represents a *portage
-overlay*. It's organized in a tree structure (overlay root, categories,
+overlay*. It is organized in a tree structure (overlay root, categories,
package directories) and implements all overlay-related functionality:
* Scan the *portage overlay* for existing ebuilds
@@ -2042,7 +2037,7 @@ overlay for them, and, if successful, adds them to the work queue.
The work queue is processed by *OverlayWorkers* that run ebuild creation
for a *PackageInfo* object and inform the *OverlayCreation* about the result
-afterwards. Overlay creation doesn't stop if an ebuild cannot be created,
+afterwards. Overlay creation keeps going if an ebuild cannot be created,
instead the event is logged. Running more than one *OverlayWorker* in parallel
is possible.
@@ -2068,7 +2063,7 @@ From the ebuild creation perspective, dependency resolution works like this:
#. Wait until all channels are *done*
-#. **Stop ebuild creation** if a channel reports that it couldn't resolve
+#. **Stop ebuild creation** if a channel reports that it could not resolve
all *required dependencies*. No ebuild can be created in that case.
#. **Successfully done** - transfer the channel results to ebuild variables
@@ -2144,7 +2139,7 @@ A non-empty *R_SUGGESTS* ebuild variable will enable the *R_suggests* USE
flag. *R_SUGGESTS* is a runtime dependency (a *Dynamic DEPEND* in *RDEPEND*).
Ebuild creation keeps going if an optional dependency cannot be resolved.
-This isn't desirable for most *dependency fields*, but extremely
+This is not desirable for most *dependency fields*, but extremely
useful for R package suggestions that often link to other repositories or
private homepages.
Such unresolvable dependencies go into the *_UNRESOLVED_PACKAGES* ebuild
@@ -2190,7 +2185,7 @@ Its mode of operation is
channel, whether successful or not.
#. Process each received *dependency environment* until all dependencies have
- been resolved or waiting doesn't make sense anymore, i.e. at least one
+ been resolved or waiting does not make sense anymore, i.e. at least one
*required* dependency could not be resolved.
* add successful resolved dependencies to the "resolved" list
@@ -2198,18 +2193,18 @@ Its mode of operation is
* any other unresolved dependency is interpreted as "channel cannot satisfy
the request", the **channel stops waiting** for remaining results.
-#. The *channel* returns the result to the ebuild creation.
+#. The *channel* returns the result to the ebuild creation:
- 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.
+ * 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.
+++++++++++++++++++++++
Dependency Rule Pools
+++++++++++++++++++++++
-The *dependency resolver* doesn't know *how* to resolve a *dependency string*.
+The *dependency resolver* does not know *how* to resolve a *dependency string*.
Instead, it searches through a list of *dependency rule pools* that may be
able to do this.
@@ -2265,7 +2260,7 @@ Channel modules
+++++++++++++++++++++
The dependency resolver puts all parts of dependency resolution together,
-*rule pools*, *listeners* and *channels*. It's main task is a loop that
+*rule pools*, *listeners* and *channels*. Its main task is a loop that
processes all queued *dependency environments* and sends the result back to
their origin (an *EbuildJob channel*).
@@ -2296,8 +2291,7 @@ Its mode of operation of operation is best described in pseudo-code:
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>
+ if <a rule pool supports TRY_OTHER and does not accept depenv's type and resolves depenv>
resolved <= True
end if
^ permalink raw reply related [flat|nested] 10+ messages in thread* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/
@ 2012-08-13 16:34 André Erdmann
0 siblings, 0 replies; 10+ messages in thread
From: André Erdmann @ 2012-08-13 16:34 UTC (permalink / raw
To: gentoo-commits
commit: 7254100883c2c25da9e154990a9e3864c8712332
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Mon Aug 13 16:34:01 2012 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Mon Aug 13 16:34:01 2012 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=72541008
usage doc: depres console and config options
---
doc/html/usage.html | 625 +++++++++++++++++++++++++++++++++++++++++++++------
doc/rst/usage.rst | 499 ++++++++++++++++++++++++++++++++++++++++-
2 files changed, 1044 insertions(+), 80 deletions(-)
diff --git a/doc/html/usage.html b/doc/html/usage.html
index 37e3c27..bc9cb85 100644
--- a/doc/html/usage.html
+++ b/doc/html/usage.html
@@ -320,67 +320,79 @@ 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="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>
+<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>
</ul>
</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>
+<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>
</ul>
</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>
+<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>
</ul>
</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>
+<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>
</ul>
</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>
+<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>
</ul>
</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>
+<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="#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>
+<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>
+</ul>
+</li>
+<li><a class="reference internal" href="#id2" id="id40">6.4 Field Definition</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>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
-<h1><a class="toc-backref" href="#id1">1 Introduction</a></h1>
+<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>
</div>
<div class="section" id="installation">
-<h1><a class="toc-backref" href="#id2">2 Installation</a></h1>
+<h1><a class="toc-backref" href="#id4">2 Installation</a></h1>
<div class="section" id="prerequisites">
-<h2><a class="toc-backref" href="#id3">2.1 Prerequisites</a></h2>
+<h2><a class="toc-backref" href="#id5">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 +437,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">2.2 via emerge (Gentoo)</a></h2>
+<h2><a class="toc-backref" href="#id6">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">2.3 Manual Installation</a></h2>
+<h2><a class="toc-backref" href="#id7">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 +477,7 @@ any config files!</p>
</div>
</div>
<div class="section" id="using-roverlay-without-installation">
-<h2><a class="toc-backref" href="#id6">2.4 Using <em>roverlay</em> without installation</a></h2>
+<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
@@ -485,9 +497,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">3 Running Roverlay</a></h1>
+<h1><a class="toc-backref" href="#id9">3 Running Roverlay</a></h1>
<div class="section" id="required-configuration-steps">
-<h2><a class="toc-backref" href="#id8">3.1 Required configuration steps</a></h2>
+<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
file in that order:</p>
@@ -532,7 +544,13 @@ see <a class="reference internal" href="#providing-a-package-mirror">Providing a
<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>
+<p>Example: LOG_LEVEL = WARNING</p>
+<div class="caution last">
+<p class="first admonition-title">Caution!</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>
+</div>
</dd>
<dt>LOG_LEVEL_CONSOLE</dt>
<dd><p class="first">This sets the console log level.</p>
@@ -549,8 +567,8 @@ have reasonable defaults if <em>roverlay</em> has been installed using <em>emerg
<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
+<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>).
Although not required, this option is <strong>recommended</strong> since ebuild
creation without dependency rules fails for most R packages.</p>
@@ -581,10 +599,13 @@ named <em>R-packages.eclass</em> should be part of your installation.</p>
</dd>
</dl>
</blockquote>
+<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>
<div class="section" id="running-it">
-<h2><a class="toc-backref" href="#id9">3.2 Running it</a></h2>
+<h2><a class="toc-backref" href="#id11">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>
@@ -690,12 +711,13 @@ is specified.</dd>
<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>
+<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>
</dl>
</div>
<div class="section" id="providing-a-package-mirror">
-<h2><a class="toc-backref" href="#id10">3.3 Providing a package mirror</a></h2>
+<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
@@ -704,7 +726,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">4 Implementation Overview</a></h1>
+<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>
<ol class="arabic simple">
@@ -757,13 +779,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">4.1 Repositories / Getting Packages</a></h2>
+<h2><a class="toc-backref" href="#id14">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">4.1.1 A word about repo config files</a></h3>
+<span id="repo-config"></span><h3><a class="toc-backref" href="#id15">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">
@@ -774,7 +796,7 @@ and where they should be stored</li>
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>
+<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>
@@ -801,7 +823,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">4.1.2 Rsync repos</a></h3>
+<span id="rsync"></span><h3><a class="toc-backref" href="#id16">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 +866,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">4.1.3 Getting packages from a repository that supports http only</a></h3>
+<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>
<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 +916,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">4.1.4 Getting packages from several remotes using http and a package list</a></h3>
+<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>
<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 +943,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">4.1.5 Using local directories</a></h3>
+<span id="local"></span><h3><a class="toc-backref" href="#id19">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 +966,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">4.2 Dependency Rules / Resolving Dependencies</a></h2>
+<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="#id19">4.2.1 Dependency types</a></h3>
+<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">
@@ -974,7 +996,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">4.2.2 Simple Dependency Rules</a></h3>
+<h3><a class="toc-backref" href="#id22">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 +1005,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">4.2.2.1 Rule Variants</a></h4>
+<h4><a class="toc-backref" href="#id23">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 +1016,7 @@ resolve them as <strong>nothing</strong>.</dd>
</dl>
</div>
<div class="section" id="rule-types">
-<h4><a class="toc-backref" href="#id22">4.2.2.2 Rule types</a></h4>
+<h4><a class="toc-backref" href="#id24">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 +1057,7 @@ as "<dev-lang/R-2.14"</li>
</dl>
</div>
<div class="section" id="rule-file-examples">
-<h4><a class="toc-backref" href="#id23">4.2.2.3 Rule File Examples</a></h4>
+<h4><a class="toc-backref" href="#id25">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 +1109,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">4.2.2.4 Rule File Syntax</a></h4>
+<span id="dependency-rule-file-syntax"></span><h4><a class="toc-backref" href="#id26">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 +1212,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">4.3 Expected Overlay Result / Structure of the generated overlay</a></h2>
+<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">
@@ -1210,26 +1232,485 @@ the <em>R-packages</em> eclass file, the result should look like:</p>
</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="#id26">5 Configuration Reference</a></h1>
+<h1><a class="toc-backref" href="#id29">6 Configuration Reference</a></h1>
<div class="section" id="dependency-rules">
-<h2><a class="toc-backref" href="#id27">5.1 Dependency Rules</a></h2>
+<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="#id28">5.2 Repositories</a></h2>
+<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="#id29">5.3 Main Config</a></h2>
+<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
+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>
+<p>Some options have value type restrictions. These <em>value types</em> are used:</p>
+<dl class="docutils">
+<dt>log_level</dt>
+<dd>Value has to be a log level. Available choise are <em>DEBUG</em>, <em>INFO</em>, <em>WARN</em>,
+<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>
+<table border="1" class="last docutils">
+<colgroup>
+<col width="59%" />
+<col width="41%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">string value</th>
+<th class="head">boolean value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>y, yes, on, 1, true, enabled</td>
+<td><em>True</em></td>
+</tr>
+<tr><td>n, no, off, 0, false, disabled</td>
+<td><em>False</em></td>
+</tr>
+<tr><td><em><any other value></em></td>
+<td><strong>not allowed</strong></td>
+</tr>
+</tbody>
+</table>
+</dd>
+</dl>
+<p>There are also some implicit <em>value types</em>:</p>
+<dl class="docutils">
+<dt>list</dt>
+<dd>This means that a option has several values that are separated by
+whitespace. Quotation marks have to be used to specify more than one
+value.</dd>
+<dt>file, dir</dt>
+<dd>A value that represents a file system location will be expanded ('~' will
+be replaced by the user's home etc.).
+Additionaly the value has to be a file (or directory) if it exists.</dd>
+<dt><empty></dt>
+<dd>Specifying empty values often leads to errors if an option has value type
+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>
+<dl class="docutils" id="distfiles">
+<dt>DISTFILES</dt>
+<dd>Alias for <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
+</dl>
<dl class="docutils" id="distfiles-root">
<dt>DISTFILES_ROOT</dt>
-<dd><></dd>
+<dd><p class="first">The root directory of per-repository package directories. Repos will create
+their package directories in this directory unless they specify another
+location (see <a class="reference internal" href="#repo-config-options">repo config options</a>).</p>
+<p class="last">This option is <strong>required</strong>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="distroot">
+<dt>DISTROOT</dt>
+<dd>Alias for <a class="reference internal" href="#distfiles-root">DISTFILES_ROOT</a>.</dd>
+</dl>
+</div>
+<div class="section" id="overlay-options">
+<h3><a class="toc-backref" href="#id34">6.3.2 overlay options</a></h3>
+<dl class="docutils" id="eclass">
+<dt>ECLASS</dt>
+<dd>Alias to <a class="reference internal" href="#overlay-eclass">OVERLAY_ECLASS</a>.</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
+for this option, but values with a slash <em>/</em> lead to errors.</p>
+<p class="last">Defaults to <em>sci-R</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="overlay-dir">
+<dt>OVERLAY_DIR</dt>
+<dd><p class="first">Sets the directory of the overlay that will be created.</p>
+<p class="last">This option is <strong>required</strong>.</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
+in all created ebuilds.
+Note that overlay creation fails if any of the specified eclass files
+cannot be imported.
+Eclass files must end with '.eclass' or have no file extension.</p>
+<p class="last">Defaults to <not set>, which means that no eclass files will be used.
+This is <strong>not useful</strong>, since created ebuilds rely on an eclass for phase
+functions like <em>src_install()</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="overlay-keep-nth-latest">
+<dt>OVERLAY_KEEP_NTH_LATEST</dt>
+<dd><p class="first">Setting this option to a value > 0 enables keeping of max. <em>value</em> ebuilds
+per R package. All others will be removed.</p>
+<p class="last">Defaults to <not set>, which disables this feature and keeps all ebuilds.</p>
+</dd>
</dl>
-<p>The main config file uses shell syntax.</p>
+<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
+<em>OVERLAY_DIR/profiles/repo_name</em>. This file will be rewritten on every
+<em>roverlay</em> run that includes the <em>create</em> command.</p>
+<p class="last">Defaults to <em>R_Overlay</em>.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="other-config-files">
+<h3><a class="toc-backref" href="#id35">6.3.3 other config files</a></h3>
+<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>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="field-definition">
+<dt>FIELD_DEFINITION</dt>
+<dd><p class="first">Path to the field definition file that controls how the <em>DESCRIPTION</em> file
+of R packages is read.</p>
+<p class="last">This option is <strong>required</strong>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="field-definition-file">
+<dt>FIELD_DEFINITION_FILE</dt>
+<dd>Alias to <a class="reference internal" href="#field-definition">FIELD_DEFINITION</a>.</dd>
+</dl>
+<dl class="docutils" id="id1">
+<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>
+</dd>
+</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>
+</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>
+</dl>
+<dl class="docutils" id="simple-rules-file">
+<dt>SIMPLE_RULES_FILE</dt>
+<dd><p class="first">A list of files and directories with dependency rules.
+Directories will be non-recursively scanned for rule files.</p>
+<p class="last">This option is <strong>not required, but recommended</strong> since <em>roverlay</em> cannot do
+much without dependency resolution.</p>
+</dd>
+</dl>
+<dl class="docutils" id="simple-rules-files">
+<dt>SIMPLE_RULES_FILES</dt>
+<dd>Alias to <a class="reference internal" href="#simple-rules-file">SIMPLE_RULES_FILE</a>.</dd>
+</dl>
+</div>
+<div class="section" id="logging">
+<h3><a class="toc-backref" href="#id36">6.3.4 logging</a></h3>
+<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>
+</dl>
+<dl class="docutils" id="log-enabled">
+<dt>LOG_ENABLED</dt>
+<dd><p class="first">Globally enable or disable logging. The value has to be a <em>bool</em>.
+Setting this option to <em>True</em> allows logging to occur, while <em>False</em>
+disables logging entirely.
+Log target such as <em>console</em> or <em>file</em> have to be enabled
+to actually get any log messages.</p>
+<p class="last">Defaults to <em>True</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-level">
+<dt>LOG_LEVEL</dt>
+<dd><p class="first">Sets the default log level. Log targets that don't have their own log
+level set will use this value.</p>
+<p class="last">Defaults to <not set> - all log targets will use their own defaults</p>
+</dd>
+</dl>
+<div class="section" id="console-logging">
+<h4><a class="toc-backref" href="#id37">6.3.4.1 console logging</a></h4>
+<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>
+<p class="last">Defaults to <em>True</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-format-console">
+<dt>LOG_FORMAT_CONSOLE</dt>
+<dd><p class="first">Sets the format for console log messages.</p>
+<p class="last">Defaults to <em>%(levelname)-8s %(name)-14s: %(message)s</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-level-console">
+<dt>LOG_LEVEL_CONSOLE</dt>
+<dd><p class="first">Sets the log level for console logging.</p>
+<p class="last">Defaults to <em>INFO</em>.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="file-logging">
+<h4><a class="toc-backref" href="#id38">6.3.4.2 file logging</a></h4>
+<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
+exist or is commented out even if <a class="reference internal" href="#log-file-enabled">LOG_FILE_ENABLED</a> is set to <em>True</em>.</p>
+<p class="last">Defaults to <not set>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-file-buffered">
+<dt>LOG_FILE_BUFFERED</dt>
+<dd><p class="first">Enable/Disable buffering of log entries in memory before they're written
+to the log file. Enabling this reduces I/O blocking, especially when using
+low log levels. The value must be a <em>bool</em>.</p>
+<p class="last">Defaults to enabled.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-file-buffer-count">
+<dt>LOG_FILE_BUFFER_COUNT</dt>
+<dd><p class="first">Sets the number of log entries to buffer at most. Can be decreased to
+lower memory consumption when using log entry buffering.</p>
+<p class="last">Defaults to <em>250</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-file-enabled">
+<dt>LOG_FILE_ENABLED</dt>
+<dd><p class="first">Enables/Disable file logging. The value has to be a bool.</p>
+<p class="last">Defaults to enabled, in which case file logging is enabled if <a class="reference internal" href="#log-file">LOG_FILE</a>
+is set, else disabled.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-file-format">
+<dt>LOG_FILE_FORMAT</dt>
+<dd><p class="first">Sets the format used for log messages written to a file.</p>
+<p class="last">Defaults to <em>%(asctime)s %(levelname)-8s %(name)-10s: %(message)s</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-file-level">
+<dt>LOG_FILE_LEVEL</dt>
+<dd><p class="first">Sets the log level for file logging.</p>
+<p class="last">Defaults to <em>WARNING</em>.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-file-rotate">
+<dt>LOG_FILE_ROTATE</dt>
+<dd><p class="first">A <em>bool</em> that enables/disables log file rotation. If enabled, the log file
+will be rotated on every script run and max. <a class="reference internal" href="#log-file-rotate-count">LOG_FILE_ROTATE_COUNT</a> log
+files will be kept.</p>
+<p class="last">Defaults to disabled.</p>
+</dd>
+</dl>
+<dl class="docutils" id="log-file-rotate-count">
+<dt>LOG_FILE_ROTATE_COUNT</dt>
+<dd><p class="first">Sets the number of log files to keep at most.</p>
+<p class="last">Defaults to <em>3</em> and has no effect if <a class="reference internal" href="#log-file-rotate">LOG_FILE_ROTATE</a> is disabled.</p>
+</dd>
+</dl>
+</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>
+<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
+written into. This can be used to analyze/backtrack overlay creation
+results.</p>
+<p class="last">Defaults to <not set>, which disables writing of description data files.</p>
+</dd>
+</dl>
+<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>
+<p class="last">Defaults to <em>ebuild</em>, which should be fine in most cases.</p>
+</dd>
+</dl>
+<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>
+<p class="last">Defaults to <not set>, which disables this feature.</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.
+This will pass '--bwlimit=<value>' to all rsync commands.</p>
+<p class="last">Defaults to <not set>, which disables bandwidth limitation.</p>
+</dd>
+</dl>
+</div>
</div>
-<div class="section" id="field-definition">
-<h2><a class="toc-backref" href="#id30">5.4 Field Definition</a></h2>
+<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>
<p>Each information field has its own section which declares a set of options
@@ -1310,9 +1791,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">6 Appendix</a></h1>
+<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="#id32">6.1 Default Field Definition File</a></h2>
+<h2><a class="toc-backref" href="#id42">7.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>
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index ebf8aa0..3099e83 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -200,6 +200,12 @@ The following options should be set before running *roverlay*:
Example: LOG_LEVEL = WARNING
+ .. caution::
+
+ Be careful with low log levels, especially *DEBUG*.
+ They produce a lot of messages that you probably don't want to see
+ and increase the size of log files dramatically.
+
LOG_LEVEL_CONSOLE
This sets the console log level.
@@ -214,8 +220,8 @@ The following options should also be set (most of them are required), but
have reasonable defaults if *roverlay* has been installed using *emerge*:
SIMPLE_RULES_FILE
- This option lists the dependency rules files that should be used
- for dependency resolution (see
+ This option lists dependency rule files and/or directories with
+ such files that should be used for dependency resolution (see
`Dependency Rules / Resolving Dependencies`_).
Although not required, this option is **recommended** since ebuild
creation without dependency rules fails for most R packages.
@@ -248,6 +254,9 @@ have reasonable defaults if *roverlay* has been installed using *emerge*:
Example: OVERLAY_ECLASS = ~/roverlay/eclass/R-packages.eclass
+There's another option that is useful if you want to create new dependency
+rules, LOG_FILE_UNRESOLVABLE_, which will write all unresolvable dependencies
+to the specified file (one dependency string per line).
For details and a full configuration reference, see `Configuration Reference`_.
@@ -350,11 +359,13 @@ sync
This will download all packages from the configured remotes.
depres_console, depres
- Starts an interactive dependency resolution console that supports rule
- creation/deletion, loading rules from files, writing rules to files
- and resolving dependencies.
+ Starts an interactive dependency resolution console that supports rule
+ creation/deletion, loading rules from files, writing rules to files
+ and resolving dependencies.
+
+ Meant for **testing only**.
- Meant for **testing only**.
+ More information can be found in the `DepRes Console`_ section.
----------------------------
Providing a package mirror
@@ -433,6 +444,8 @@ and is able to use any packages locally available. The concrete method used
to get and use the packages is determined by the concrete
**type of a repository** and that's what this section is about.
+.. _repo config:
+
++++++++++++++++++++++++++++++++
A word about repo config files
++++++++++++++++++++++++++++++++
@@ -449,6 +462,8 @@ Each repo entry section is introduced with ``[<repo name>]`` and defines
Such options are declared with ``<option> = <value>`` in the repo entry.
+.. _repo config options:
+
The common options for repository entries are:
* *type*, which declares the repository type. Available types are:
@@ -809,6 +824,9 @@ They're found in */etc/roverlay/simple-deprules.d*
if you've installed *roverlay* with *emerge*,
else in *<R Overlay src directory>/simple-deprules.d*.
+
+.. _Dependency Rule File Syntax:
+
Rule File Syntax
----------------
@@ -931,6 +949,134 @@ the *R-packages* eclass file, the result should look like:
<overlay root>/sci-R/seewave/seewave-1.6.4.ebuild
+================
+ DepRes Console
+================
+
+As previously stated, the *DepRes Console* is only meant for **testing**.
+It's an interactive console with the following features:
+
+* resolve dependencies
+* create new dependency rules (**only single line rules**)
+* create dependency rules for each R package found in a directory
+* load rules from files
+* save rules to a file
+
+Rules are managed in a set. These so-called *rule pools* are organized in
+a *first-in-first-out* data structure that allows
+to create or remove them easily at runtime.
+
+Running ``roverlay depres_console`` will print a welcome message that
+lists all available commands and a few usage hints.
+
+For reference, these commands are currently available:
+
++---------------------+----------------------------------------------------+
+| command | description |
++=====================+====================================================+
+| help, | lists all commands |
+| h | |
++---------------------+----------------------------------------------------+
+| help --list, | lists all help topics for which help is available |
+| h --list | |
++---------------------+----------------------------------------------------+
+| help *<cmd>*, | prints a command-specific help message |
+| h *<cmd>* | |
++---------------------+----------------------------------------------------+
+| load *<file|dir>*, | loads a rule file or a directory with rule files |
+| l *<file|dir>* | into a new *rule pool* |
++---------------------+----------------------------------------------------+
+| load_conf, | loads the rule files listed in the config file |
+| lc | into a new *rule pool* |
++---------------------+----------------------------------------------------+
+| addrule *<rule>* | creates a new rule and adds it to the topmost, |
+| + *<rule>* | i.e. latest *rule pool*. This command uses |
+| | `Rule File Syntax`_, but multi line rules are |
+| | not supported. |
++---------------------+----------------------------------------------------+
+| add_pool, | creates a new *rule pool* |
+| << | |
++---------------------+----------------------------------------------------+
+| unwind, | removes the topmost *rule pool* and all of its |
+| >> | rules |
++---------------------+----------------------------------------------------+
+| resolve *<dep>*, | tries to resolve the given dependency string and |
+| ? *<dep>* | prints the result |
++---------------------+----------------------------------------------------+
+| print, p | prints the rules of the topmost *rule pool* |
++---------------------+----------------------------------------------------+
+| print all, p all | prints the rules of all *rule pools* |
++---------------------+----------------------------------------------------+
+| write *<file>*, | writes the rules of the topmost *rule pool* into |
+| w *<file>* | *<file>* |
++---------------------+----------------------------------------------------+
+| cd *<dir>* | changes the working directory, also creates it if |
+| | necessary |
++---------------------+----------------------------------------------------+
+| scandir *<dir>*, | creates dependency rules for each R package found |
+| sd *<dir>* | in *<dir>* |
++---------------------+----------------------------------------------------+
+| set, unset | prints the status of currently (in)active modes |
++---------------------+----------------------------------------------------+
+| set *<mode>*, | set or unsets *<mode>*. There's only one mode to |
+| unset *<mode>* | control, the *shlex mode* which controls how |
+| | command arguments are parsed |
++---------------------+----------------------------------------------------+
+| mkhelp | verifies that each accessible command has a help |
+| | message |
++---------------------+----------------------------------------------------+
+| exit, qq, q | exit the *DepRes Console* |
++---------------------+----------------------------------------------------+
+
+
+
+Example Session:
+ .. code-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
+
+
=========================
Configuration Reference
=========================
@@ -952,12 +1098,349 @@ the *R-packages* eclass file, the result should look like:
Main Config
-------------
+The main config file uses "<option> = <value>" syntax, comment lines start
+with **#**. 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 **paths must not contain whitespace**.
+
+Some options have value type restrictions. These *value types* are used:
+
+log_level
+ Value has to be a log level. Available choise are *DEBUG*, *INFO*, *WARN*,
+ *WARNING*, *ERROR* and *CRITICAL*.
+
+bool
+ Value is a string that represents a boolean value.
+
+ This table illustrates which values strings are accepted:
+
+ +--------------------------------+----------------------+
+ | string value | boolean value |
+ +================================+======================+
+ | y, yes, on, 1, true, enabled | *True* |
+ +--------------------------------+----------------------+
+ | n, no, off, 0, false, disabled | *False* |
+ +--------------------------------+----------------------+
+ | *<any other value>* | **not allowed** |
+ +--------------------------------+----------------------+
+
+
+There are also some implicit *value types*:
+
+list
+ This means that a option has several values that are separated by
+ whitespace. Quotation marks have to be used to specify more than one
+ value.
+
+file, dir
+ A value that represents a file system location will be expanded ('~' will
+ be replaced by the user's home etc.).
+ Additionaly the value has to be a file (or directory) if it exists.
+
+<empty>
+ Specifying empty values often leads to errors if an option has value type
+ restrictions. It's better to comment out options.
+
+
+The following sections will list all config entries.
+
+++++++++++++++
+ misc options
+++++++++++++++
+
+.. _DISTFILES:
+
+DISTFILES
+ Alias for DISTFILES_ROOT_.
+
.. _DISTFILES_ROOT:
DISTFILES_ROOT
- <>
+ The root directory of per-repository package directories. Repos will create
+ their package directories in this directory unless they specify another
+ location (see `repo config options`_).
+
+ This option is **required**.
+
+.. _DISTROOT:
+
+DISTROOT
+ Alias for DISTFILES_ROOT_.
+
+
++++++++++++++++++
+ overlay options
++++++++++++++++++
+
+.. _ECLASS:
+
+ECLASS
+ Alias to OVERLAY_ECLASS_.
+
+.. _OVERLAY_CATEGORY:
+
+OVERLAY_CATEGORY
+ Sets the category of created ebuilds. There are no value type restrictions
+ for this option, but values with a slash */* lead to errors.
+
+ Defaults to *sci-R*.
+
+.. _OVERLAY_DIR:
+
+OVERLAY_DIR
+ Sets the directory of the overlay that will be created.
+
+ This option is **required**.
+
+.. _OVERLAY_ECLASS:
+
+OVERLAY_ECLASS
+ A list of eclass files that will be imported into the overlay and inherited
+ in all created ebuilds.
+ Note that overlay creation fails if any of the specified eclass files
+ cannot be imported.
+ Eclass files must end with '.eclass' or have no file extension.
+
+ Defaults to <not set>, which means that no eclass files will be used.
+ This is **not useful**, since created ebuilds rely on an eclass for phase
+ functions like *src_install()*.
+
+.. _OVERLAY_KEEP_NTH_LATEST:
+
+OVERLAY_KEEP_NTH_LATEST
+ Setting this option to a value > 0 enables keeping of max. *value* ebuilds
+ per R package. All others will be removed.
+
+ Defaults to <not set>, which disables this feature and keeps all ebuilds.
+
+.. _OVERLAY_NAME:
+
+OVERLAY_NAME
+ Sets the name of the created overlay that will be written into
+ *OVERLAY_DIR/profiles/repo_name*. This file will be rewritten on every
+ *roverlay* run that includes the *create* command.
+
+ Defaults to *R_Overlay*.
+
+++++++++++++++++++++
+ other config files
+++++++++++++++++++++
+
+Some config config options are split from the main config file for various
+reasons:
+
+* no need for modification in most cases, e.g. the `field definition`_ file
+* special syntax that is not compatible with the main config file,
+ e.g. the `dependency rule file syntax`_
+
+The paths to these files have to be listed in the main config file and
+can be overridden with the appropriate command line options.
+
+.. _FIELD_DEFINITION:
+
+FIELD_DEFINITION
+ Path to the field definition file that controls how the *DESCRIPTION* file
+ of R packages is read.
+
+ This option is **required**.
+
+.. _FIELD_DEFINITION_FILE:
+
+FIELD_DEFINITION_FILE
+ Alias to FIELD_DEFINITION_.
+
+.. _REPO_CONFIG:
+
+REPO_CONFIG
+ A list of one or more repo config files.
+
+ This option is **required**.
+
+.. _REPO_CONFIG_FILE:
+
+REPO_CONFIG_FILE
+ Alias to REPO_CONFIG_.
+
+.. _REPO_CONFIG_FILES:
+
+REPO_CONFIG_FILES
+ Alias to REPO_CONFIG_.
+
+.. _SIMPLE_RULES_FILE:
+
+SIMPLE_RULES_FILE
+ A list of files and directories with dependency rules.
+ Directories will be non-recursively scanned for rule files.
+
+ This option is **not required, but recommended** since *roverlay* cannot do
+ much without dependency resolution.
+
+.. _SIMPLE_RULES_FILES:
+
+SIMPLE_RULES_FILES
+ Alias to SIMPLE_RULES_FILE_.
+
++++++++++
+ logging
++++++++++
+
+.. _LOG_DATE_FORMAT:
+
+LOG_DATE_FORMAT
+ The date format used in log messages.
+
+ Defaults to *%F %H:%M:%S*.
+ (<<explain the date format by referencing to date(1)
+ or python's logging->? module>>)
+
+.. _LOG_ENABLED:
+
+LOG_ENABLED
+ Globally enable or disable logging. The value has to be a *bool*.
+ Setting this option to *True* allows logging to occur, while *False*
+ disables logging entirely.
+ Log target such as *console* or *file* have to be enabled
+ to actually get any log messages.
+
+ Defaults to *True*.
+
+.. _LOG_LEVEL:
+
+LOG_LEVEL
+ Sets the default log level. Log targets that don't have their own log
+ level set will use this value.
+
+ Defaults to <not set> - all log targets will use their own defaults
+
+
+console logging
+---------------
+
+.. _LOG_CONSOLE:
+
+LOG_CONSOLE
+ Enables/Disables logging to console. The value has to be a *bool*.
+
+ Defaults to *True*.
+
+.. _LOG_FORMAT_CONSOLE:
+
+LOG_FORMAT_CONSOLE
+ Sets the format for console log messages.
+
+ Defaults to *%(levelname)-8s %(name)-14s: %(message)s*.
+
+.. _LOG_LEVEL_CONSOLE:
+
+LOG_LEVEL_CONSOLE
+ Sets the log level for console logging.
+
+ Defaults to *INFO*.
+
+
+file logging
+------------
+
+.. _LOG_FILE:
+
+LOG_FILE
+ Sets the log file. File logging will be disabled if this option does not
+ exist or is commented out even if LOG_FILE_ENABLED_ is set to *True*.
+
+ Defaults to <not set>.
+
+.. _LOG_FILE_BUFFERED:
+
+LOG_FILE_BUFFERED
+ Enable/Disable buffering of log entries in memory before they're written
+ to the log file. Enabling this reduces I/O blocking, especially when using
+ low log levels. The value must be a *bool*.
+
+ Defaults to enabled.
+
+.. _LOG_FILE_BUFFER_COUNT:
+
+LOG_FILE_BUFFER_COUNT
+ Sets the number of log entries to buffer at most. Can be decreased to
+ lower memory consumption when using log entry buffering.
+
+ Defaults to *250*.
+
+.. _LOG_FILE_ENABLED:
+
+LOG_FILE_ENABLED
+ Enables/Disable file logging. The value has to be a bool.
+
+ Defaults to enabled, in which case file logging is enabled if LOG_FILE_
+ is set, else disabled.
+
+.. _LOG_FILE_FORMAT:
+
+LOG_FILE_FORMAT
+ Sets the format used for log messages written to a file.
+
+ Defaults to *%(asctime)s %(levelname)-8s %(name)-10s: %(message)s*.
+
+.. _LOG_FILE_LEVEL:
+
+LOG_FILE_LEVEL
+ Sets the log level for file logging.
+
+ Defaults to *WARNING*.
+
+.. _LOG_FILE_ROTATE:
+
+LOG_FILE_ROTATE
+ A *bool* that enables/disables log file rotation. If enabled, the log file
+ will be rotated on every script run and max. LOG_FILE_ROTATE_COUNT_ log
+ files will be kept.
+
+ Defaults to disabled.
+
+.. _LOG_FILE_ROTATE_COUNT:
+
+LOG_FILE_ROTATE_COUNT
+ Sets the number of log files to keep at most.
+
+ Defaults to *3* and has no effect if LOG_FILE_ROTATE_ is disabled.
+
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ options for debugging, manual dependency rule creation and testing
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. _DESCRIPTION_DIR:
+
+DESCRIPTION_DIR
+ A directory where all description data read from an R package will be
+ written into. This can be used to analyze/backtrack overlay creation
+ results.
+
+ Defaults to <not set>, which disables writing of description data files.
+
+.. _EBUILD_PROG:
+
+EBUILD_PROG
+ 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.
+
+ Defaults to *ebuild*, which should be fine in most cases.
+
+.. _LOG_FILE_UNRESOLVABLE:
+
+LOG_FILE_UNRESOLVABLE
+ A file where all unresolved dependency strings will be written into
+ on *roverlay* exit. Primarily useful for creating new rules.
+
+ Defaults to <not set>, which disables this feature.
+
+.. _RSYNC_BWLIMIT:
+
+RSYNC_BWLIMIT
+ Set a max. average bandwidth usage in kilobytes per second.
+ This will pass '--bwlimit=<value>' to all rsync commands.
-The main config file uses shell syntax.
+ Defaults to <not set>, which disables bandwidth limitation.
------------------
Field Definition
^ permalink raw reply related [flat|nested] 10+ messages in thread
end of thread, other threads:[~2015-01-26 17:41 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-01-26 17:41 [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/ André Erdmann
-- strict thread matches above, loose matches on Subject: below --
2014-02-21 17:36 André Erdmann
2013-09-26 22:34 André Erdmann
2013-09-23 15:30 André Erdmann
2013-09-06 11:10 André Erdmann
2013-08-29 12:36 André Erdmann
2013-08-20 7:50 André Erdmann
2013-06-05 18:11 [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
2013-06-13 16:34 ` [gentoo-commits] proj/R_overlay:master " André Erdmann
2012-08-20 14:04 André Erdmann
2012-08-13 16:34 André Erdmann
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox