path: root/man/roverlay-deprules.5

.\" groff -Tascii -man
.TH "ROVERLAY-DEPRULES" "5" "July 10 2012" "Linux/Gentoo?" "R Overlay"
.SH "NAME"
deprules \- R overlay dependency rule configuration
.SH "SYNOPSIS"
\fBsimple-deprules.conf\fR
.SH "DESCRIPTION"
A simple dependency rule file defines one or more rules
that are used for dependency resolution in \fBroverlay(1)\fR.
.PP
A rule defines which \fIdep_string\fR read from an R package resolves
to a specific \fIdependency\fR.
\fIdependency\fR can be a \fBDEPEND atom\fR or \fBDynamic DEPEND\fR,
see \fBebuild(5)\fR.
\'The R programming language\',
for example, should resolve to \'dev\-lang/R\'.
Other dependencies such as packages from @system,
should be ignored since they\'re always provided.
This is also possible.

.IP "\(bu simple rules"
These rules are very simple and match a \fIdep_string\fR exactly.
.IP "\(bu fuzzy rules"
These rules try to find a match for \fIdep_string\fR using string interpolation, metrics and/or regex matches.
.SS "RULE VARIANTS"
.IP "\(bu normal"
\fIdep_string\fR will be resolved as \fIdependency\fR.
.IP "\(bu ignore"
\fIdep_string\fR will be ignored if it matches an ignore rule.

.SS "RULE STUBS"
There\'s a special (shorter) syntax for dependencies
that are resolved within the created overlay.
For example, if your \fIOVERLAY_CATEGORY\fR is \'sci\-R\',
\'zoo\' should be resolved as \'sci\-R/zoo\'.
This rule can be written as a single word, \'zoo\'.
The advantage is that you don\'t have to write the
overlay category into the rule file.
These stubs are called \fBselfdeps\fR.


.SS "BASIC SYNTAX"
.IP "\(bu rule that matches one \fIdep_string\fR"
[\fIkeyword\fR and/or \fIdependency\fR] :: \fIdep_string\fR
.br
.IP "\(bu rule that matches multiple \fIdep_string\fRs"
This replaces " :: \fIdep_string\fR" by a multiline variant
.br
[\fIkeyword\fR and/or \fIdependency\fR] \&{
.br
\& \fIdep_string\fR
.br
\& [\fIdep_string\fR]
.br
\& [\fIdep_string\fR]
.br
\& \&.\&.\&.
.br
\&}
.br
.IP "\fBselfdep\fR rule"
[\fIkeyword\fR]\fIshort_dependency\fR
.br
where \fIshort_dependency\fR is a package name (\fBDEPEND atom\fR without version, category).
This is the only way to specify selfdeps.

.SS "ADDITIONAL SYNTAX"
Comments start with \'#\', with a few exceptions:
.TP
dependency type
There's a keyword to set the dependency type of all rules following this statement,
\'#deptype <type>\' where type is \'sys\', \'pkg\' or \'all\'.
.TP
stop reading
There are two special keywords that both cause reading a rule file to stop, \'#! BREAKPARSE\' and \'#! NOPARSE\'.
The line must exactly be one of these keywords (no additional content at the end of the line).



.SH "SIMPLE RULES"
A simple rule resolves exact string matches (case-insensitive).
.SS "SYNTAX"
.IP "\(bu normal"
\fIdependency\fR :: \fIdep_string\fR
.IP "\(bu ignore"
! :: \fIdep_string\fR
.IP "\(bu selfdep, normal"
\fIshort_dependency\fR
.IP "\(bu selfdep, ignored"
!\fIshort_dependency\fR

.SH "FUZZY RULES"
A fuzzy rule tries to resolve, i.e. "resolve \fIdep_string\fR as \fIdependency\fR if it \fIsomehow\fR matches a \fIfuzzy_string\fR".
The \fIsomehow\fR is up to the implementation, it currently includes:
.SS "EXACT MATCH"
This is equal to the \fBSIMPLE RULES\fR
.SS "VERSION\-RELATIVE MATCH"
Uses regexes to identify \fIdep_string\fRs
that only differ in the requested version (and/or version syntax).
"R (\&>\&= 2.15)" and "R[2.10]", for instance, should be resolved as "dev\-lang/R".
A single fuzzy\-rule "~dev\-lang/R :: R" does this and resolves them as
"\&>=dev\-lang/R\-2.15" and "\&>=dev\-lang/R\-2.10", respectively.
Note that this is just an example, \fBroverlay(1)\fR will filter out dependencies on
dev\-lang/R when the version is \&<= the lowest version available in portage.
.br
In detail, this method matches if
.br
\& \fIdep_string\fR ~= \fIfuzzy_string\fR \&<\fIversion_statement\fR\&>,
.br
where \fIversion_statment\fR is something like \&>=2.10, \&!=0.9, 1.0, \&<5,
optionally enclosed with braces ((), [], {}).
Whitespace is ignored unless \fIversion_statment\fR is not enclosed,
in which case some whitespace (more than zero chars) must exist between
\fIfuzzy_string\fR and \fIversion_statment\fR.

.SS SYNTAX
Fuzzy rules use ~ and % as keyword.
.IP "\(bu normal"
\&~\fIdependency\fR :: \fIfuzzy_string\fR
.IP "\(bu ignore"
\&%\fIdependency\fR :: \fIfuzzy_string\fR
.IP "\(bu selfdep"
\&~\fIshort_dependency\fR
.IP "\(bu selfdep, ignored"
\&%\fIshort_dependency\fR

.SH "EXAMPLES"
Example 1:
.RS 1
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".
.RS 2

\&~dev\-lang/R :: R
.RE
.RE
.PP
Example 2:
.RS 1
A rule that fuzzy-matches a zoo package selfdep.
.RS 2

\&~zoo
.RE
.RE
.PP
Example 3:
.RS 1
A standard self dep, resolves "tuneR", "tuner", ... as "sci\-R/tuneR"
(\fIOVERLAY_CATEGORY\fR/tuneR).
.RS 2

\&tuneR
.RE
.RE
.PP
Example 4:
.RS 1
A simple multiline rule that ignores some text.
This is a good way to deal with free-style text found in
some R package DESCRIPTION files.
.RS 2

! :: {
.RS 2
see README
.br
read INSTALL
.br
[which can be downloaded from http://...]
.br
.RE
}
.RE
.RE

.SH "SEE ALSO"
.BR "roverlay(1)"