* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-06-05 18:08 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-06-05 18:08 UTC (permalink / raw
To: gentoo-commits
commit: c73dd7909d2969d35451bd0945be545ddf0a155b
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jun 5 18:05:14 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jun 5 18:05:14 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=c73dd790
doc/rst, package rules: set/rename actions
---
doc/rst/usage.rst | 110 +++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 100 insertions(+), 10 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 34ce7ac..e74c091 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -405,6 +405,10 @@ to know in detail what *roverlay* does before running it.
Summary: Expect 300 (slow) or 600MB (fast) memory consumption when using
the default package repositories.
+--fixup-category-move, --fixup-category-move-reverse
+ Remove ebuilds that have been moved to a different category.
+ See `Action Blocks`_ in `Package Rules`_ for details.
+
--config file, -c file
Path to the config file
@@ -1223,6 +1227,7 @@ Rule Stubs
[<keychar>]<short dependency>
+
===============
Package Rules
===============
@@ -1315,7 +1320,12 @@ These *match keywords* are recognized:
| package_name | *implicit* | package file name without version |
| | | and file extension, e.g. *seewave* |
+---------------+------------------+--------------------------------------+
- | name | *implicit* | *alias to package_name* |
+ | ebuild_name | *implicit* | ebuild name ``${PN}``, which is the |
+ | | | package_name with special chars |
+ | | | removed or replaced (e.g., |
+ | | | *R.oo* (pkg) => *R_oo* (ebuild)) |
+ +---------------+------------------+--------------------------------------+
+ | name | *implicit* | *alias to ebuild_name* |
+---------------+------------------+--------------------------------------+
Note the **implicit operator**. It will be used whenever no explicit operator
@@ -1478,21 +1488,60 @@ control *where*) and the number of values they accept:
| keywords | ebuild variables | >= 1 | set per-package |
| | | | ``KEYWORDS`` |
+----------------+------------------+-------------+------------------------+
- | trace | package rules | none | marks a package as |
+ | trace | package rules | none | mark a package as |
| | | | modified |
+ + +-------------+------------------------+
- | | | 1 | adds the stored string |
+ | | | 1 | add the stored string |
| | | | to a package's |
| | | | *modified* variable |
| | | | whenever this action |
| | | | is applied |
+----------------+------------------+-------------+------------------------+
+ | set | package | 2 | set package |
+ +----------------+ metadata, +-------------+ information |
+ | set_<key> | overlay creaton | 1 | |
+ +----------------+------------------+-------------+------------------------+
+ | rename | package | 2 | modify package |
+ +----------------+ metadata, +-------------+ information with |
+ | rename_<key> | overlay creation | 1 | sed-like |
+ | | | | *s/expr/repl/* |
+ | | | | statements |
+ +----------------+------------------+-------------+------------------------+
+
+The two-arg form of the set/rename keywords expect a <key> as first and
+a value / sed expression as second arg. The one-arg form expects the latter
+one only. The "/" delimitier in the sed expression can be any character.
+The following *info keys* can be set and/or modified:
+
+.. table:: info keys for set/rename
+
+ +--------------+---------------------+-------------------------------------+
+ | info key | supports set/rename | description |
+ +==============+=====================+=====================================+
+ | name | yes / yes | rename the ebuild |
+ +--------------+---------------------+-------------------------------------+
+ | category | yes / **no** | set package category |
+ +--------------+---------------------+-------------------------------------+
+ | destfile | yes / yes | rename ebuild destfile by using the |
+ | | | '->' operator in ``${SRC_URI}`` |
+ +--------------+---------------------+-------------------------------------+
+
+.. Caution::
+
+ Category moves are not handled automatically. In incremental mode, overlay
+ creation has to be called with either ``--fixup-category-move`` or
+ ``--fixup-category-move-reverse``, depending on whether the package(s)
+ have been moved away from the default category or back to the default
+ category ("reverse"). Configuring both category move types at once requires
+ a full recreation of the overlay, that is ``rm -rf <overlay dir>``
+ followed by ``roverlay create``.
.. Note::
- Applying the same (non-incremental) ebuild variable action more than once
- is possible, but only the last one will have an effect on ebuild creation.
+ Applying the same (non-incremental) ebuild variable, set or rename action
+ more than once is possible, but only the last one will have an effect
+ on ebuild creation.
Extended Action Block Syntax
@@ -1562,6 +1611,46 @@ if the package is from BIOC/experiment, and otherwise to ``-x86 amd64``:
END;
+A rule that assigns all packages from BIOC-2.10/bioc to sci-bioc:
+
+.. code::
+
+ MATCH:
+ repo == BIOC-2.10/bioc
+ ACTION:
+ set category sci-bioc
+ END;
+
+ # alternatively:
+ MATCH:
+ repo == BIOC-2.10/bioc
+ ACTION:
+ set_category sci-bioc
+ END;
+
+
+The following example prefixes all *yaml* packages with *Rpkg_*:
+
+.. code::
+
+ MATCH:
+ ebuild_name ,= yaml
+ ACTION:
+ rename destfile s/^/Rpkg_/
+ END;
+
+
+Moving such packages to a "R-package" sub directory would be possible, too:
+
+.. code::
+
+ MATCH:
+ name ,= yaml
+ ACTION:
+ rename_destfile s=^=R-package=
+ END;
+
+
=========================
Configuration Reference
=========================
@@ -1639,8 +1728,9 @@ DISTROOT
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.
+ Manifest file creation. A wrong value will cause ebuild creation to fail
+ late, which is a huge time loss, so make sure that this option is properly
+ set.
Defaults to *ebuild*, which should be fine in most cases.
@@ -2340,9 +2430,9 @@ functionality:
* *sync* all repos and *nosync* all repos (offline mode)
* create *PackageInfo* instances for R packages from all repositories
-++++++++++++++
- Repositories
-++++++++++++++
+++++++++++++
+ Repository
+++++++++++++
The functionality described above is an abstraction layer that calls the
respective function for each repository and collects the result.
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-06-12 21:10 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-06-12 21:10 UTC (permalink / raw
To: gentoo-commits
commit: b882ecc22d31458fc64949fd458931ec79a88456
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jun 12 21:09:03 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jun 12 21:09:03 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=b882ecc2
doc/rst: additions dir
---
doc/rst/usage.rst | 132 +++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 120 insertions(+), 12 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index adf26da..ab2c563 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -52,19 +52,20 @@ This document is targeted at
* *roverlay* maintainers who **control and test overlay creation**,
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`_.
+ Depending on what you want to configure, chapters 5-10 are relevant,
+ namely `Repositories / Getting Packages`_, `Additions Directory`,
+ `Dependency Rules`_, `Package Rules`_, `Configuration Reference`_
+ and `Field Definition Config`_.
There is another chapter that is only interesting for testing, the
- `Dependency Resolution Console`_ (10), which can be used to interactively
+ `Dependency Resolution Console`_ (11), which can be used to interactively
test dependency rules.
* *roverlay* code maintainers who want to know **how roverlay works** for
code improvements etc.
- The most important chapter is `Implementation Overview`_ (11) which has
- references to other chapters (4-9) where required.
+ The most important chapter is `Implementation Overview`_ (12) which has
+ references to other chapters (4-10) where required.
Expected prior knowlegde:
@@ -279,13 +280,19 @@ have reasonable defaults if *roverlay* has been installed using *emerge*:
Example: REPO_CONFIG = ~/roverlay/config/repo.list
- PACKAGE_RULES:
+ PACKAGE_RULES
A list of files and/or directories with package rules.
Package rules can be used to control overlay/ebuild creation.
This option is not required.
Example: PACKAGE_RULES = ~/roverlay/config/packagerules.d
+ ADDITIONS_DIR
+ Directory with an overlay-like structure that contains extra files, e.g.
+ ebuild patches and hand-written ebuilds.
+
+ Example: ADDITIONS_DIR = ~/roverlay/additions
+
FIELD_DEFINITION
The value of this option should point to a field definition file which
controls how an R package's DESCRIPTION file is read.
@@ -330,6 +337,7 @@ 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?
+++++++++++++++++++++++++++++++++++++++++++++++++
@@ -510,7 +518,9 @@ These are the steps that *roverlay* performs:
2. scan the R Overlay directory (if it exists) for valid ebuilds
-3. **add** - queue all R packages for ebuild creation
+3. import ebuilds from the additions dir
+
+4. **add** - queue all R packages for ebuild creation
* all repositories are asked to list their packages which are then added
to a queue
@@ -522,7 +532,7 @@ These are the steps that *roverlay* performs:
See also: `Package Rules`_
-4. **create** - process each package *p* from the package queue
+5. **create** - process each package *p* from the package queue
(thread-able on a per package basis)
* read *p*'s DESCRIPTION file that contains information fields
@@ -545,9 +555,9 @@ These are the steps that *roverlay* performs:
* **done** with *p* - the overlay creator takes control over *p*
and may decide to write *p*'s ebuild now (or later)
-5. write the overlay
+6. write the overlay
- * write all ebuilds
+ * write all ebuilds and apply patches to them
(supports threads on a per package basis)
* write the *metadata.xml* files
@@ -957,6 +967,91 @@ A local directory will never be modified.
websync_pkglist_.
+=====================
+ Additions Directory
+=====================
+
+The *additions directory* is a directory with overlay-like structure that
+contains extra files for overlay creation. Currently, ebuild patches and
+ebuild files are supported.
+
+To give an idea of how this directory could
+
+
+
+------------------
+ Patching ebuilds
+------------------
+
+Patches can apply to a **specific version** or to **all versions** of a
+package.
+
+The naming convention for patches is (full filesystem paths relative to the
+additions dir):
+
+.. code:: text
+
+ # version-specific patches
+ ${CATEGORY}/${PN}/${PF}[-dddd].patch
+
+ # version-agnostic patches
+ ${CATEGORY}/${PN}/${PN}[-dddd].patch
+
+
+The *-dddd* part is optional and can be used to apply more than one patch to
+an ebuild in the specified order. *d* should be a digit (0..9) and exactly
+4 digits are expected. The not-numbered patch is always applied first.
+So, in theory, up to 10001 patches per ebuild are supported.
+
+The *default* (version-agnostic) patches are only applied to ebuilds for
+which no version-specific patches exist.
+
+Exempting a specific ebuild from being patched can be achieved by creating
+an empty patch file (or a symlink to /dev/null). This is only necessary
+if *default* patches are available, else it adds some overhead.
+
+.. Caution::
+
+ Don't try to patch the (R)DEPEND variables of an ebuild.
+ It will *randomly* break because *roverlay* uses unordered data structures
+ for collecting dependencies.
+
+Example:
+
+.. code:: text
+
+ <additions dir>/sci-CRAN/R_oo/R_oo-1.9.8.patch
+ <additions dir>/sci-CRAN/R_oo/R_oo-1.9.8-0000.patch
+ <additions dir>/sci-CRAN/R_oo/R_oo-1.9.8-0001.patch
+ <additions dir>/sci-R/seewave/seewave-1.6.7.patch
+ <additions dir>/sci-R/seewave/seewave.patch
+
+
+-------------------
+ Importing ebuilds
+-------------------
+
+Foreign ebuilds can be imported into the overlay by simple putting them into
+the additions directory.
+
+The naming convention is similar to ebuild patches and identical to the
+portage tree:
+
+.. code::
+
+ ${CATEGORY}/${PN}/${PF}.ebuild
+
+
+Ebuilds imported that way can not be overwritten by generated ebuilds and
+benefit from most overlay creation features, e.g. Manifest file creation.
+However, they cannot be used for metadata creation.
+
+.. Important::
+
+ Importing ebuilds is only supported by the default Manifest implementation
+ (*ebuildmanifest*).
+
+
==================
Dependency Rules
==================
@@ -1747,6 +1842,11 @@ RSYNC_BWLIMIT
overlay options
-----------------
+.. _ADDITIONS_DIR:
+
+ADDITIONS_DIR:
+ Alias to OVERLAY_ADDITIONS_DIR_.
+
.. _DISTDIR:
DISTDIR
@@ -1772,6 +1872,14 @@ ECLASS
MANIFEST_IMPLEMENTATION
Alias to OVERLAY_MANIFEST_IMPLEMENTATION_.
+.. _OVERLAY_ADDITIONS_DIR:
+
+OVERLAY_ADDITIONS_DIR
+ Directory with an overlay-like structure that contains extra files, e.g.
+ ebuild patches and hand-written ebuilds. This option is not required.
+
+ Defaults to <not set>, which disables this feature.
+
.. _OVERLAY_CATEGORY:
OVERLAY_CATEGORY
@@ -1790,7 +1898,7 @@ OVERLAY_DIR
.. _OVERLAY_DISTDIR_FLAT:
OVERLAY_DISTDIR_FLAT
- A *bool* that controls the overall layout of _OVERLAY_DISTDIR_ROOT.
+ A *bool* that controls the overall layout of OVERLAY_DISTDIR_ROOT_.
A flat distdir is a single directory with all package files or package
file links in it. A nested distdir contains per-package directories.
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-06-18 14:12 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-06-18 14:12 UTC (permalink / raw
To: gentoo-commits
commit: 846a4c66dabd31bbb4b9c2e17394ad53cc086d3d
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Jun 18 12:54:18 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Jun 18 12:54:18 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=846a4c66
doc/rst: r_suggests USE_EXPAND variable
---
doc/rst/usage.rst | 190 +++++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 161 insertions(+), 29 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index ab2c563..8d06bab 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -302,6 +302,18 @@ have reasonable defaults if *roverlay* has been installed using *emerge*:
Example: FIELD_DEFINITION = ~/roverlay/config/description_fields.conf
+ USE_EXPAND_DESC
+ A file that contains USE_EXPAND flag descriptions. This option is not
+ required.
+
+ Example: USE_EXPAND_DESC = ~/roverlay/config/useflag/useflag_desc
+
+ USE_EXPAND_RENAME
+ The value of this option should point to a USE flag remap file which
+ can be used to rename USE_EXPAND flags. This option is not required.
+
+ Example: USE_EXPAND_RENAME = ~/roverlay/config/useflag_rename
+
OVERLAY_ECLASS
This option lists eclass files that should be imported into the overlay
(into *OVERLAY_DIR*/eclass/) and inherited in all ebuilds.
@@ -557,6 +569,10 @@ These are the steps that *roverlay* performs:
6. write the overlay
+ * write/update the profiles dir
+
+ * *roverlay* respects manual changes to USE_EXPAND description files
+
* write all ebuilds and apply patches to them
(supports threads on a per package basis)
@@ -588,6 +604,8 @@ eclass file are used, the result should look like:
<overlay root>/profiles/categories
<overlay root>/profiles/repo_name
<overlay root>/profiles/use.desc
+ <overlay root>/profiles/desc
+ <overlay root>/profiles/desc/r_suggests.desc
<overlay root>/sci-R/<many directories per R package>
<overlay root>/sci-R/seewave/
<overlay root>/sci-R/seewave/Manifest
@@ -604,19 +622,22 @@ Ebuild Template
.. code-block:: text
<ebuild header>
+
+ EAPI=<EAPI>
+
inherit <eclass(es)>
DESCRIPTION="<the R package's description>"
SRC_URI="<src uri for the R package>"
- IUSE="${IUSE:-}
- R_suggests
+ IUSE="${IUSE-}
+ r_suggests_<flag> r_suggests_<another flag> ...
"
- R_SUGGESTS="<R package suggestions>"
+ R_SUGGESTS="r_suggests_<flag>? ( <optional dependency> ) ..."
DEPEND="<build time dependencies for the R package>"
- RDEPEND="${DEPEND:-}
+ RDEPEND="${DEPEND-}
<runtime dependencies>
- R_suggests? ( ${R_SUGGESTS} )
+ ${R_SUGGESTS-}
"
_UNRESOLVED_PACKAGES=(<unresolvable, but optional dependencies>)
@@ -628,6 +649,9 @@ Ebuild Template
.. code-block:: text
<ebuild header>
+
+ EAPI=<EAPI>
+
inherit <eclass(es)>
SRC_URI="<src uri for the R package>"
@@ -638,7 +662,7 @@ Example: seewave 1.6.4 from CRAN:
.. code-block:: sh
- # Copyright 1999-2012 Gentoo Foundation
+ # Copyright 1999-2013 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
@@ -648,11 +672,13 @@ Example: seewave 1.6.4 from CRAN:
DESCRIPTION="Time wave analysis and graphical representation"
SRC_URI="http://cran.r-project.org/src/contrib/seewave_1.6.4.tar.gz"
- IUSE="${IUSE:-}
- R_suggests
+ IUSE="${IUSE-}
+ r_suggests_sound
+ r_suggests_audio
"
- R_SUGGESTS="sci-R/sound
- sci-R/audio
+ R_SUGGESTS="
+ r_suggests_sound? ( sci-R/sound )
+ r_suggests_audio? ( sci-R/audio )
"
DEPEND="sci-R/fftw
sci-R/tuneR
@@ -660,11 +686,11 @@ Example: seewave 1.6.4 from CRAN:
sci-R/rpanel
sci-R/rgl
"
- RDEPEND="${DEPEND:-}
+ RDEPEND="${DEPEND-}
media-libs/flac
sci-libs/fftw
media-libs/libsndfile
- R_suggests? ( ${R_SUGGESTS} )
+ ${R_SUGGESTS-}
"
Example: MetaPCA 0.1.3 from CRAN's archive:
@@ -673,7 +699,7 @@ Example: MetaPCA 0.1.3 from CRAN's archive:
.. code-block:: sh
- # Copyright 1999-2012 Gentoo Foundation
+ # Copyright 1999-2013 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
@@ -683,21 +709,29 @@ Example: MetaPCA 0.1.3 from CRAN's archive:
DESCRIPTION="MetaPCA: Meta-analysis in the Di... (see metadata)"
SRC_URI="http://cran.r-project.org/src/contrib/Archive/MetaPCA/MetaPCA_0.1.3.tar.gz"
- IUSE="${IUSE:-}
- R_suggests
+ IUSE="${IUSE-}
+ r_suggests_domc
+ r_suggests_affy
+ r_suggests_ellipse
+ r_suggests_pcapp
+ r_suggests_mass
+ r_suggests_impute
+ r_suggests_dosmp
+ r_suggests_geoquery
"
- R_SUGGESTS="sci-R/doMC
- sci-R/affy
- sci-R/ellipse
- sci-R/pcaPP
- sci-R/MASS
- sci-R/impute
- sci-R/doSMP
- sci-R/GEOquery
+ R_SUGGESTS="
+ r_suggests_domc? ( sci-R/doMC )
+ r_suggests_affy? ( sci-R/affy )
+ r_suggests_ellipse? ( sci-R/ellipse )
+ r_suggests_pcapp? ( sci-R/pcaPP )
+ r_suggests_mass? ( sci-R/MASS )
+ r_suggests_impute? ( sci-R/impute )
+ r_suggests_dosmp? ( sci-R/doSMP )
+ r_suggests_geoquery? ( sci-R/GEOquery )
"
DEPEND="sci-R/foreach"
- RDEPEND="${DEPEND:-}
- R_suggests? ( ${R_SUGGESTS} )
+ RDEPEND="${DEPEND-}
+ ${R_SUGGESTS-}
"
_UNRESOLVED_PACKAGES=('hgu133plus2.db')
@@ -1847,6 +1881,11 @@ RSYNC_BWLIMIT
ADDITIONS_DIR:
Alias to OVERLAY_ADDITIONS_DIR_.
+.. _BACKUP_DESC:
+
+BACKUP_DESC
+ Alias to OVERLAY_BACKUP_DESC_.
+
.. _DISTDIR:
DISTDIR
@@ -1862,6 +1901,11 @@ DISTDIR_FLAT
DISTDIR_STRATEGY
Alias to OVERLAY_DISTDIR_STRATEGY_.
+.. _EBUILD_USE_EXPAND_NAME:
+
+EBUILD_USE_EXPAND_NAME
+ Name of the R_SUGGESTS USE_EXPAND variable. Defaults to *R_SUGGESTS*.
+
.. _ECLASS:
ECLASS
@@ -1880,6 +1924,14 @@ OVERLAY_ADDITIONS_DIR
Defaults to <not set>, which disables this feature.
+.. _OVERLAY_BACKUP_DESC:
+
+OVERLAY_BACKUP_DESC
+ A *bool* that indicates whether the description file of the *R_SUGGESTS*
+ USE_EXPAND variable should be backed up before (over-)writing it.
+
+ Defaults to *true*.
+
.. _OVERLAY_CATEGORY:
OVERLAY_CATEGORY
@@ -1997,6 +2049,11 @@ OVERLAY_NAME
Defaults to *R_Overlay*.
+.. _USE_EXPAND_NAME:
+
+USE_EXPAND_NAME:
+ Alias to EBUILD_USE_EXPAND_NAME_.
+
--------------------
other config files
--------------------
@@ -2011,6 +2068,21 @@ reasons:
The paths to these files have to be listed in the main config file and
can be overridden with the appropriate command line options.
+.. _EBUILD_USE_EXPAND_DESC:
+
+EBUILD_USE_EXPAND_DESC
+ Path to a flag description file (for the *R_SUGGESTS* USE_EXPAND variable).
+ The syntax of this file is identical to USE_EXPAND description files
+ (``<overlay root>/profiles/desc/r_suggests.desc``).
+
+ Defaults to <not set>, which disables this option.
+
+.. _EBUILD_USE_EXPAND_RENAME:
+
+EBUILD_USE_EXPAND_RENAME
+ Path to a file that lists alternative names for a flag in the *R_SUGGESTS*
+ USE_EXPAND variable.
+
.. _FIELD_DEFINITION:
FIELD_DEFINITION
@@ -2066,6 +2138,16 @@ SIMPLE_RULES_FILE
SIMPLE_RULES_FILES
Alias to SIMPLE_RULES_FILE_.
+.. _USE_EXPAND_DESC:
+
+USE_EXPAND_DESC
+ Alias to EBUILD_USE_EXPAND_DESC_.
+
+.. _USE_EXPAND_RENAME:
+
+USE_EXPAND_RENAME
+ Alias to EBUILD_USE_EXPAND_RENAME_.
+
---------
logging
---------
@@ -2210,11 +2292,61 @@ LOG_FILE_UNRESOLVABLE
Defaults to <not set>, which disables this feature.
+====================
+ Other config files
+====================
+
+-----------------------------
+ USE_EXPAND flag rename file
+-----------------------------
+
+The USE_EXPAND_RENAME_ file contains dictionary-like entries that assign
+*effective* flag names to flag names generated at runtime.
+
+The syntax is as follows:
+
+.. code-block:: text
+
+ # comments start with '#'
+
+ <effective flag> <runtime flag> [<another runtime flag>...]
+
+ # a '=' can be used as separator to improve readability
+ <effective flag> = <runtime flag> [<another runtime flag>...]
+
+ # the previous line can be continued with leading whitespace
+ <effective flag> = <runtime flag>
+ [<another runtime flag>...]
+
+
+Example:
+
+.. code-block:: text
+
+ # rename 'audio' and 'snd' to 'sound'
+ sound = audio snd
+
+
+Each flag is renamed at most once, so the following example renames 'sound'
+to media, but 'audio' to 'sound':;
+
+.. code-block:: text
+
+ sound = audio snd
+ media = sound video
+
+
+.. Caution::
+
+ Assigning more than one *effective flag* to a *runtime flag* leads to
+ unpredictable results.
+
+
.. _Field Definition:
-=========================
+-------------------------
Field Definition Config
-=========================
+-------------------------
The field definition file uses ConfigParser_ syntax and defines
how an R package's DESCRIPTION file is read.
@@ -2319,9 +2451,9 @@ Known field flags:
.. _default field definition file:
---------------------------------------------
+++++++++++++++++++++++++++++++++++++++++++++
Example: The default field definition file
---------------------------------------------
+++++++++++++++++++++++++++++++++++++++++++++
This is the default field definition file (without any ignored fields):
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-06-25 21:10 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-06-25 21:10 UTC (permalink / raw
To: gentoo-commits
commit: adbe0bb8d1edc7cbff598b4834fbaceb7335fbb3
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Jun 25 21:10:02 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Jun 25 21:10:02 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=adbe0bb8
doc/rst: doc for "run hooks" (incomplete)
---
doc/rst/usage.rst | 354 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 354 insertions(+)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 8d06bab..078a7ac 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -314,6 +314,12 @@ have reasonable defaults if *roverlay* has been installed using *emerge*:
Example: USE_EXPAND_RENAME = ~/roverlay/config/useflag_rename
+ CACHEDIR
+ Directory for generated files that do not belong to the overlay, e.g.
+ the *distmap* file. This option is **required**.
+
+ Example: CACHEDIR = ~/roverlay/workdir/cache
+
OVERLAY_ECLASS
This option lists eclass files that should be imported into the overlay
(into *OVERLAY_DIR*/eclass/) and inherited in all ebuilds.
@@ -409,6 +415,10 @@ to know in detail what *roverlay* does before running it.
--nosync, --no-sync
Disable downloading of R packages.
+--distmap-verify
+ Enforce verification of R packages in the package mirror directory.
+ This also tries to recreate the distmap.
+
--no-incremental
Force recreation of existing ebuilds
@@ -1834,6 +1844,16 @@ The following sections will list all config entries.
misc options
--------------
+.. _CACHEDIR:
+
+CACHEDIR
+ Directory for persistent files that don't belong to the overlay, e.g.
+ the distmap file.
+
+ This option is **required**.
+
+ <<TODO: default value!>>
+
.. _DISTFILES:
DISTFILES
@@ -1863,6 +1883,14 @@ EBUILD_PROG
Defaults to *ebuild*, which should be fine in most cases.
+.. _NOSYNC:
+
+NOSYNC
+ A *bool* that controls whether *syncing*, i.e. data transfers from/to
+ remote machines, is allowed or forbidden.
+
+ Defaults to *no*.
+
.. _RSYNC_BWLIMIT:
RSYNC_BWLIMIT
@@ -1872,6 +1900,7 @@ RSYNC_BWLIMIT
Defaults to <not set>, which disables bandwidth limitation.
+
-----------------
overlay options
-----------------
@@ -1901,6 +1930,17 @@ DISTDIR_FLAT
DISTDIR_STRATEGY
Alias to OVERLAY_DISTDIR_STRATEGY_.
+
+.. _DISTDIR_VERIFY:
+
+DISTDIR_VERIFY
+ Alias to OVERLAY_DISTDIR_VERIFY_.
+
+.. _DISTMAP_FILE:
+
+DISTMAP_FILE
+ Alias to OVERLAY_DISTMAP_FILE_.
+
.. _EBUILD_USE_EXPAND_NAME:
EBUILD_USE_EXPAND_NAME
@@ -2002,6 +2042,23 @@ OVERLAY_DISTDIR_STRATEGY
This option is **required**, but has a reasonable value in the default
config file, "hardlink symlink".
+.. _OVERLAY_DISTDIR_VERIFY:
+
+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.
+
+ Defaults to *no* as the verification is normally not needed.
+
+
+.. _OVERLAY_DISTMAP_FILE:
+
+OVERLAY_DISTMAP_FILE:
+ File path to the distmap file.
+
+ Defaults to <not set>, which results in CACHEDIR_/distmap.db.
+
.. _OVERLAY_ECLASS:
OVERLAY_ECLASS
@@ -2148,6 +2205,45 @@ USE_EXPAND_DESC
USE_EXPAND_RENAME
Alias to EBUILD_USE_EXPAND_RENAME_.
+---------------------------
+ shell environment / hooks
+---------------------------
+
+.. _EVENT_HOOK:
+
+EVENT_HOOK
+ A script that is called for handling *events* (see Hooks_).
+
+ Defaults to ADDITIONS_DIR_/hooks/mux.sh.
+
+.. _EVENT_HOOK_RESTRICT:
+
+EVENT_HOOK_RESTRICT
+ A list of *events* that are allowed (``<event>``, ``+<event>``) or
+ forbidden (``-<event>``). The asterisk wildcard character can be used to
+ set the default policy to *allow unless forbidden* (``*``) or
+ *deny unless allowed* (``-*``).
+
+ Defaults to <not set>, which is equivalent to *deny all*.
+
+.. _FILTER_SHELL_ENV:
+
+FILTER_SHELL_ENV
+ A *bool* that controls whether the hook environment should be filtered
+ or not.
+
+ Defaults to *true*.
+
+.. _HOOK:
+
+HOOK
+ Alias to EVENT_HOOK_.
+
+.. _HOOK_RESTRICT:
+
+HOOK_RESTRICT
+ Alias to EVENT_HOOK_RESTRICT_.
+
---------
logging
---------
@@ -3146,3 +3242,261 @@ Its mode of operation of operation is best described in pseudo-code:
The dependency resolver can be **run as thread**, in which case the while loop
becomes "loop until resolver closes".
+
+
+=======
+ undef
+=======
+
+<<TODO; this section has to merged/moved>>
+
+---------
+ distmap
+---------
+
+The distmap is a file that stores information about the files in the package
+mirror directory (`OVERLAY_DISTDIR_ROOT`_).
+<<TODO>>
+
+
+-------
+ hooks
+-------
+
+*roverlay* calls a script when certain events occur, e.g. after successful
+overlay creation.
+
+<<TODO>>
+
+* real work is offloaded to the called script
+* roverlay provides some env vars
+* roverlay provides a *$FUNCTIONS* file and a way to load other function files
+* ``EVENT_HOOK_RESTRICT="this -not_that *"``
+
+<<^^TODO>>
+
+.. Note::
+
+ *roverlay* waits until the script terminates.
+
+
+++++++++++++++++++
+ Hook environment
+++++++++++++++++++
+
+.. table:: environment variables provided by *roverlay*
+
+ +----------------+------------------+-----------------------------------------+
+ | variable | source | notes / description |
+ +================+==================+=========================================+
+ | PATH | os.environ | |
+ +----------------+------------------+-----------------------------------------+
+ | LOGNAME | os.environ | |
+ +----------------+------------------+-----------------------------------------+
+ | SHLVL | os.environ | |
+ +----------------+------------------+-----------------------------------------+
+ | TERM | os.environ | |
+ +----------------+------------------+-----------------------------------------+
+ | HOME | os.environ | |
+ +----------------+------------------+-----------------------------------------+
+ | ROVERLAY_PHASE | event | event that caused the script to run |
+ +----------------+------------------+-----------------------------------------+
+ | OVERLAY | config | overlay directory (`OVERLAY_DIR`_), |
+ +----------------+------------------+ initial working directory |
+ | S | *$OVERLAY* | |
+ +----------------+------------------+ |
+ | PWD | *$OVERLAY* | |
+ +----------------+------------------+-----------------------------------------+
+ | DISTROOT | config | package mirror directory |
+ | | | (`OVERLAY_DISTDIR_ROOT`_) |
+ +----------------+------------------+-----------------------------------------+
+ | TMPDIR | os.environ, | directory for temporary files |
+ | | *fallback* | |
+ +----------------+------------------+ |
+ | T | *$TMPDIR* | |
+ +----------------+------------------+-----------------------------------------+
+ | ADDITIONS_DIR | config | directory with supplementary files |
+ | | | (`OVERLAY_ADDITIONS_DIR`_) |
+ +----------------+------------------+ |
+ | FILESDIR | *$ADDITIONS_DIR* | |
+ +----------------+------------------+-----------------------------------------+
+ | SHLIB | *$ADDITIONS_DIR* | directory with shell function files |
+ | | | (optional, only set if it exists) |
+ +----------------+------------------+-----------------------------------------+
+ | FUNCTIONS | *$ADDITIONS_DIR* | file with essential shell functions |
+ | | | (optional, only set if it exists) |
+ +----------------+------------------+-----------------------------------------+
+ | DEBUG | log level | *shbool* (``y`` or ``n``) that |
+ | | | indicates whether debug messages should |
+ | | | be printed |
+ +----------------+------------------+-----------------------------------------+
+ | VERBOSE | log level | *shbool* |
+ +----------------+------------------+-----------------------------------------+
+ | QUIET | log level | *shbool* that indicates whether scripts |
+ | | | should be quiet |
+ +----------------+------------------+-----------------------------------------+
+ | NO_COLOR | *n/a* | *shbool*. Always set to *y* since |
+ | | | colored output should not be produced |
+ +----------------+------------------+-----------------------------------------+
+ | NOSYNC | config | *shbool* that indicates whether data |
+ | | | transfers from/to remote machines is |
+ | | | allowed (NOSYNC_) |
+ +----------------+------------------+-----------------------------------------+
+ | EBUILD | config | the *ebuild* executable |
+ +----------------+------------------+-----------------------------------------+
+ | GIT_EDITOR | *n/a* | set to */bin/false* |
+ +----------------+------------------+ |
+ | GIT_ASKPASS | *n/a* | |
+ +----------------+------------------+-----------------------------------------+
+
+
+The default *essential shell functions* file (*$FUNCTIONS*) makes,
+when included in the hook script, most of the enviroment variables readonly.
+
+
+.. table:: variables provided by *$FUNCTIONS*
+
+ +-----------------+-------------------------------------------------------+
+ | variable | description |
+ +=================+=======================================================+
+ | IFS_DEFAULT | default *internal field separator* |
+ +-----------------+-------------------------------------------------------+
+ | IFS_NEWLINE | *IFS* for iterating over text lines |
+ +-----------------+-------------------------------------------------------+
+ | DEVNULL | */dev/null* target (could also be a file) |
+ +-----------------+-------------------------------------------------------+
+ | EX_ERR | default error exit code |
+ +-----------------+-------------------------------------------------------+
+ | EX_ARG_ERR | default exit code for arg errors |
+ +-----------------+-------------------------------------------------------+
+ | SCRIPT_FILENAME | file name of the hook script |
+ +-----------------+-------------------------------------------------------+
+ | SCRIPT_NAME | name of the hook script (without file extension) |
+ +-----------------+-------------------------------------------------------+
+ | lf | reference to a function that loads additional shell |
+ | | function files |
+ +-----------------+-------------------------------------------------------+
+
+
+*$FUNCTIONS* also provides a number of shell functions:
+
+.. code-block:: sh
+
+ # --- message ---
+ #
+ # void veinfo ( message )
+ # Prints a message to stdout if $DEBUG is set to 'y'.
+ #
+ # void einfo ( message )
+ # Prints a message to stdout if $VERBOSE is set to 'y'.
+ #
+ # void ewarn ( message )
+ # Prints a message to stderr unless $QUIET is set to 'y'.
+ #
+ # void eerror ( message )
+ # Prints a message to stderr.
+ #
+ #
+ # --- core ---
+ #
+ # @noreturn die ( [message], [exit_code] ), raises exit()
+ # Lets the script die with the given message/exit code.
+ #
+ # @noreturn OUT_OF_BOUNDS(), raises die()
+ # Lets the script die due to insufficient arg count.
+ #
+ # int run_command ( *cmdv )
+ # Logs a command and runs it afterwards.
+ #
+ # int run_command_logged ( *cmdv )
+ # Logs a command, runs it and logs the result.
+ #
+ # void autodie ( *cmdv ), raises die()
+ # Runs a command. Lets the script die if the command fails.
+ #
+ #
+ # void load_functions ( *filenames, **SHLIB ), raises die()
+ # Loads additional shell functions file(s) from $SHLIB.
+ # (Referenced by $lf.)
+ #
+ # void dont_run_as_root(), raises die()
+ # Lets the script die if it is run as root.
+ #
+ # int list_has ( word, *list_items )
+ # Returns 0 if $word is in the given list.
+ #
+ # int qwhich ( *command )
+ # Returns 0 if all listed commands are found by "which".
+ #
+ #
+ # --- fs ---
+ #
+ # int dodir ( *dir )
+ # Ensures that zero or more directories exist by creating them if
+ # necessary. Returns the number of directories that could not be created.
+ #
+ #
+ # --- str ---
+ #
+ # int yesno ( word, **YESNO_YES=0, **YESNO_NO=1, **YESNO_EMPTY=2 )
+ # Returns $YESNO_YES if $word means "yes", $YESNO_EMPTY if $word is empty
+ # and $YESNO_NO otherwise (if $word probably means "no").
+ #
+ # ~int str_trim ( *args )
+ # Removes whitespace at the beginning and end of a string and replaces
+ # any whitespace sequence within the string with a single space char.
+ # Passes the return value of the underlying sed command.
+ #
+ # ~int str_upper ( *args )
+ # Echoes the uppercase variant of stdin or *args.
+ # Passes tr's return value.
+ #
+ # ~int str_lower ( *args )
+ # Echoes the lowercase variant of stdin or *args.
+ # Passes tr's return value.
+ #
+ # ~int str_field ( fieldspec, *args, **FIELD_SEPARATOR=' ' )
+ # Echoes the requested fields of stdin or *args.
+ # Passes cut's return value.
+ #
+ #
+ # --- int ---
+ #
+ # int is_int ( word )
+ # Returns 0 if $word is an integer, else 1.
+ #
+ # int is_natural ( word )
+ # Returns 0 if $word is an integer >= 0, else 1.
+ #
+ # int is_positive ( word )
+ # Returns 0 if $word is an integer >= 1, else 1.
+ #
+ # int is_negative ( word )
+ # Returns 0 if $word is an integer < 0, else 1.
+ #
+
+
++++++++++++++++++++++
+ Adding a hook event
++++++++++++++++++++++
+
+in roverlay
+
+.. code-block:: python
+
+ # import hook module
+ import roverlay.hook
+
+ # ...
+ # then:
+ roverlay.hook.run ( "<event>" )
+ # ...
+ roverlay.hook.run ( "<another event>" )
+
+
+in additions dir (assuming that mux.sh is used)
+
+.. code-block:: text
+
+ <somehow create> ${ADDITIONS_DIR}/<hook>.<event>
+ <somehow create> ${ADDITIONS_DIR}/<hook>/<event>.sh
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-06-26 17:29 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-06-26 17:29 UTC (permalink / raw
To: gentoo-commits
commit: 0678580564dcf6aa8e2587d3b04d62544265ca74
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jun 26 17:28:39 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jun 26 17:28:39 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=06785805
doc/rst: "run hooks", "distmap"
---
doc/rst/usage.rst | 643 ++++++++++++++++++++++++++++++++----------------------
1 file changed, 383 insertions(+), 260 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 078a7ac..2daedce 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1010,6 +1010,22 @@ A local directory will never be modified.
consider using one of the **websync** repo types, websync_repo_ and
websync_pkglist_.
+---------
+ distmap
+---------
+
+*roverlay* uses a text file to store information about files in the package
+mirror directory (OVERLAY_DISTDIR_ROOT_). This is necessary for comparing
+package files from repos with files for which an ebuild has already been
+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.
+
+The *distmap file* can optionally be compressed (bzip2 or gzip), which
+reduces its size considerably.
+
=====================
Additions Directory
@@ -1790,6 +1806,354 @@ Moving such packages to a "R-package" sub directory would be possible, too:
END;
+=============
+ Event Hooks
+=============
+
+*roverlay* is able to call a script when certain events occur, e.g. after
+successful overlay creation, which can be used to perform additional actions
+without touching *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,
+which provides extra functionality.
+
+.. Note::
+
+ *roverlay* waits until the script terminates and thus possibly waits
+ forever.
+
+
+----------------------
+ Default event script
+----------------------
+
+The default event script (``mux.sh``) loads *$FUNCTIONS* and then runs the
+following script files (by sourcing them), in order:
+
+#. all files from ADDITIONS_DIR_/hooks/<event> that end with *.sh*
+ (``<ADDITIONS_DIR>/hooks/<event>/*.sh``)
+#. all files ADDITIONS_DIR_/hooks that end with *.<event>*
+ (``<ADDITIONS_DIR>/hooks/*.<event>``)
+
+So, there are two naming schemes for *hook scripts*.
+Either one is acceptable, but it is advised to stay consistent.
+Having the same script at both locations results in executing it twice.
+
+.. Note::
+
+ The default event script enables *nounset* behavior, which causes the
+ shell command interpreter to exit abnormally if an unset variable is
+ accessed.
+
+
+++++++++++++++++++++++++++
+ Activating a hook script
+++++++++++++++++++++++++++
+
+Activating a hook script can be done by symlinking it:
+
+.. code-block:: text
+
+ ln -s <real script> ${ADDITIONS_DIR}/hooks/<event>/<name>.sh
+ # or
+ ln -s <real script> ${ADDITIONS_DIR}/hooks/<name>.<event>
+
+
+++++++++++++++++++++++++++
+ Adding a new hook script
+++++++++++++++++++++++++++
+
+As hinted before, *hook scripts* are simple shell scripts. The following
+template gives an idea of how to write them:
+
+.. code-block:: sh
+
+ #!/bin/sh
+ #set -u
+
+ # load essential functions
+ # (not necessary when using the default event script)
+ . "${FUNCTIONS?}" || exit
+
+ ## load additional function files, if any
+ #$lf <name(s)>
+
+ # script body
+ #
+ # when redirecting output to $DEVNULL, use ">>" instead of ">" as
+ # $DEVNULL could be a file
+ #ls >>${DEVNULL}
+ #
+ # ...
+
+
+ # the script must not exit if everything went well (return is ok)
+ return 0
+
+
+--------------
+ Event Policy
+--------------
+
+The *event policy* controls whether a certain event actually triggers a script
+call or not.
+It is constructed by parsing the EVENT_HOOK_RESTRICT_ config option:
+
+* a word prefixed by ``-`` means *deny specific event* (-> blacklist)
+* the asterisk char ``*`` (or ``+*``) sets the policy to
+ *allow unless denied* (blacklist) or *allow all*
+* a word prefixed by ``+`` or without a prefix char means
+ *allow specific event* (-> whitelist)
+* the asterisk char with ``-`` as prefix (``-*``) sets the policy to
+ *deny unless allowed* (whitelist) or *deny all*
+
+
+The policy defaults to *allow all* if ``EVENT_HOOK_RESTRICT`` is not set in
+the config file. An empty string sets the policy to *deny all*.
+
+
+------------------
+ Hook Environment
+------------------
+
+.. table:: environment variables provided by *roverlay*
+
+ +----------------+-------------------+-----------------------------------------+
+ | variable | source | notes / description |
+ +================+===================+=========================================+
+ | PATH | os.environ | |
+ +----------------+-------------------+-----------------------------------------+
+ | LOGNAME | os.environ | |
+ +----------------+-------------------+-----------------------------------------+
+ | SHLVL | os.environ | |
+ +----------------+-------------------+-----------------------------------------+
+ | TERM | os.environ | |
+ +----------------+-------------------+-----------------------------------------+
+ | HOME | os.environ | |
+ +----------------+-------------------+-----------------------------------------+
+ | ROVERLAY_PHASE | event | event that caused the script to run |
+ +----------------+-------------------+-----------------------------------------+
+ | OVERLAY | config | overlay directory (`OVERLAY_DIR`_), |
+ +----------------+-------------------+ initial working directory |
+ | S | *$OVERLAY* | |
+ +----------------+-------------------+ |
+ | PWD | *$OVERLAY* | |
+ +----------------+-------------------+-----------------------------------------+
+ | DISTROOT | config | package mirror directory |
+ | | | (`OVERLAY_DISTDIR_ROOT`_) |
+ +----------------+-------------------+-----------------------------------------+
+ | TMPDIR | os.environ, | directory for temporary files |
+ | | *fallback* | |
+ +----------------+-------------------+ |
+ | T | *$TMPDIR* | |
+ +----------------+-------------------+-----------------------------------------+
+ | ADDITIONS_DIR | config | directory with supplementary files |
+ | | | (`OVERLAY_ADDITIONS_DIR`_) |
+ +----------------+-------------------+ |
+ | FILESDIR | *$ADDITIONS_DIR* | |
+ +----------------+-------------------+-----------------------------------------+
+ | SHLIB | *$ADDITIONS_DIR*, | A list of directories with shell |
+ | | *installed?* | function files |
+ | | | (optional, only set if any dir exists) |
+ +----------------+-------------------+-----------------------------------------+
+ | FUNCTIONS | *$ADDITIONS_DIR*, | file with essential shell functions |
+ | | *installed?* | (optional, only set if it exists) |
+ +----------------+-------------------+-----------------------------------------+
+ | DEBUG | log level | *shbool* (``y`` or ``n``) that |
+ | | | indicates whether debug messages should |
+ | | | be printed |
+ +----------------+-------------------+-----------------------------------------+
+ | VERBOSE | log level | *shbool* |
+ +----------------+-------------------+-----------------------------------------+
+ | QUIET | log level | *shbool* that indicates whether scripts |
+ | | | should be quiet |
+ +----------------+-------------------+-----------------------------------------+
+ | NO_COLOR | *n/a* | *shbool*. Always set to *y* since |
+ | | | colored output should not be produced |
+ +----------------+-------------------+-----------------------------------------+
+ | NOSYNC | config | *shbool* that indicates whether data |
+ | | | transfers from/to remote machines is |
+ | | | allowed (NOSYNC_) |
+ +----------------+-------------------+-----------------------------------------+
+ | EBUILD | config | the *ebuild* executable |
+ +----------------+-------------------+-----------------------------------------+
+ | GIT_EDITOR | *n/a* | set to */bin/false* |
+ +----------------+-------------------+ |
+ | GIT_ASKPASS | *n/a* | |
+ +----------------+-------------------+-----------------------------------------+
+
+
+The default *essential shell functions* file (*$FUNCTIONS*) makes,
+when included in the hook script, most of the enviroment variables readonly.
+
+
+.. table:: variables provided by *$FUNCTIONS*
+
+ +-----------------+-------------------------------------------------------+
+ | variable | description |
+ +=================+=======================================================+
+ | IFS_DEFAULT | default *internal field separator* |
+ +-----------------+-------------------------------------------------------+
+ | IFS_NEWLINE | *IFS* for iterating over text lines |
+ +-----------------+-------------------------------------------------------+
+ | DEVNULL | */dev/null* target (could also be a file) |
+ +-----------------+-------------------------------------------------------+
+ | EX_ERR | default error exit code |
+ +-----------------+-------------------------------------------------------+
+ | EX_ARG_ERR | default exit code for arg errors |
+ +-----------------+-------------------------------------------------------+
+ | SCRIPT_FILENAME | file name of the hook script |
+ +-----------------+-------------------------------------------------------+
+ | SCRIPT_NAME | name of the hook script (without file extension) |
+ +-----------------+-------------------------------------------------------+
+ | lf | reference to a function that loads additional shell |
+ | | function files |
+ +-----------------+-------------------------------------------------------+
+
+
+*$FUNCTIONS* also provides a number of shell functions:
+
+.. code-block:: sh
+
+ # --- message ---
+ #
+ # void veinfo ( message )
+ # Prints a message to stdout if $DEBUG is set to 'y'.
+ #
+ # void einfo ( message )
+ # Prints a message to stdout if $VERBOSE is set to 'y'.
+ #
+ # void ewarn ( message )
+ # Prints a message to stderr unless $QUIET is set to 'y'.
+ #
+ # void eerror ( message )
+ # Prints a message to stderr.
+ #
+ #
+ # --- core ---
+ #
+ # @noreturn die ( [message], [exit_code] ), raises exit()
+ # Lets the script die with the given message/exit code.
+ #
+ # @noreturn OUT_OF_BOUNDS(), raises die()
+ # Lets the script die due to insufficient arg count.
+ #
+ # int run_command ( *cmdv )
+ # Logs a command and runs it afterwards.
+ #
+ # int run_command_logged ( *cmdv )
+ # Logs a command, runs it and logs the result.
+ #
+ # void autodie ( *cmdv ), raises die()
+ # Runs a command. Lets the script die if the command fails.
+ #
+ #
+ # void load_functions ( *filenames, **SHLIB ), raises die()
+ # Loads additional shell functions file(s) from $SHLIB.
+ # (Referenced by $lf.)
+ #
+ # void dont_run_as_root(), raises die()
+ # Lets the script die if it is run as root.
+ #
+ # int list_has ( word, *list_items )
+ # Returns 0 if $word is in the given list, else 1.
+ #
+ # int qwhich ( *command )
+ # Returns 0 if all listed commands are found by "which", else 1.
+ #
+ #
+ # --- fs ---
+ #
+ # int dodir ( *dir )
+ # Ensures that zero or more directories exist by creating them if
+ # necessary. Returns the number of directories that could not be created.
+ #
+ #
+ # --- str ---
+ #
+ # int yesno ( word, **YESNO_YES=0, **YESNO_NO=1, **YESNO_EMPTY=2 )
+ # Returns $YESNO_YES if $word means "yes", $YESNO_EMPTY if $word is empty
+ # and $YESNO_NO otherwise (if $word probably means "no").
+ #
+ # ~int str_trim ( *args )
+ # Removes whitespace at the beginning and end of a string and replaces
+ # any whitespace sequence within the string with a single space char.
+ # Passes the return value of the underlying sed command.
+ #
+ # ~int str_upper ( *args )
+ # Echoes the uppercase variant of stdin or *args.
+ # Passes tr's return value.
+ #
+ # ~int str_lower ( *args )
+ # Echoes the lowercase variant of stdin or *args.
+ # Passes tr's return value.
+ #
+ # ~int str_field ( fieldspec, *args, **FIELD_SEPARATOR=' ' )
+ # Echoes the requested fields of stdin or *args.
+ # Passes cut's return value.
+ #
+ #
+ # --- int ---
+ #
+ # int is_int ( word )
+ # Returns 0 if $word is an integer, else 1.
+ #
+ # int is_natural ( word )
+ # Returns 0 if $word is an integer >= 0, else 1.
+ #
+ # int is_positive ( word )
+ # Returns 0 if $word is an integer >= 1, else 1.
+ #
+ # int is_negative ( word )
+ # Returns 0 if $word is an integer < 0, else 1.
+ #
+
+
+------------------------
+ Adding a function file
+------------------------
+
+Function files are shell script files that provide functions and variables.
+They should, however, not execute any code directly.
+
+The template below illustrates how to write function files:
+
+.. code-block:: sh
+
+ # protect against repeated inclusion of this file
+ # (replace <name> with a unique identifier)
+ if [ -z "${__HAVE_<name>__-}" ]; then
+ readonly __HAVE_<name>__=y
+
+ # function file body
+ # ...
+
+ fi
+
+Shell function files should be put into ``<ADDITIONS_DIR>/shlib``.
+
+---------------------
+ 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:
+
+.. code-block:: python
+
+ # import hook module
+ import roverlay.hook
+
+ # ...
+ # then, somewhere in the code
+ roverlay.hook.run ( "<event>" )
+ # ...
+ roverlay.hook.run ( "<another event>" )
+
+
=========================
Configuration Reference
=========================
@@ -1936,6 +2300,11 @@ DISTDIR_STRATEGY
DISTDIR_VERIFY
Alias to OVERLAY_DISTDIR_VERIFY_.
+.. _DISTMAP_COMPRESSION:
+
+DISTMAP_COMPRESSION
+ Alias to OVERLAY_DISTMAP_COMPRESSION_.
+
.. _DISTMAP_FILE:
DISTMAP_FILE
@@ -2051,6 +2420,13 @@ OVERLAY_DISTDIR_VERIFY
Defaults to *no* as the verification is normally not needed.
+.. _OVERLAY_DISTMAP_COMPRESSION:
+
+OVERLAY_DISTMAP_COMPRESSION
+ Compression format for the distmap file. Choices are none, gzip/gz and
+ bzip2/bz2.
+
+ Defaults to bzip2.
.. _OVERLAY_DISTMAP_FILE:
@@ -2212,9 +2588,10 @@ USE_EXPAND_RENAME
.. _EVENT_HOOK:
EVENT_HOOK
- A script that is called for handling *events* (see Hooks_).
+ A script that is called for handling *events* (see `Event Hooks`_).
- Defaults to ADDITIONS_DIR_/hooks/mux.sh.
+ Defaults to <libexec dir>/hooks/mux.sh if roverlay has been installed
+ and ADDITIONS_DIR_/hooks/mux.sh otherwise.
.. _EVENT_HOOK_RESTRICT:
@@ -2226,6 +2603,10 @@ EVENT_HOOK_RESTRICT
Defaults to <not set>, which is equivalent to *deny all*.
+ ``EVENT_HOOK_RESTRICT="overlay_success"`` would allow the ``overlay_success``
+ event only, whereas ``EVENT_HOOK_RESTRICT="* -overlay_success"`` would
+ allow any event except for ``overlay_success``. Also see `event policy`_.
+
.. _FILTER_SHELL_ENV:
FILTER_SHELL_ENV
@@ -3242,261 +3623,3 @@ Its mode of operation of operation is best described in pseudo-code:
The dependency resolver can be **run as thread**, in which case the while loop
becomes "loop until resolver closes".
-
-
-=======
- undef
-=======
-
-<<TODO; this section has to merged/moved>>
-
----------
- distmap
----------
-
-The distmap is a file that stores information about the files in the package
-mirror directory (`OVERLAY_DISTDIR_ROOT`_).
-<<TODO>>
-
-
--------
- hooks
--------
-
-*roverlay* calls a script when certain events occur, e.g. after successful
-overlay creation.
-
-<<TODO>>
-
-* real work is offloaded to the called script
-* roverlay provides some env vars
-* roverlay provides a *$FUNCTIONS* file and a way to load other function files
-* ``EVENT_HOOK_RESTRICT="this -not_that *"``
-
-<<^^TODO>>
-
-.. Note::
-
- *roverlay* waits until the script terminates.
-
-
-++++++++++++++++++
- Hook environment
-++++++++++++++++++
-
-.. table:: environment variables provided by *roverlay*
-
- +----------------+------------------+-----------------------------------------+
- | variable | source | notes / description |
- +================+==================+=========================================+
- | PATH | os.environ | |
- +----------------+------------------+-----------------------------------------+
- | LOGNAME | os.environ | |
- +----------------+------------------+-----------------------------------------+
- | SHLVL | os.environ | |
- +----------------+------------------+-----------------------------------------+
- | TERM | os.environ | |
- +----------------+------------------+-----------------------------------------+
- | HOME | os.environ | |
- +----------------+------------------+-----------------------------------------+
- | ROVERLAY_PHASE | event | event that caused the script to run |
- +----------------+------------------+-----------------------------------------+
- | OVERLAY | config | overlay directory (`OVERLAY_DIR`_), |
- +----------------+------------------+ initial working directory |
- | S | *$OVERLAY* | |
- +----------------+------------------+ |
- | PWD | *$OVERLAY* | |
- +----------------+------------------+-----------------------------------------+
- | DISTROOT | config | package mirror directory |
- | | | (`OVERLAY_DISTDIR_ROOT`_) |
- +----------------+------------------+-----------------------------------------+
- | TMPDIR | os.environ, | directory for temporary files |
- | | *fallback* | |
- +----------------+------------------+ |
- | T | *$TMPDIR* | |
- +----------------+------------------+-----------------------------------------+
- | ADDITIONS_DIR | config | directory with supplementary files |
- | | | (`OVERLAY_ADDITIONS_DIR`_) |
- +----------------+------------------+ |
- | FILESDIR | *$ADDITIONS_DIR* | |
- +----------------+------------------+-----------------------------------------+
- | SHLIB | *$ADDITIONS_DIR* | directory with shell function files |
- | | | (optional, only set if it exists) |
- +----------------+------------------+-----------------------------------------+
- | FUNCTIONS | *$ADDITIONS_DIR* | file with essential shell functions |
- | | | (optional, only set if it exists) |
- +----------------+------------------+-----------------------------------------+
- | DEBUG | log level | *shbool* (``y`` or ``n``) that |
- | | | indicates whether debug messages should |
- | | | be printed |
- +----------------+------------------+-----------------------------------------+
- | VERBOSE | log level | *shbool* |
- +----------------+------------------+-----------------------------------------+
- | QUIET | log level | *shbool* that indicates whether scripts |
- | | | should be quiet |
- +----------------+------------------+-----------------------------------------+
- | NO_COLOR | *n/a* | *shbool*. Always set to *y* since |
- | | | colored output should not be produced |
- +----------------+------------------+-----------------------------------------+
- | NOSYNC | config | *shbool* that indicates whether data |
- | | | transfers from/to remote machines is |
- | | | allowed (NOSYNC_) |
- +----------------+------------------+-----------------------------------------+
- | EBUILD | config | the *ebuild* executable |
- +----------------+------------------+-----------------------------------------+
- | GIT_EDITOR | *n/a* | set to */bin/false* |
- +----------------+------------------+ |
- | GIT_ASKPASS | *n/a* | |
- +----------------+------------------+-----------------------------------------+
-
-
-The default *essential shell functions* file (*$FUNCTIONS*) makes,
-when included in the hook script, most of the enviroment variables readonly.
-
-
-.. table:: variables provided by *$FUNCTIONS*
-
- +-----------------+-------------------------------------------------------+
- | variable | description |
- +=================+=======================================================+
- | IFS_DEFAULT | default *internal field separator* |
- +-----------------+-------------------------------------------------------+
- | IFS_NEWLINE | *IFS* for iterating over text lines |
- +-----------------+-------------------------------------------------------+
- | DEVNULL | */dev/null* target (could also be a file) |
- +-----------------+-------------------------------------------------------+
- | EX_ERR | default error exit code |
- +-----------------+-------------------------------------------------------+
- | EX_ARG_ERR | default exit code for arg errors |
- +-----------------+-------------------------------------------------------+
- | SCRIPT_FILENAME | file name of the hook script |
- +-----------------+-------------------------------------------------------+
- | SCRIPT_NAME | name of the hook script (without file extension) |
- +-----------------+-------------------------------------------------------+
- | lf | reference to a function that loads additional shell |
- | | function files |
- +-----------------+-------------------------------------------------------+
-
-
-*$FUNCTIONS* also provides a number of shell functions:
-
-.. code-block:: sh
-
- # --- message ---
- #
- # void veinfo ( message )
- # Prints a message to stdout if $DEBUG is set to 'y'.
- #
- # void einfo ( message )
- # Prints a message to stdout if $VERBOSE is set to 'y'.
- #
- # void ewarn ( message )
- # Prints a message to stderr unless $QUIET is set to 'y'.
- #
- # void eerror ( message )
- # Prints a message to stderr.
- #
- #
- # --- core ---
- #
- # @noreturn die ( [message], [exit_code] ), raises exit()
- # Lets the script die with the given message/exit code.
- #
- # @noreturn OUT_OF_BOUNDS(), raises die()
- # Lets the script die due to insufficient arg count.
- #
- # int run_command ( *cmdv )
- # Logs a command and runs it afterwards.
- #
- # int run_command_logged ( *cmdv )
- # Logs a command, runs it and logs the result.
- #
- # void autodie ( *cmdv ), raises die()
- # Runs a command. Lets the script die if the command fails.
- #
- #
- # void load_functions ( *filenames, **SHLIB ), raises die()
- # Loads additional shell functions file(s) from $SHLIB.
- # (Referenced by $lf.)
- #
- # void dont_run_as_root(), raises die()
- # Lets the script die if it is run as root.
- #
- # int list_has ( word, *list_items )
- # Returns 0 if $word is in the given list.
- #
- # int qwhich ( *command )
- # Returns 0 if all listed commands are found by "which".
- #
- #
- # --- fs ---
- #
- # int dodir ( *dir )
- # Ensures that zero or more directories exist by creating them if
- # necessary. Returns the number of directories that could not be created.
- #
- #
- # --- str ---
- #
- # int yesno ( word, **YESNO_YES=0, **YESNO_NO=1, **YESNO_EMPTY=2 )
- # Returns $YESNO_YES if $word means "yes", $YESNO_EMPTY if $word is empty
- # and $YESNO_NO otherwise (if $word probably means "no").
- #
- # ~int str_trim ( *args )
- # Removes whitespace at the beginning and end of a string and replaces
- # any whitespace sequence within the string with a single space char.
- # Passes the return value of the underlying sed command.
- #
- # ~int str_upper ( *args )
- # Echoes the uppercase variant of stdin or *args.
- # Passes tr's return value.
- #
- # ~int str_lower ( *args )
- # Echoes the lowercase variant of stdin or *args.
- # Passes tr's return value.
- #
- # ~int str_field ( fieldspec, *args, **FIELD_SEPARATOR=' ' )
- # Echoes the requested fields of stdin or *args.
- # Passes cut's return value.
- #
- #
- # --- int ---
- #
- # int is_int ( word )
- # Returns 0 if $word is an integer, else 1.
- #
- # int is_natural ( word )
- # Returns 0 if $word is an integer >= 0, else 1.
- #
- # int is_positive ( word )
- # Returns 0 if $word is an integer >= 1, else 1.
- #
- # int is_negative ( word )
- # Returns 0 if $word is an integer < 0, else 1.
- #
-
-
-+++++++++++++++++++++
- Adding a hook event
-+++++++++++++++++++++
-
-in roverlay
-
-.. code-block:: python
-
- # import hook module
- import roverlay.hook
-
- # ...
- # then:
- roverlay.hook.run ( "<event>" )
- # ...
- roverlay.hook.run ( "<another event>" )
-
-
-in additions dir (assuming that mux.sh is used)
-
-.. code-block:: text
-
- <somehow create> ${ADDITIONS_DIR}/<hook>.<event>
- <somehow create> ${ADDITIONS_DIR}/<hook>/<event>.sh
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
2013-07-03 10:05 [gentoo-commits] proj/R_overlay:master commit in: doc/rst/ André Erdmann
@ 2013-06-28 17:18 ` André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-06-28 17:18 UTC (permalink / raw
To: gentoo-commits
commit: 22b1e80c37192d3049f95293cedd03b30ca2c7d2
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Jun 28 17:16:32 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Jun 28 17:16:32 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=22b1e80c
doc/rst: SLOT handling (incomplete)
Draft for documentation about fuzzy slot rules.
(No doc/html commit will be created since documentation is todo.)
---
doc/rst/usage.rst | 69 +++++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 62 insertions(+), 7 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 2daedce..f3e2e18 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1160,7 +1160,8 @@ Simple Rules
Fuzzy Rules
Fuzzy Rules are **extended Simple Rules**. If the basic lookup
as described above fails for a *dependency string*,
- they will *try* to resolve it as a **version-relative match**.
+ they will *try* to resolve it as a **version-relative**,
+ **slot-relative** or **version,slot-relative match**.
To do this, the *dependency string* will be split into components like
*dependency name*, *dependency version* and useless comments, which are
@@ -1177,7 +1178,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-2.10 dev-lang/R )"
+ * "R ( !=2.10 )" as "( !=dev-lang/R-2.10 dev-lang/R )"
++++++++++++++++++++
@@ -1190,7 +1191,7 @@ See `Rule File Syntax`_ for a formal description.
Example 1 - *default* fuzzy rule
A rule that matches many dependencies on dev-lang/R, for example
- "r 2.12", "R(>= 2.14)", "R [<2.10]", "r{ !2.12 }", and "R", and
+ "r 2.12", "R(>= 2.14)", "R [<2.10]", "r{ !=2.12 }", and "R", and
resolves them as '>=dev-lang/R-2.12', '>=dev-lang/R-2.14',
'<dev-lang/R-2.10', etc.:
@@ -1239,6 +1240,25 @@ Example 4 - *ignore* simple rule
Will use djmrgl or rgl packages for rendering if present
}
+Example 5 - fuzzy slot rule
+ A rule that matches many dependencies on sci-libs/fftw and resolves them
+ as slotted depencency:
+
+ .. code-block:: text
+
+ ~sci-libs/fftw: :: fftw
+
+Example 6 - slot-restricted fuzzy slot rule
+ Similar to example 5, but this rule does not resolve anything unless the
+ calculated slot is allowed.
+
+ .. code-block:: text
+
+ ~sci-libs/fftw:2.1,3.0: :: fftw
+
+ .. caution::
+
+ TODO! (only integers accepted)
Please see the default rule files for more extensive examples that cover
other aspects like limiting a rule to certain dependency types.
@@ -1307,14 +1327,13 @@ Dependencies
Dependency strings cannot start with *~* as it is a keychar.
Use braces *( ~... )* to work around that.
-
Single line rules
resolve exactly one *dependency string*. Their rule separator is ' :: '.
Syntax:
.. code:: text
- [<keychar>]<dependency> :: <dependency string>
+ [<keychar>]<dependency>[<rule options>] :: <dependency string>
Multi line rules
resolve several *dependency strings*.
@@ -1324,7 +1343,7 @@ Multi line rules
Syntax:
.. code-block:: text
- [<keychar>]<dependency> {
+ [<keychar>]<dependency>[<rule options>] {
<dependency string>
[<dependency string>]
...
@@ -1336,6 +1355,42 @@ Multi line rules
zero or more *dependency strings*. An empty rule makes little sense,
though.
+Rule Options
+ Certain rule types accept options that control the rule's behavior.
+ For example, *default* fuzzy rules can be set up to yield slotted
+ dependencies.
+
+Fuzzy Slot Rules
+ <<TODO>>
+
+ Fuzzy Slot rules are a subtype of *default* fuzzy rules. Appending a colon
+ character ``:`` to the *dependency string* of a fuzzy rules
+ (as *rule option*) turns it into a slot rule.
+
+ Fuzzy slot rules accept even more options:
+
+ * accepted slot values can be restricted (integer range or list)
+ * *version,slot-relative* matches can be enabled (example, <<TODO>>: ``>=${CATEGORY}/${PN}-${PV}:${SLOT}${SLOT_SUFFIX-}``)
+ * a *slot suffix* can be specified (e.g. for using *Atom Slot Operators*)
+
+ .. code-block:: text
+
+ fuzzy slot options := [:<slot restrict>]:{+<flag>}[<slot suffix>]
+ flag := v
+ slot restrict := <restrict range> | <restrict list>
+ restrict range := [<number>]..[<number>]
+ restrict list := <number>{,<number>}
+
+ # slot suffix can be any string that starts with '/', '=' or '*'
+ # number is a natural number (0..N)
+
+
+
+ .. Note::
+
+ Fuzzy Slot rules cannot resolve "not <version>" statements, e.g.
+ "R ( != 2.14 )".
+
Comments
start with **#**. There are a few exceptions to that, the *#deptype* and
*#! NOPARSE* keywords. Comments inside rule blocks are not allowed and
@@ -1380,7 +1435,7 @@ Rule Stubs
Syntax:
.. code:: text
- [<keychar>]<short dependency>
+ [<keychar>]<short dependency>[<rule options>]
===============
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-07-03 10:04 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-07-03 10:04 UTC (permalink / raw
To: gentoo-commits
commit: 1e797b7bcafc6b364190961ef74b63febe10b9e9
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Jul 3 09:57:49 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Jul 3 09:57:49 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=1e797b7b
doc/rst: SLOT handling
---
doc/rst/usage.rst | 53 +++++++++++++++++++++++++++++++----------------------
1 file changed, 31 insertions(+), 22 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index f3e2e18..54ed6d3 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1242,11 +1242,15 @@ Example 4 - *ignore* simple rule
Example 5 - fuzzy slot rule
A rule that matches many dependencies on sci-libs/fftw and resolves them
- as slotted depencency:
+ as slotted depencency. The ``s=<range>`` option controls which parts of the
+ version (from the dependency string) are relevant for calculating the
+ slot. The following example resolves "fftw 2.1", "fftw 2.1.2" and
+ "fftw 2.1.3" as "sci-libs/fftw:2.1", "fftw 3.0" as "sci-libs/fftw:3.0"
+ and so on:
.. code-block:: text
- ~sci-libs/fftw: :: fftw
+ ~sci-libs/fftw:s=0..1 :: fftw
Example 6 - slot-restricted fuzzy slot rule
Similar to example 5, but this rule does not resolve anything unless the
@@ -1254,11 +1258,17 @@ Example 6 - slot-restricted fuzzy slot rule
.. code-block:: text
- ~sci-libs/fftw:2.1,3.0: :: fftw
+ ~sci-libs/fftw:s=0..1:restrict=2.1,3.0: :: fftw
- .. caution::
+Example 7 - slot-restricted fuzzy slot rule with *immediate* value
+ Example 6 is not quite correct, as sci-libs/fftw currently uses slot 3.0
+ for various versions from the 3.x range. The following rule resolves
+ "fftw 3.0", ..., "fftw 3.3" as "sci-libs/fftw:3.0":
+
+ .. code-block:: text
+
+ ~sci-libs/fftw:s=i3.0:restrict=3.0,3.1,3.2,3.3 :: fftw
- TODO! (only integers accepted)
Please see the default rule files for more extensive examples that cover
other aspects like limiting a rule to certain dependency types.
@@ -1361,30 +1371,29 @@ Rule Options
dependencies.
Fuzzy Slot Rules
- <<TODO>>
-
Fuzzy Slot rules are a subtype of *default* fuzzy rules. Appending a colon
- character ``:`` to the *dependency string* of a fuzzy rules
+ character ``:`` to the *dependency string* of a fuzzy rule
(as *rule option*) turns it into a slot rule.
- Fuzzy slot rules accept even more options:
-
- * accepted slot values can be restricted (integer range or list)
- * *version,slot-relative* matches can be enabled (example, <<TODO>>: ``>=${CATEGORY}/${PN}-${PV}:${SLOT}${SLOT_SUFFIX-}``)
- * a *slot suffix* can be specified (e.g. for using *Atom Slot Operators*)
-
- .. code-block:: text
+ Fuzzy slot rules accept even more options, each of them separated by one
+ colong char ``:``:
- fuzzy slot options := [:<slot restrict>]:{+<flag>}[<slot suffix>]
- flag := v
- slot restrict := <restrict range> | <restrict list>
- restrict range := [<number>]..[<number>]
- restrict list := <number>{,<number>}
+ * slot mode:
- # slot suffix can be any string that starts with '/', '=' or '*'
- # number is a natural number (0..N)
+ * ``default``: calculate a slot value (``<cat>/<pkg>:<SLOT>``)
+ * ``with_version`` or ``+v``: include version, too (``=<cat>/<pkg>-<pkgver>:<SLOT>``)
+ * ``open``: non-versioned slot (``<cat>/<pkg>:*`` or ``<cat>/<pkg>:=``)
+ * accepted *calculated* slot values can be restricted with
+ ``restrict=<list of accepted values`` or ``r=<list>``
+ * relevant slot parts can be set with ``slotparts=<selection>`` or
+ ``s=<selection>``
+ * relevant subslot parts can be set with ``subslotparts=<selection>`` or
+ ``/<selection>``
+ * slot operator can be set to ``*`` or ``=``
+ ``<selection>`` can be an index (integer) range
+ ``[<low>:=0]..[<high>:=<low>]`` or a fixed value ``i<value>``.
.. Note::
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:master commit in: doc/rst/
@ 2013-07-03 10:05 André Erdmann
2013-06-28 17:18 ` [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
0 siblings, 1 reply; 12+ messages in thread
From: André Erdmann @ 2013-07-03 10:05 UTC (permalink / raw
To: gentoo-commits
commit: 22b1e80c37192d3049f95293cedd03b30ca2c7d2
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Jun 28 17:16:32 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Jun 28 17:16:32 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=22b1e80c
doc/rst: SLOT handling (incomplete)
Draft for documentation about fuzzy slot rules.
(No doc/html commit will be created since documentation is todo.)
---
doc/rst/usage.rst | 69 +++++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 62 insertions(+), 7 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 2daedce..f3e2e18 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1160,7 +1160,8 @@ Simple Rules
Fuzzy Rules
Fuzzy Rules are **extended Simple Rules**. If the basic lookup
as described above fails for a *dependency string*,
- they will *try* to resolve it as a **version-relative match**.
+ they will *try* to resolve it as a **version-relative**,
+ **slot-relative** or **version,slot-relative match**.
To do this, the *dependency string* will be split into components like
*dependency name*, *dependency version* and useless comments, which are
@@ -1177,7 +1178,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-2.10 dev-lang/R )"
+ * "R ( !=2.10 )" as "( !=dev-lang/R-2.10 dev-lang/R )"
++++++++++++++++++++
@@ -1190,7 +1191,7 @@ See `Rule File Syntax`_ for a formal description.
Example 1 - *default* fuzzy rule
A rule that matches many dependencies on dev-lang/R, for example
- "r 2.12", "R(>= 2.14)", "R [<2.10]", "r{ !2.12 }", and "R", and
+ "r 2.12", "R(>= 2.14)", "R [<2.10]", "r{ !=2.12 }", and "R", and
resolves them as '>=dev-lang/R-2.12', '>=dev-lang/R-2.14',
'<dev-lang/R-2.10', etc.:
@@ -1239,6 +1240,25 @@ Example 4 - *ignore* simple rule
Will use djmrgl or rgl packages for rendering if present
}
+Example 5 - fuzzy slot rule
+ A rule that matches many dependencies on sci-libs/fftw and resolves them
+ as slotted depencency:
+
+ .. code-block:: text
+
+ ~sci-libs/fftw: :: fftw
+
+Example 6 - slot-restricted fuzzy slot rule
+ Similar to example 5, but this rule does not resolve anything unless the
+ calculated slot is allowed.
+
+ .. code-block:: text
+
+ ~sci-libs/fftw:2.1,3.0: :: fftw
+
+ .. caution::
+
+ TODO! (only integers accepted)
Please see the default rule files for more extensive examples that cover
other aspects like limiting a rule to certain dependency types.
@@ -1307,14 +1327,13 @@ Dependencies
Dependency strings cannot start with *~* as it is a keychar.
Use braces *( ~... )* to work around that.
-
Single line rules
resolve exactly one *dependency string*. Their rule separator is ' :: '.
Syntax:
.. code:: text
- [<keychar>]<dependency> :: <dependency string>
+ [<keychar>]<dependency>[<rule options>] :: <dependency string>
Multi line rules
resolve several *dependency strings*.
@@ -1324,7 +1343,7 @@ Multi line rules
Syntax:
.. code-block:: text
- [<keychar>]<dependency> {
+ [<keychar>]<dependency>[<rule options>] {
<dependency string>
[<dependency string>]
...
@@ -1336,6 +1355,42 @@ Multi line rules
zero or more *dependency strings*. An empty rule makes little sense,
though.
+Rule Options
+ Certain rule types accept options that control the rule's behavior.
+ For example, *default* fuzzy rules can be set up to yield slotted
+ dependencies.
+
+Fuzzy Slot Rules
+ <<TODO>>
+
+ Fuzzy Slot rules are a subtype of *default* fuzzy rules. Appending a colon
+ character ``:`` to the *dependency string* of a fuzzy rules
+ (as *rule option*) turns it into a slot rule.
+
+ Fuzzy slot rules accept even more options:
+
+ * accepted slot values can be restricted (integer range or list)
+ * *version,slot-relative* matches can be enabled (example, <<TODO>>: ``>=${CATEGORY}/${PN}-${PV}:${SLOT}${SLOT_SUFFIX-}``)
+ * a *slot suffix* can be specified (e.g. for using *Atom Slot Operators*)
+
+ .. code-block:: text
+
+ fuzzy slot options := [:<slot restrict>]:{+<flag>}[<slot suffix>]
+ flag := v
+ slot restrict := <restrict range> | <restrict list>
+ restrict range := [<number>]..[<number>]
+ restrict list := <number>{,<number>}
+
+ # slot suffix can be any string that starts with '/', '=' or '*'
+ # number is a natural number (0..N)
+
+
+
+ .. Note::
+
+ Fuzzy Slot rules cannot resolve "not <version>" statements, e.g.
+ "R ( != 2.14 )".
+
Comments
start with **#**. There are a few exceptions to that, the *#deptype* and
*#! NOPARSE* keywords. Comments inside rule blocks are not allowed and
@@ -1380,7 +1435,7 @@ Rule Stubs
Syntax:
.. code:: text
- [<keychar>]<short dependency>
+ [<keychar>]<short dependency>[<rule options>]
===============
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-07-15 22:31 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-07-15 22:31 UTC (permalink / raw
To: gentoo-commits
commit: e09da4f72660a0e564b57c9439f9dddaaf7c9186
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Mon Jul 15 22:31:14 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Mon Jul 15 22:31:14 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=e09da4f7
doc/rst: selfdep validation, add TODO sections
---
doc/rst/usage.rst | 128 ++++++++++++++++++++++++++++++++++++++++++------------
1 file changed, 100 insertions(+), 28 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 54ed6d3..36fa031 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -85,11 +85,13 @@ Expected prior knowlegde:
* argparse (http://code.google.com/p/argparse)
+* setuptools (http://pypi.python.org/pypi/setuptools)
+
* rsync (for using rsync repositories)
* for Manifest creation:
- * portage (*ebuild* and/or the *portage libs* directly)
+ * portage (*ebuild*)
* *true* or *echo* from coreutils or busybox for preventing
package downloads during Manifest creation (optional)
@@ -110,7 +112,7 @@ Expected prior knowlegde:
using a slower one.
time
- Expect 3-6h execution time for the first run, depending on computing
+ Expect 1h execution time for the first run, depending on computing
and I/O speed. *roverlay* is able to work in incremental mode,
thus making subsequent runs need a lot less time.
@@ -211,6 +213,17 @@ 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"``).
+If roverlay has been installed, then ``emerge --config roverlay`` can be
+used to set up the config file as well as to create essential directories.
+It can be run multiple times in order to configure roverlay for more than
+one user.
+
+.. Important::
+
+ ``emerge --config roverlay`` will overwrite the user's config file (or
+ /etc/roverlay/R-overlay.conf when configuring for root).
+
+
The following options should be set before running *roverlay*:
OVERLAY_DIR
@@ -350,6 +363,10 @@ have reasonable defaults if *roverlay* has been installed using *emerge*:
Example: DISTDIR_FLAT = yes
+ PORTDIR
+ Portage directory, which is used to scan for valid licenses.
+
+ Example: PORTDIR = /usr/portage
There is another option that is useful for creating new dependency rules,
LOG_FILE_UNRESOLVABLE_, which will write all unresolvable dependencies
@@ -569,6 +586,9 @@ These are the steps that *roverlay* performs:
* **immediately stop** processing *p* if a *required* dependency
cannot be resolved in which case a valid ebuild cannot be created
+ * verify dependencies on packages found in the overlay, whether their
+ ebuilds already exist or not (*selfdep validation*)
+
See also: `Dependency Resolution`_
* create an ebuild for *p* by using the dependency resolution results
@@ -1106,11 +1126,6 @@ Ebuilds imported that way can not be overwritten by generated ebuilds and
benefit from most overlay creation features, e.g. Manifest file creation.
However, they cannot be used for metadata creation.
-.. Important::
-
- Importing ebuilds is only supported by the default Manifest implementation
- (*ebuildmanifest*).
-
==================
Dependency Rules
@@ -1314,6 +1329,15 @@ Keywords
* *all* (no type restrictions)
* *pkg* (resolve only R package dependencies)
* *sys* (resolve only system dependencies)
+ * *selfdep* (subtype: dependency is part of the overlay, see selfdep below)
+
+ The dependency type can also be a comma-separated list of the listed types.
+ Actually, *all* is an abbreviated version of ``pkg,sys``.
+ Specifying *selfdep* alone does not resolve anything.
+
+ .. Hint::
+
+ Check the *dependency type* if a newly added rule has no effect.
The other keyword is *#! NOPARSE* which stops parsing of a rule file.
@@ -1406,16 +1430,28 @@ Comments
will be read as normal *dependency strings*.
Selfdep
- This is another name for *dependency strings* that are resolved by an
- R package with the same name, which is also part of the overlay being
- created.
+ This is a classification for dependencies on packages which are also part
+ of the overlay being created. Typically, selfdeps refer to other R
+ packages, but there may be a few exceptions.
+
+ roverlay validates *selfdeps* during overlay creation, which is the most
+ significant difference to non-*selfdeps*.
+
+ Selfdep rules can be written by prefixing a single rule with ``@selfdep``
+ (in a separate text line) or by adding ``selfdep`` to the dependency rule
+ type.
+
+
+ There is a second variant of selfdeps, *true selfdeps*, which resolve
+ a *dependency string* as R package with the same name.
+
- Example: *zoo* is resolved as *sci-R/zoo*, assuming that `OVERLAY_CATEGORY`_
- is set to *sci-R*
+ Example: *zoo* is resolved as *sci-R/zoo*, assuming that
+ `OVERLAY_CATEGORY`_ is set to *sci-R*.
- Writing selfdep rules is not necessary since *roverlay* automatically
- creates rules for all known R packages (see `Dynamic Selfdep Rule Pool`_
- for details).
+ Writing such selfdep rules is not necessary since *roverlay* automatically
+ creates rules for all known R packages at runtime (see
+ `Dynamic Selfdep Rule Pool`_ for details).
There are a few exceptions to that in which case selfdep rules have to
be written:
@@ -1424,15 +1460,10 @@ Selfdep
R package). This is likely a "bug" in the DESCRIPTION file of the
R package being processed.
- * The R package name is not ebuild-name compliant (e.g. contains the '.'
- char, which is remapped to '_'.).
- Most *char remap* cases are handled properly, but there may be a few
- exceptions.
-
.. Caution::
- Writing unnecessary selfdep rules slows dependency resolution down!
- Each rule will exist twice, once as *dynamic* rule and once as
+ Writing unnecessary *true selfdep* rules slows dependency resolution
+ down! Each rule will exist twice, once as *dynamic* rule and once as
the written one.
@@ -2524,10 +2555,12 @@ OVERLAY_KEEP_NTH_LATEST
OVERLAY_MANIFEST_IMPLEMENTATION
Sets the implementation that will be used for Manifest file writing.
- Available choices are *ebuild*, *portage*, *default* and *none*.
- Defaults to *default* (-> *ebuild*).
- *portage* is highly experimental and therefore not recommended
- for production usage.
+ Available choices are *ebuild*, *next*, *default* and *none*.
+ Defaults to *default* (-> *next*).
+
+ *next* is an mostly internal implementation that is considerably faster
+ than *ebuild*. *ebuild* is still used when creating Manifest files for
+ imported ebuilds.
.. Note::
@@ -2966,6 +2999,13 @@ Known field flags:
Declares that a field's value is a list whose values are separated by
whitespace. Has no effect if `field flag: isList` is set.
+ .. _field flag\: isLicense:
+
+ isLicense
+ Declares that a field's value should be interpreted as license string.
+ This disables *allowed_value*/*allowed_values* and all other flags
+ except for *mandatory*/*optional*.
+
.. _field flag\: mandatory:
.. _'mandatory' field flag:
@@ -3162,6 +3202,14 @@ Example Session:
cmd % exit
+====================
+ Roverlay Interface
+====================
+
+<<TODO: stub only>>
+
+API to roverlay functionality. Currently supports dependency resolution.
+
=========================
Implementation Overview
=========================
@@ -3353,6 +3401,8 @@ for which an ebuild has been created.
Manifest Creation
+++++++++++++++++++
+<<TODO:this section is totally out of date>>
+
Manifest files are created by calling the *ebuild* executable for each
package directory in a filtered environment where FETCHCOMMAND and
RESUMECOMMAND are set to no-operation. The directories that contain the R
@@ -3374,6 +3424,14 @@ It does the following steps:
#. Call `dependency resolution`_
+#. If dependency resolution was successful and any *selfdeps* found
+ (dependencies on other packages): *pause* ebuild creation for *p* until
+ it has been verified whether these dependencies are satisfiable.
+ This is necessary because dependency resolution does not know whether a
+ resolved dependency is actually valid. To realize this, *roverlay* collects
+ paused ebuild creation jobs after processing all packages, performs
+ *selfdep validation* and then continues ebuild creation.
+
#. If dependency resolution was successful, dependency ebuild variables are
created (*DEPEND*, *RDEPEND* and *R_SUGGESTS*, also *IUSE*, *MISSINGDEPS*).
Otherwise **ebuild creation stops** and *p* is marked as
@@ -3414,6 +3472,13 @@ 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.
+++++++++++++++++++++
+ Selfdep Validation
+++++++++++++++++++++
+
+<<TODO: specify algo here>>
+
+
-----------------------
Dependency Resolution
-----------------------
@@ -3467,6 +3532,13 @@ System Dependency
This declares that the *dependency string* could be a system dependency,
e.g. a scientific library or a video encoder.
+Selfdep
+ This declares that the resolved dependency has to pass
+ *selfdep validation*. While *selfdep* usually implies *package*, these
+ types are not the same. The *package* type is applied to *dependency strings*
+ based on their origin (DESCRIPTION field), whereas *selfdep* is a property
+ of the resolving rule.
+
Try other dependency types
This declares that the *dependency string* can be resolved by ignoring its
dependency type partially. This property allows to resolve package
@@ -3602,8 +3674,8 @@ R packages" to create rules.
.. _Dynamic Selfdep Rule Pool:
*roverlay* uses one dynamic rule pool, the **Dynamic Selfdep Rule Pool**.
-This pool contains rules for all known R packages and is able to resolve
-R package dependencies.
+This pool contains *selfdep* rules for all known R packages and is able
+to resolve R package dependencies.
By convention, it will never resolve any system dependencies.
+++++++++++++++++++++++++++++
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-07-16 16:35 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-07-16 16:35 UTC (permalink / raw
To: gentoo-commits
commit: d7db304d7a087f04613cc0d62cf0d39504311f14
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Jul 16 16:33:22 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Jul 16 16:33:22 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=d7db304d
doc/rst: api, manifest creation
---
doc/rst/usage.rst | 77 +++++++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 67 insertions(+), 10 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 36fa031..df18824 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -2311,8 +2311,6 @@ CACHEDIR
This option is **required**.
- <<TODO: default value!>>
-
.. _DISTFILES:
DISTFILES
@@ -3206,9 +3204,63 @@ Example Session:
Roverlay Interface
====================
-<<TODO: stub only>>
+Roverlay provides an API for accessing its functionality independently of
+R overlay creation. Only dependency resolution is available, currently.
+
+Note, however, that a minimal config file may still be required for accessing
+*roverlay interfaces*.
+
+The table below lists all interfaces and where to find them:
+
+.. table:: roverlay interfaces
+
+ +-----------------+---------------------------+-----------------------------+
+ | name | module | description |
+ +=================+===========================+=============================+
+ | RootInterface | roverlay.interface.root | meta interface for managing |
+ | | | other interfaces |
+ +-----------------+---------------------------+-----------------------------+
+ | MainInterface | roverlay.interface.main | RootInterface with delayed |
+ | | | initialization |
+ +-----------------+---------------------------+-----------------------------+
+ | DepresInterface | roverlay.interface.depres | dependency resolution |
+ +-----------------+---------------------------+-----------------------------+
+
+
+For extending the API, roverlay provides the abstract *RoverlayInterface* and
+*RoverlaySubInterface* classes.
+
+
+------------------
+ DepRes Interface
+------------------
+
+The *DepResInterface* offers the following functionality:
+
+* rule creation
+
+ * load rules from text input, files and/or configured files (SIMPLE_RULES_FILE_)
+
+ * *compile* rules after loading them
+
+* manage dependency rule pools (container for rules)
+
+ * rule pools are kept in a stack-like data structure, which makes it easy
+ to "forget" the most recent rules (*discard_pool()* et al.)
-API to roverlay functionality. Currently supports dependency resolution.
+ * *visualize* pools: convert rules into text (inverse of rule creation)
+
+* easy access to the resolver via *resolve()*, *can_resolve()*
+ and *cannot_resolve()*
+
+* "low-level" access to dependency resolution, e.g. *EbuildJobChannels*, is
+ 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.)
=========================
Implementation Overview
@@ -3401,13 +3453,18 @@ for which an ebuild has been created.
Manifest Creation
+++++++++++++++++++
-<<TODO:this section is totally out of date>>
+Two implementations for writing manifest files are available, *ebuild* and
+*next*.
+
+The *ebuild* implementation calls the ``ebuild`` executable for each package
+directory in a filtered environment where where FETCHCOMMAND and
+RESUMECOMMAND are set to no-operation (/bin/true on systems that support it).
-Manifest files are created by calling the *ebuild* executable for each
-package directory in a filtered environment where FETCHCOMMAND and
-RESUMECOMMAND are set to no-operation. The directories that contain the R
-package files are passed in the PORTAGE_RO_DISTDIRS variable and DISTDIR
-is set to `DISTFILES_ROOT`_/__tmp__.
+*next* is an internal implementation that uses the
+``roverlay.overlay.pkgdir.manifest`` module for creating Manifest files.
+It falls back to *ebuild* when creating Manifest entries for imported ebuilds,
+since roverlay does not support reading *SRC_URI* from ebuilds reliably (that
+would require variable interpolation, e.g. for ``${PN}``).
-----------------
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-07-23 14:57 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-07-23 14:57 UTC (permalink / raw
To: gentoo-commits
commit: c9055b8a4cc87a7518710bd7a2ff7a1f57ad97ee
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Jul 23 14:30:05 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Jul 23 14:30:42 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=c9055b8a
doc/rst: "fix" example 3 in dependency rules
Due to changes in the depresolver, the old example does no longer work.
---
doc/rst/usage.rst | 11 ++++-------
1 file changed, 4 insertions(+), 7 deletions(-)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index df18824..01c3411 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -1230,16 +1230,13 @@ Example 2 - *default* simple rule stub
be resolved. See *Selfdep* in `Rule File Syntax`_ for details.
Example 3 - *default* simple rule
- A rule that matches several *dependency strings* and resolves them
- as "sci-libs/gdal and sci-libs/proj":
+ A rule that matches a *dependency string* and resolves it
+ as "virtual/blas and virtual/lapack":
.. code-block:: text
- ( sci-libs/gdal sci-libs/proj ) {
- for building from source: GDAL >= 1.3.1 && GDAL < 1.6.0 (until tested) library and PROJ.4 (proj >= 4.4.9)
- for building from source: GDAL >= 1.3.1 library and PROJ.4 (proj >= 4.4.9)
- for building from source: GDAL >= 1.3.1 library and PROJ.4(proj >= 4.4.9)
- for building from source: GDAL >= 1.6.0 library and PROJ.4(proj >= 4.4.9)
+ ( virtual/blas virtual/lapack ) {
+ BLAS/LAPACK libraries
}
Example 4 - *ignore* simple rule
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/
@ 2013-07-23 18:34 André Erdmann
0 siblings, 0 replies; 12+ messages in thread
From: André Erdmann @ 2013-07-23 18:34 UTC (permalink / raw
To: gentoo-commits
commit: 1dc64039a45eb41f785f9f64a4ddbf9464e018ba
Author: André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Jul 23 18:33:54 2013 +0000
Commit: André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Jul 23 18:33:54 2013 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=1dc64039
doc/rst: add hook environment changes
---
doc/rst/usage.rst | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 55 insertions(+)
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 01c3411..204de09 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -542,6 +542,43 @@ to symbolic links if hard links are not supported. This should be fine in
most cases, but fine-tuning can be done via OVERLAY_DISTDIR_STRATEGY_ and
OVERLAY_DISTDIR_FLAT_.
+------------------
+ 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:
+
+ .. code-block:: sh
+
+ #!/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.
+
+
+
+
===============================
Basic Implementation Overview
===============================
@@ -2027,6 +2064,8 @@ the config file. An empty string sets the policy to *deny all*.
+----------------+-------------------+-----------------------------------------+
| ROVERLAY_PHASE | event | event that caused the script to run |
+----------------+-------------------+-----------------------------------------+
+ | OVERLAY_NAME | config | name of the overlay |
+ +----------------+-------------------+-----------------------------------------+
| OVERLAY | config | overlay directory (`OVERLAY_DIR`_), |
+----------------+-------------------+ initial working directory |
| S | *$OVERLAY* | |
@@ -2046,6 +2085,9 @@ the config file. An empty string sets the policy to *deny all*.
+----------------+-------------------+ |
| FILESDIR | *$ADDITIONS_DIR* | |
+----------------+-------------------+-----------------------------------------+
+ | WORKDIR | config | directory for work data |
+ | | | (`CACHEDIR`_) |
+ +----------------+-------------------+-----------------------------------------+
| SHLIB | *$ADDITIONS_DIR*, | A list of directories with shell |
| | *installed?* | function files |
| | | (optional, only set if any dir exists) |
@@ -2053,6 +2095,19 @@ the config file. An empty string sets the policy to *deny all*.
| FUNCTIONS | *$ADDITIONS_DIR*, | file with essential shell functions |
| | *installed?* | (optional, only set if it exists) |
+----------------+-------------------+-----------------------------------------+
+ | DATADIR | *installed?* | location of installed data files |
+ | | | (directory, usually |
+ | | | */usr/share/roverlay*) |
+ +----------------+-------------------+-----------------------------------------+
+ | ROVERLAY\ | sys.argv | path to the roverlay executable that |
+ | _HELPER_EXE | | created the hook environment |
+ | | | (usually */usr/bin/roverlay* or |
+ | | | */usr/bin/roverlay-sh*) |
+ +----------------+-------------------+-----------------------------------------+
+ | ROVERLAY_EXE | guessed, | guessed path to the roverlay "main" |
+ | | *$ROVERLAY\ | executable (which creates the overlay) |
+ | | _HELPER_EXE* | |
+ +----------------+-------------------+-----------------------------------------+
| DEBUG | log level | *shbool* (``y`` or ``n``) that |
| | | indicates whether debug messages should |
| | | be printed |
^ permalink raw reply related [flat|nested] 12+ messages in thread
end of thread, other threads:[~2013-07-23 18:34 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-07-03 10:05 [gentoo-commits] proj/R_overlay:master commit in: doc/rst/ André Erdmann
2013-06-28 17:18 ` [gentoo-commits] proj/R_overlay:gsoc13/next " André Erdmann
-- strict thread matches above, loose matches on Subject: below --
2013-07-23 18:34 André Erdmann
2013-07-23 14:57 André Erdmann
2013-07-16 16:35 André Erdmann
2013-07-15 22:31 André Erdmann
2013-07-03 10:04 André Erdmann
2013-06-26 17:29 André Erdmann
2013-06-25 21:10 André Erdmann
2013-06-18 14:12 André Erdmann
2013-06-12 21:10 André Erdmann
2013-06-05 18:08 André Erdmann
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox