From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id 0886C138010 for ; Mon, 20 Aug 2012 14:06:01 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 8F67321C021; Mon, 20 Aug 2012 14:04:53 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by pigeon.gentoo.org (Postfix) with ESMTP id 1C91B21C021 for ; Mon, 20 Aug 2012 14:04:52 +0000 (UTC) Received: from hornbill.gentoo.org (hornbill.gentoo.org [94.100.119.163]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 3BC951B41E1 for ; Mon, 20 Aug 2012 14:04:52 +0000 (UTC) Received: from localhost.localdomain (localhost [127.0.0.1]) by hornbill.gentoo.org (Postfix) with ESMTP id 0482BE543D for ; Mon, 20 Aug 2012 14:04:50 +0000 (UTC) From: "André Erdmann" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "André Erdmann" Message-ID: <1345470960.149ebf6b03f7df5d341f350ecdc1a00712467d79.dywi@gentoo> Subject: [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/ X-VCS-Repository: proj/R_overlay X-VCS-Files: doc/html/usage.html doc/rst/usage.rst X-VCS-Directories: doc/rst/ doc/html/ X-VCS-Committer: dywi X-VCS-Committer-Name: André Erdmann X-VCS-Revision: 149ebf6b03f7df5d341f350ecdc1a00712467d79 X-VCS-Branch: master Date: Mon, 20 Aug 2012 14:04:50 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: c7f17532-869a-4e75-a7ae-ec3839075595 X-Archives-Hash: c8baa835c91f61df031bb6cf1870fa53 commit: 149ebf6b03f7df5d341f350ecdc1a00712467d79 Author: André Erdmann mailerd de> AuthorDate: Mon Aug 20 13:56:00 2012 +0000 Commit: André Erdmann mailerd 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 install.packages() in R.

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

@@ -445,7 +445,7 @@ e.g. configure which R packages will be part of the generated overlay

Depending on what you want to configure, chapters 5-8 are relevant, 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.

@@ -456,8 +456,13 @@ 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
    • +
+

2   Installation

@@ -512,9 +517,8 @@ all necessary config files into /etc/roverlay.

2.3   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:

 git clone git://git.overlays.gentoo.org/proj/R_overlay.git
 
@@ -540,8 +544,8 @@ The make targets take care of this.

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!

@@ -569,20 +573,20 @@ as the R Overlay src directory from now on.

3.1   Required configuration steps

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, 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:

@@ -610,14 +614,14 @@ see Providing a
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
@@ -665,22 +669,21 @@ named R-packages.eclass should be part of your installation.

-

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).

3.1.1   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 rotation and assistance for writing new dependency rules.
@@ -693,8 +696,8 @@ a typo) to be understood as 'Depends'.

3.2   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

 roverlay --config <config file> [<options>] [<commands>]
@@ -703,13 +706,12 @@ roverlay --config <config file> [<options>] [<commands>]
 
 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:

 @@ -718,7 +720,7 @@ in detail what roverlay does before running it.

-
+
@@ -726,11 +728,10 @@ in detail what roverlay does before running it.

-

 

 

 --nosync, --no-sync
 
 Don't download R packages.
 Disable downloading of R packages.

 

 --no-incremental
 

 

 --immediate-ebuild-writes
 
 
Immediately write ebuilds when they're 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.
+
 
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.
 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 ???>>.

@@ -748,8 +749,8 @@ the default package repositories.

 

 

 
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.

 

 
For testing roverlay, these options may be convenient:

@@ -766,7 +767,7 @@ 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
@@ -877,8 +878,8 @@ and may decide to write p's ebuild now (or later)

4.2   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:

 <overlay root>/
 <overlay root>/eclass
@@ -917,7 +918,7 @@ RDEPEND="${DEPEND:-}
 
 _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:

 <ebuild header>
@@ -1030,8 +1031,8 @@ if a package has more than one, e.g. one in its Title and one in its
 
