[gentoo-commits] proj/R_overlay:master commit in: man/, /, config/

[André Erdmann]

commit:     02ee937512a9261570b126ca283e4b87de0daa91
Author:     André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Wed Aug  1 21:08:54 2012 +0000
Commit:     André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Wed Aug  1 21:08:54 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=02ee9375

docs

---
 README                  |   24 ++++++++++++++++--------
 config/R-overlay.conf   |    6 ++++++
 config/repo.list        |    2 ++
 man/roverlay-deprules.5 |   12 +++++++++---
 man/roverlay-repo.5     |   39 +++++++++++++++++++++++++++++++++++----
 man/roverlay.1          |    4 ++++
 6 files changed, 72 insertions(+), 15 deletions(-)

diff --git a/README b/README
index 3be012c..40c2201 100644
--- a/README
+++ b/README
@@ -2,15 +2,24 @@ R overlay -- README
 
 == How to use ==
 
-There is currently no "R overlay" script, only modules that implement functionality.
+./roverlay.py [option(s)] [command(s)]
 
-=== Running tests ===
-# <TODO> write this section
+See man/roverlay.1 or ./roverlay.py --help for all options.
 
-Real tests are scheduled for July 10 - July 30.
+=== Running tests ===
 
-A main script is available. See man/roverlay.1 or ./roverlay.py --help for usage.
+Just run the main script, the '--repo-config' option can be used to use
+other repo config files (instead of the default one that downloads ~50GB of packages).
+The '--no-manifest' switch can be used to disable Manifest creation, which saves a
+considerable amount of time at the expense of an unusable overlay
+(but useful to analyze created metadata, ebuild and depres results).
 
+Test run example:
+<<
+#!/bin/sh
+./roverlay.py sync
+time ./main.py --nosync --stats -O /tmp/created_overlay --no-manifest
+>>
 
 == Configuration ==
 
@@ -18,11 +27,10 @@ A main script is available. See man/roverlay.1 or ./roverlay.py --help for usage
 see config/R-overlay.conf
 
 * repo configuration (CRAN,...)
-see config/repo.list
+see man/roverlay-repo.5
 
 * description field configuration
 see config/description_fields.conf
 
 * dependency rules configuration
-see config/simple-deprules.conf
-
+see man/roverlay-deprules.5

diff --git a/config/R-overlay.conf b/config/R-overlay.conf
index 01f0037..a1ba48c 100644
--- a/config/R-overlay.conf
+++ b/config/R-overlay.conf
@@ -134,6 +134,12 @@
 #  * defaults to sci-R
 #OVERLAY_CATEGORY = 'dev-R'
 
+# OVERLAY_KEEP_NTH_LATEST
+#  keep the n-th latest ebuilds per R package, removing all others
+#  * accepted values: integer, has no effect if < 1
+#  * defaults to <unset>, which disables this option (keep all ebuilds)
+#OVERLAY_KEEP_NTH_LATEST = 3
+
 # EBUILD_HEADER
 #  ebuild header file that will be included in all created ebuilds
 # *** NOT IN USE ***

diff --git a/config/repo.list b/config/repo.list
index f389fd7..378c03e 100644
--- a/config/repo.list
+++ b/config/repo.list
@@ -1,6 +1,8 @@
 # repo.list
 #  This file explains how to write repo config files.
 
+# !! out of date, see man/roverlay-repo.5
+
 # This file is parsed used ConfigParser syntax (known from .ini files).
 
 # A repo entry describes

diff --git a/man/roverlay-deprules.5 b/man/roverlay-deprules.5
index e41beda..2af7920 100644
--- a/man/roverlay-deprules.5
+++ b/man/roverlay-deprules.5
@@ -105,10 +105,16 @@ 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\&>,
+\& \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 ((), [], {}).
+where \fIversion_statement\fR ::= [\&<\fIversion_modifier\fR\&>] \&<\fIversion\fR\&>
+.br
+and \fIversion_modifier\fR is one out of \&{\&<, \&>, \&=, \&!, \&<\&=, \&>\&=, \&=\&=, \&!\&=\&}.
+.br
+
+Examples: \&'\&>=2.10\&', \&'\&!=0.9\&', \&'1.0\&', \&'\&<5\&'.
+
+Version statements can optionally be 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.

diff --git a/man/roverlay-repo.5 b/man/roverlay-repo.5
index c8e1270..212aae9 100644
--- a/man/roverlay-repo.5
+++ b/man/roverlay-repo.5
@@ -12,11 +12,11 @@ A repo entry describes where to find R packages that will be used for overlay cr
 and optionally where and how to get the R packages (using \fBREPO TYPES\fR).
 It also defines how ebuilds can download the R packages (used as \fISRC_URI\fR variable in ebuilds).
 .SS "REPO TYPES"
