From edd0452a932e4fb0e063fd3c3aff11826bca6cfe Mon Sep 17 00:00:00 2001 From: André Erdmann Date: Fri, 2 Aug 2013 16:29:39 +0200 Subject: update doc/html/usage.html --- doc/html/usage.html | 469 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 335 insertions(+), 134 deletions(-) (limited to 'doc') diff --git a/doc/html/usage.html b/doc/html/usage.html index 2dbe25f..16fbbe9 100644 --- a/doc/html/usage.html +++ b/doc/html/usage.html @@ -329,141 +329,147 @@ ul.auto-toc {

Contents

+
+

3.4   roverlay helpers

+

An installation of roverlay includes some helper programs:

+
+
roverlay-sh
+

a wrapper around /bin/sh that runs a shell or shell script in roverlay's +hook environment.

+

roverlay-related scripts can use it to automatically inherit roverlay's +config and $FUNCTIONS file:

+
+#!/usr/bin/roverlay-sh
+
+# reset DEBUG, VERBOSE, QUIET
+DEBUG=n; QUIET=n; VERBOSE=y
+
+# load the functions file (optional)
+. "${FUNCTIONS?}" || exit
+
+# script body
+true
+
+

<<TODO: maybe there's a better place for the details>>

+
+
name_is_todo--roverlay_creation_helper
+
<<TODO>> +Safely runs overlay creation <<and $$afterwards>>. +Suitable for being run as cron job.
+
+

4   Basic Implementation Overview

@@ -1792,7 +1833,7 @@ as sci-R/zoo. This rule can be written as a single word, zoo.< Each package rule consists of conditions, e.g. package name contains amd64, and actions, e.g. set KEYWORDS="-x86 amd64". The actions of a rule will only be applied if a package meets all conditions, -otherwise the rule does nothing. +otherwise the rule applies alternative actions (if defined) or does nothing. Moreover, rules can contain further rules which will only take effect if all enclosing rules match a given package.

@@ -1800,10 +1841,13 @@ enclosing rules match a given package.

As stated above, each rule has two parts, a match block that lists the rule's conditions and an action block that defines which actions and nested rules are applied to a package if the rule matches it, i.e. if all -conditions are met.

+conditions are met. A rule can also contain an alternative action block +whose actions are applied to a package if the rule does not match it.

A rule file contains zero or more package rules. -Each rule has to declare one match and one action statement at least. -The basic syntax for a rule with 1..m match and 1..n action statements is

+Each rule has to declare one match and one +[alternative] action statement at least. +The basic syntax for a rule with 1..m match, 1..n action statements and +1..k alternative action statements is

 MATCH:
    <match statement 1>
@@ -1815,13 +1859,20 @@ ACTION:
    <action statement 2>
    ...
    <action statement n>
+ELSE:
+   <alternative action statement 1>
+   <alternative action statement 2>
+   ...
+   <alternative action statement k>
 END;

A rule is introduced by the MATCH: keyword, which starts the match block and is followed by one or more match statements, one per line. The match block ends with the ACTION: keyword, which also starts the action block and is followed by one or more action statements -(again, one per line). Finally, the rule is terminated by the END; keyword.

+(again, one per line). The alternative action block introduced by the +ELSE: keyword is optional and lists action statements. +Finally, the rule is terminated by the END; keyword.

Indention is purely optional, leading and ending whitespace will be discarded. Lines starting with # or ; are considered to be comments and will be ignored.

@@ -2119,6 +2170,15 @@ statements rename_<key> 1 +null +n/a +none +does nothing +(can be used for +readability) + +pass +

The two-arg form of the set/rename keywords expect a <key> as first and @@ -2190,6 +2250,19 @@ ACTION: END; # top-level rule, action block continues ... +ELSE: + # top-level rule, alternative action block + ... + MATCH: + # (alternative) nested rule, match block + ... + ACTION: + # (alternative) nested rule, action block + ... + ELSE: + # (alternative) nested rule, alternative action block + ... + END; END;

Rules can be nested indefinitely, whitespace indention is optional. @@ -2201,13 +2274,19 @@ checks necessary for a given package.

8.1.3   Package Rule Examples

A rule that ignores the 'yaqcaffy' package from CRAN, which is also available -from BIOC:

+from BIOC. Additionally, it sets the category for all non-ignored packages +from CRAN to sci-CRAN:

 MATCH:
-   repo         == CRAN
-   package_name == yaqcaffy
+   repo CRAN
 ACTION:
-   do-not-process
+   MATCH:
+      package_name == yaqcaffy
+   ACTION:
+      do-not-process
+   ELSE:
+      set category sci-CRAN
+   END;
 END;

A more complex example that sets the KEYWORDS ebuild variable for @@ -2219,11 +2298,12 @@ MATCH: * package_name ~ x86_64 * package_name ~ amd64 ACTION: - keywords "-x86 amd64" MATCH: repo == BIOC/experiment ACTION: keywords "-x86 ~amd64" + ELSE: + keywords "-x86 amd64" END; END; @@ -2258,6 +2338,13 @@ ACTION: rename_destfile s=^=R-package/= END; +

+

Hint

+

roverlay [--nosync] [--dump-file <file>] apply_rules can be used to +test rules. It applies the rules to all packages without running overlay +creation. Furthermore, roverlay --ppr parses the package rules, +prints them and exits afterwards.

+
@@ -2389,16 +2476,30 @@ the config file. An empty string sets the policy to deny all.

event event that caused the script to run +HAS_CHANGES +internal +a shbool (y or n) that +indicates whether the overlay has +any changes + +OVERLAY_NAME +config +name of the overlay + OVERLAY config -overlay directory (OVERLAY_DIR), -initial working directory +overlay directory (OVERLAY_DIR), S $OVERLAY PWD -$OVERLAY +$OVERLAY +$ROVERLAY_PHASE +

initial working directory

+

depends on $ROVERLAY_PHASE (usually set +to $OVERLAY or left unchanged)

+ DISTROOT config @@ -2421,6 +2522,11 @@ initial working directory FILESDIR $ADDITIONS_DIR +WORKDIR +config +directory for work data +(CACHEDIR) + SHLIB $ADDITIONS_DIR, installed? @@ -2434,6 +2540,30 @@ function files file with essential shell functions (optional, only set if it exists) +DATADIR +installed? +location of installed data files +(directory, usually +/usr/share/roverlay) + +ROVERLAY_HELPER_EXE +sys.argv +path to the roverlay executable that +created the hook environment +(usually /usr/bin/roverlay or +/usr/bin/roverlay-sh) + +ROVERLAY_EXE +guessed, +$ROVERLAY_HELPER_EXE +guessed path to the roverlay "main" +executable (which creates the overlay) + +STATS_DB +config +stats database file +(optional, only set if configured) + DEBUG log level shbool (y or n) that @@ -2628,8 +2758,39 @@ They should, however, not execute any code directly.

Shell function files should be put into <ADDITIONS_DIR>/shlib.

+
+

9.5   Hook event table

+

The following table lists all known events (ROVERLAY_PHASE):

+ +++++ + + + + + + + + + + + + + + + + + + + + +
nameinitial working directorydescription
overlay_success$OVERLAYoverlay creation succeeded
db_written$OVERLAYstats database file written
userunchangeduser-triggered event
+
-

9.5   Adding a hook event

+

9.6   Adding a hook event

Adding a new event has to be done in roverlay's source code and is a rather trivial task. The roverlay.hook module implements a function for running the event script:

@@ -2940,6 +3101,13 @@ writing.

+
+
OVERLAY_MASTERS
+

A list of repo names that are used as 'masters' attribute when generating +<overlay>/metadata/layout.conf.

+

Defaults to "gentoo".

+
+
OVERLAY_NAME

Sets the name of the created overlay that will be written into @@ -3277,9 +3445,9 @@ as flag.

joinValues
Declares that a field's value is one string even if it spans over -multiple lines. -The lines will be joined with a single space character ' '. -The default behavior is to merge lines.
+multiple lines. The lines will be joined with a single space +character ' '. The default behavior is to merge lines. +This flag can be used in conjunction with any "is list" flag.
isList
@@ -3350,17 +3518,31 @@ such a field is found. [OS_Type] alias_nocase = OS_TYPE allowed_values = unix + +[License] +alias_nocase = License, Licence, Lisence +isLicense +
+

12   Roverlay Console

+

<<section is TODO>>

+

<<links to depres console chapter may need to be fixed>>

+

<<basic commands, table>>

+

<<note regarding python -OO and missing help texts>>

-

12   Dependency Resolution Console

+

12.1   Dependency Resolution Console

+
+

Warning

+

This section is out-of-date.

+

As previously stated, the DepRes Console is only meant for testing. It is an interactive console with the following features:

  • resolve dependencies
    • -
  • create new dependency rules (only single line rules)
    • +
  • create new dependency rules
  • create dependency rules for each R package found in a directory
  • load rules from files
  • save rules to a file
    • @@ -3371,6 +3553,7 @@ 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:

    +

    <<TODO: rewrite/update command table, it's out-of-date>>

    @@ -3383,13 +3566,9 @@ lists all available commands and a few usage hints.

    +h, ? - - - @@ -3404,65 +3583,78 @@ lc - +Rule File Syntax. Multi line rules are +supported. - +?? <dep> + + + + + + - + + + + +<file>. See write --help for advanced usage. - + + + + - - + + - - + + - - + + - - + +
    help, -h lists all commands
    help --list, -h --listlists all help topics for which help is available
    help <cmd>, h <cmd> prints a command-specific help message loads the rule files listed in the config file into a new rule pool
    addrule <rule> +
    add_rule <rule> + <rule> creates a new rule and adds it to the topmost, 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, +
    unwind_pool, >> removes the topmost rule pool and all of its rules
    resolve <dep>, -? <dep> tries to resolve the given dependency string and prints the result
    !enter the resolve command chroot +all input will be prefixed with "resolve"
    !!leave any command chroot
    print, p prints the rules of the topmost rule pool
    print all, p all
    print --all|-a prints the rules of all rule pools
    print <id> [<id>..]prints the rules of a specific rule pool
    write <file>, w <file> writes the rules of the topmost rule pool into -<file>
    cd <dir>changes the working directory, also creates it if -necessarychanges the working directory +This is a virtual command. <<TODO:EXPLAIN>>
    set VAR=VALUEset variables
    scandir <dir>, -sd <dir>creates dependency rules for each R package found -in <dir>
    unset VARunset variables
    set, unsetprints the status of currently (in)active modes
    declareshow declared variables
    set <mode>, -unset <mode>sets or unsets <mode>. There is only one mode to -control, the shlex mode which controls how -command arguments are parsed
    aliasshow command aliases
    mkhelpverifies that each accessible command has a help -message
    unaliasreserved for future usage
    exit, qq, q exits the DepRes Console
    +
    +

    Note

    +

    Some commands also offer more detailed help via <command> --help.

    +
    +

    <<TODO>>

    +

    <<Example Session is out-of-date>>

    Example Session:
    @@ -3512,6 +3704,7 @@ cmd % exit
+

13   Roverlay Interface

Roverlay provides an API for accessing its functionality independently of @@ -3547,6 +3740,10 @@ initialization roverlay.interface.depres dependency resolution +RemoteInterface +roverlay.interface.remote +remote interaction (sync) +

For extending the API, roverlay provides the abstract RoverlayInterface and @@ -3572,9 +3769,13 @@ and cannot_resolve() also possible

Refer to in-code documentation on how to use this interface. -See the dependency resolution test suite for a usage example -(tests.depres, not part of the roverlay installation). -(The depres console is also a candidate for using this interface in future.)

+See the dependency resolution test suite (tests.depres, not part of the +roverlay installation) and the dependency resolution console +for usage examples.

+
+
+

13.2   Remote Interface

+

<<TODO; this interface isn't mature enough yet (it will likely change in future)>>

@@ -4114,7 +4315,7 @@ becomes "loop until resolver closes".

-Generated on: 2013-07-23. +Generated on: 2013-08-02.
-- cgit v1.2.3-65-gdbad