5   Repositories / Getting Packages

 
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.

 

 
5.1   A word about repo config files

 
Repo config files use ConfigParser syntax (known from ini files).

@@ -1116,10 +1117,10 @@ Options with whitespace are not supported.
 

 

 
5.3   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):

 
@@ -1202,15 +1203,15 @@ file would be:

 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.
@@ -1230,7 +1231,7 @@ dictionary entry.

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 resolve them as nothing.
@@ -1270,7 +1271,7 @@ it will resolve any of these dependency strings:

  • "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 )"
    • @@ -1331,9 +1332,8 @@ in some R package DESCRIPTION files.

    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.

    6.1.4   Rule File Syntax

    @@ -1361,7 +1361,7 @@ simple rule.

    defines that all rules until the next deptype directory or end of file, 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)
      • @@ -1418,7 +1418,7 @@ Their rule block begins with '{' + newline, followed by one

      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.

      @@ -1454,10 +1454,9 @@ the written one.

    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:
    @@ -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.
    <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.

    7.1   misc options

    DISTFILES
    -
    Alias for DISTFILES_ROOT.
    +
    Alias to DISTFILES_ROOT.
    DISTFILES_ROOT
    @@ -1539,7 +1538,22 @@ location (see repo con
    DISTROOT
    -
    Alias for DISTFILES_ROOT.
    +
    Alias to DISTFILES_ROOT.
    +
    +
    +
    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
    +

    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.

    +
    @@ -1658,8 +1672,8 @@ to actually get any log messages.

    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

    @@ -1695,7 +1709,7 @@ exist or is commented out even if
    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.

    Defaults to enabled.

    @@ -1753,14 +1767,6 @@ results.

    Defaults to <not set>, which disables writing of description data files.

    -
    -
    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

    A file where all unresolved dependency strings will be written into @@ -1768,13 +1774,6 @@ on roverlay exit. Primarily useful for creating new rules.

    Defaults to <not set>, which disables this feature.

    -
    -
    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.

    -
    -
    @@ -1783,9 +1782,9 @@ This will pass '--bwlimit=<value>' to all rsync commands.

    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.

    -

    Known field options:

    +

    Available field options:

    default_value
    @@ -1857,7 +1856,7 @@ such a field is found.

    Note

    -

    It won't be checked whether a flag is known or not.

    +

    It is not checked whether a flag is known or not.

    8.1   Example: The default field definition file

    @@ -1898,7 +1897,7 @@ such a field is found.

    9   Dependency Resolution Console

    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)
      • @@ -1991,7 +1990,7 @@ in <dir> set <mode>, unset <mode> -sets or unsets <mode>. There's only one mode to +sets or unsets <mode>. There is only one mode to control, the shlex mode which controls how command arguments are parsed @@ -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 @@ -2076,7 +2075,7 @@ with the package file.

      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.

    @@ -2129,14 +2128,14 @@ 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.

    10.2.1.1   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():

    @@ -2222,7 +2221,7 @@ to be accessible.

    10.3   Overlay

    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

      @@ -2303,7 +2302,7 @@ It accepts PackageInfo objects as input, tries to reserve a slot in the 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.

    @@ -2323,7 +2322,7 @@ R_SUGGESTS).

  • Collect the dependency strings from the DESCRIPTION data and add them to the communication channels (up to 3 will be used)
  • 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
    • @@ -2407,7 +2406,7 @@ This section describes which dependency fields are used and how.

    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 @@ -2446,7 +2445,7 @@ strings have been added.

    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
      • @@ -2455,16 +2454,18 @@ been resolved or waiting doesn't make sense anymore, i.e. at least one the request", the channel stops waiting for remaining results.
    • -

  • 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.

    +

  • The channel returns the result to the ebuild creation:

    +
      +
    • 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.
      • +

    • 10.6.4   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.

    A dependency rule pool combines a list of dependency rules with a @@ -2508,7 +2509,7 @@ resolution, wait for results, and send them to the other end.

    10.6.6   Dependency Resolver

    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).

    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. */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 '