-There are two types of repos, "rsync" and "local" ones:
-.IP "\(bu local repositories"
+There are 4 types of repos, "local", "rsync", "websync_repo" and "websync_pkglist":
+.IP "\(bu local repositories (\&'local\&')"
 A \fBlocal repo\fR represents a directory with R packages in it.
 It will never be modified (i.e. synced) and has no special options.
-.IP "\(bu rsync repositories"
+.IP "\(bu rsync repositories (\&'rsync\&')"
 An \fBrsync repo\fR uses a local directory to sync with a remote.
 Its directory will be modified whenever syncing (using the rsync program).
 It behaves like a local repo if syncing is disabled.
@@ -28,6 +28,17 @@ These rsync options are always passed to rsync:
 \-\-dirs, \-\-prune-empty-dirs, \-\-force, \-\-delete,
 \-\-human-readable, \-\-stats, \-\-chmod=ugo=r,u+w,Dugo+
 \fR
+.IP "\(bu websync repositories (\&'websync_repo\&')"
+A \fBwebsync repo\fR fetches an R package list (deb-control file, typically named PACKAGES)
+from a remote and downloads all packages afterwards (via http). It supports file-size and basic digest
+verification for downloaded packages.
+Nosync mode support for this type of repo is limited, it will report all packages from its
+directory as synced.
+.IP "\(bu package list websync  (\&'websync_pkglist\&')"
+This is not a real repo type, it merely reads package uris from a file
+(one \&'http://...\&' entry per line) and downloads them (via http).
+Package uri entries must end with \&'.tar.gz\&', else ebuild creation is not possible.
+Nosync mode support is limited, all packages that exist locally will be reported as synced.
 .PP
 .SH "VARIABLES"
 Each repository is introduced with [\fIsection_name\fR] and has to declare some options.
@@ -37,7 +48,7 @@ Each repository is introduced with [\fIsection_name\fR] and has to declare some
 This is used to determine the \fISRC_URI\fR variable used in ebuilds.
 \fIuri\fR usually starts with 'http://' which can be left out,
 "localhost/R-packages" is the same uri as "http://localhost/R-packages".
-Always required.
+Always required unless \fItype\fR is websync_pkglist in which case this option has no effect.
 .TP
 .BR "name" " = \fIrepo_name\fR"
 Specify a name for the repository.
@@ -71,6 +82,26 @@ A whitespace-separated list of extra options that will be passed to rsync.
 Useful to in-/exclude files/dirs, show progress while running rsync etc.
 Options must not contain whitespace/quote chars.
 Note that the options won't be verified - this is \fBtotally unsafe!\fR
+.SS "special options for websync repos"
+.TP
+.BR "pkglist_file" " = \fIfilename\fR"
+Name of the package list file that will be downloaded.
+Optional, defaults to \&'PACKAGES\&', which should be fine in
+most cases. Note that reading compressed package lists  (e.g. \&'PACKAGES.gz\&')
+is not supported. Has no effect if \fBpkglist_uri\fR is set.
+.TP
+.BR "pkglist_uri" " = \fIuri\fR"
+Fetch \fIuri\fR and use it as package list.
+Optional, defaults to \fIsrc_uri\fR/\fIpkglist_file\fR.
+.TP
+.BR "digest_type" " = \fIdigest_type\fR"
+Verify downloaded packages using \fIdigest_type\fR.
+Available choices are \&'md5\&' and \&'none\&'. The remote has to support this,
+i.e. list digests in the \fIpkglist_file\fR.
+.SS "special options for package list websync"
+.TP
+.BR "pkglist_file" " = \fIfile\fR"
+Path to the file that lists all package uris.
 .SH "EXAMPLES"
 Example 1:
 .RS 1

diff --git a/man/roverlay.1 b/man/roverlay.1
index 02c78ed..5d34be4 100644
--- a/man/roverlay.1
+++ b/man/roverlay.1
@@ -88,6 +88,10 @@ This includes ebuilds, metadata, Manifest files and the profiles/ dir.
 .BR "\-\-stats" "\fR, " "\-\-no\-stats"
 Print some stats after overlay creation/writing.
 .TP
+.BR "\-\-no\-manifest"
+Skip Manifest file creation to save time. Note that the resulting overlay
+cannot be used with portage/emerge.
+.TP
 .BR "\-\-overlay " "\fIdirectory\fR (\fB\-O\fR)"
 Set the overlay directory to \fIdirectory\fR. Else
 \fIOVERLAY_DIR\fR from the main config will be used.