From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path:
-
-
+
-
-
-
+
-
+
-
-
-
+
+
-
-
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.
Example: REPO_CONFIG = ~/roverlay/config/repo.list
-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
Directory with an overlay-like structure that contains extra files, e.g. +ebuild patches and hand-written ebuilds.
+Example: ADDITIONS_DIR = ~/roverlay/additions
+The value of this option should point to a field definition file which controls how an R package's DESCRIPTION file is read. @@ -897,6 +908,8 @@ most cases, but fine-tuning can be done via scan the R Overlay directory (if it exists) for valid ebuilds
+import ebuilds from the additions dir
+add - queue all R packages for ebuild creation
all repositories are asked to list their packages which are then added @@ -939,9 +952,9 @@ and may decide to write p's ebuild now (or later)
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
+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):
++# 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:
++<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 ++
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:
++${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).
+Simple dependency rules use a dictionary and string transformations to resolve dependencies. Fuzzy simple dependency rules extend these by a set of regular expressions, which allows to resolve many dependency strings @@ -1309,7 +1384,7 @@ that minimally differ (e.g. only in the required version and/or comments: dictionary entry.
This is the only rule implementation currently available.
A simple rule resolves exact string matches (case-insensitive).
@@ -1361,7 +1436,7 @@ as "<dev-lang/R-2.14"This sections lists some rule file examples. See Rule File Syntax for a formal description.
Simple dependency rule files have a special syntax. Each rule is introduced with the resolving dependency prefixed by a keychar that sets the rule type if required. The dependency strings resolved by this rule are listed @@ -1552,7 +1627,7 @@ as sci-R/zoo. This rule can be written as a single word, zoo.<
Package Rules can be used to control both overlay and ebuild creation. Each package rule consists of conditions, e.g. package name contains amd64, and actions, e.g. set KEYWORDS="-x86 amd64". @@ -1561,7 +1636,7 @@ otherwise the rule does nothing. Moreover, rules can contain further rules which will only take effect if all enclosing rules match a given package.
As stated above, each rule has two parts, a match block that lists the rule's conditions and an action block that defines which actions and nested rules are applied to a package if the rule matches it, i.e. if all @@ -1591,7 +1666,7 @@ The match block ends with the ACTION: Lines starting with # or ; are considered to be comments and will be ignored.
The match block lists one or more conditions, which all must evaluate to true for a certain package, otherwise no actions will be applied. There are two types of conditions, trivial conditions, @@ -1699,7 +1774,7 @@ be replaced with their regex equivalents.
The accepted value is a simple string or a regular expression, which depends on the operator.
Sometimes, a rule should apply its actions to a package if it matches any condition, e.g. package from CRAN or BIOC, or if it does not match a certain condition, e.g. package not from BIOC/experiment.
@@ -1805,7 +1880,7 @@ END;The action block syntax is quite simple. Each action statement starts with an action keyword, optionally followed by one or more values.
Action statement syntax:
@@ -1936,7 +2011,7 @@ more than once is possible, but only the last one will have an effect on ebuild creation.A mentioned before, action blocks can contain nested rules. The syntax is exactly the same as for the normal package rules:
@@ -1964,7 +2039,7 @@ checks necessary for a given package.
A rule that ignores the 'yaqcaffy' package from CRAN, which is also available from BIOC:
@@ -2027,7 +2102,7 @@ END;
The main config file uses '<option> = <value>' syntax, comment lines start with #. Variable substitution ("${X}") is not supported. Quotes around the value are optional and allow to span long values over multiple lines. @@ -2080,7 +2155,7 @@ restrictions. Commenting it out is safe.
The following sections will list all config entries.
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.
+Sets the category of created ebuilds. There are no value type restrictions @@ -2151,7 +2237,7 @@ for this option, but values with a slash / lead to errors.
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.
Defaults to true. @@ -2257,7 +2343,7 @@ writing.
Some config config options are split from the main config file for various reasons:
The date format (ISO8601) used in log messages.
@@ -2340,7 +2426,7 @@ have their own log level.Enables/Disables logging to console. The value has to be a bool.
@@ -2361,7 +2447,7 @@ have their own log level.Sets the log file. File logging will be disabled if this option does not @@ -2420,7 +2506,7 @@ files will be kept.
A directory where all description data read from an R package will be @@ -2439,7 +2525,7 @@ on roverlay exit. Primarily useful for creating new rules.
The field definition file uses ConfigParser syntax and defines how an R package's DESCRIPTION file is read. See the next section, default field definition file, for an example.
@@ -2521,7 +2607,7 @@ such a field is found.It is not checked whether a flag is known or not.
This is the default field definition file (without any ignored fields):
[Description]
@@ -2557,7 +2643,7 @@ such a field is found.
As previously stated, the DepRes Console is only meant for testing. It is an interactive console with the following features:
This chapter gives an in-depth overview of how roverlay works. Code documentation is also available and html pages for it can be created with make pydoc in the R Overlay src directory or by using pydoc directly.
PackageInfo is the data object that contains all information about an R package and is created by the owning repository.
After initialization it contains data like
@@ -2742,7 +2828,7 @@ for it. Otherwise, p is now part of the overlay and has to pass ebuild creation.Repositories are managed in a list-like object, RepoList. Its task is to provide R package input for overlay creation and implements the following functionality:
@@ -2753,7 +2839,7 @@ functionality:The functionality described above is an abstraction layer that calls the respective function for each repository and collects the result. So, while the RepoList object knows what to do for all repositories, @@ -2794,7 +2880,7 @@ subclass-specifc _sync()/_nosync() functions if available. repository types, rsync, websync_repo and websync_pkglist derive from BasicRepo.
Adding new repository types is best done by creating a new repo class that inherits BasicRepo. The table below shows BasicRepo's subclass awareness concerning sync() and what may be changed if required. @@ -2881,7 +2967,7 @@ to be accessible.
The overlay is roverlay's central data structure that represents a portage overlay. It is organized in a tree structure (overlay root, categories, package directories) and implements all overlay-related functionality:
@@ -2912,7 +2998,7 @@ levelmetadata.xml files are created with a tree structure that contains metadata nodes, e.g. '<pkgmetadata>...</pkgmetadata>' and '<use>...</use>' are nodes. The current implementation writes the R package's full description @@ -2921,7 +3007,7 @@ Metadata creation uses the latest package, i.e. highest version, for which an ebuild has been created.
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 @@ -2930,7 +3016,7 @@ is set to DISTFILES_ROOT
Ebuild creation is the process centered around one PackageInfo instance p that tries to create an ebuild for it.
It does the following steps:
@@ -2949,7 +3035,7 @@ order to save memory etc. as ebuild successfully createdEach ebuild variable is an object whose class is derived from the EbuildVar class. An EbuildVar defines its position in the ebuild and how its text output should look like. Ebuild text is created by adding ebuild variables @@ -2957,7 +3043,7 @@ to an Ebuilder that automatically sorts them and creates the ebuild.
Overlay creation is the process of creating an overlay for many R packages and roverlay's main task. More specifically, OverlayCreation is an R packages -> Overlay (-> overlay in filesystem) interface. @@ -2971,7 +3057,7 @@ instead the event is logged. Running more than one OverlayWorker in par is possible.
Each ebuild creation process has access to the dependency resolver that accepts dependency strings, tries to resolve them and returns the result, either "unresolvable" or the resolving dependency as @@ -2993,7 +3079,7 @@ all required dependencies. No ebuild can be created in that case.
Details about dependency resolution like how channels work can be found in the following subsections.
Every dependency string has a dependency type that declares how a dependency should be resolved. It has one or more of these properties:
The DESCRIPTION file of an R package contains several fields that list dependencies on R packages or other software like scientific libraries. This section describes which dependency fields are used and how.
@@ -3081,7 +3167,7 @@ but optional dependencies during the pkg_postinst() ebuild phase.A dependency environment is an object that reflects the whole dependency resolution process of a single dependency string. It usually contains the dependency string, its dependency type, information about its @@ -3091,7 +3177,7 @@ resolving resolving dependency, if any.
dependency resolver.The EbuildJob Channel is used by the ebuild creation to communicate with the dependency resolver. It is initialized by an ebuild creation process and realizes a greedy string to string dependency resolution.
@@ -3128,7 +3214,7 @@ dependencies are unresolvable.The dependency resolver does not know how to resolve a dependency string. Instead, it searches through a list of dependency rule pools that may be able to do this.
@@ -3151,7 +3237,7 @@ R package dependencies. By convention, it will never resolve any system dependencies.The dependency resolver can be extended by modules. Two base types are available, channels and listeners.
The dependency resolver puts all parts of dependency resolution together, rule pools, listeners and channels. Its main task is a loop that processes all queued dependency environments and sends the result back to @@ -3229,7 +3315,7 @@ becomes "loop until resolver closes".