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

["André Erdmann" <dywi@mailerd.de>]

commit:     6d85d2ef9272f19ee193a3ee58c1a72ae03c647d
Author:     André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Fri Jul  6 22:18:38 2012 +0000
Commit:     André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Fri Jul  6 22:18:38 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=6d85d2ef

documentation: config files

	modified:   README
	new file:   config/R-overlay.conf
	renamed:    description_fields.conf -> config/description_fields.conf
	new file:   config/repo.list
	renamed:    simple-deprules.conf -> config/simple-deprules.conf
	typechange: description_fields.conf

---
 README                                             |   43 +---
 config/R-overlay.conf                              |  321 ++++++++++++++++++++
 .../description_fields.conf                        |    0
 config/repo.list                                   |  103 +++++++
 .../simple-deprules.conf                           |    0
 description_fields.conf                            |  160 +----------
 6 files changed, 431 insertions(+), 196 deletions(-)

diff --git a/README b/README
index 64a1f47..542fa30 100644
--- a/README
+++ b/README
@@ -5,55 +5,24 @@ R overlay -- README
 There is currently no "R overlay" script, only modules that implement functionality.
 
 === Running tests ===
+# <TODO> write this section
 
 Real tests are scheduled for July 10 - July 30.
 
-In the meantime, there are some test scripts (run_<something>.py,
-test_<something>.sh) and a Makefile that provide basic testing.
-
-To run them you need to create a directory <root>/examples/packages and
-put some R packages into it (expected suffix is .tar.gz),
-where <root> is the directory containing this README file.
-Some scripts expect the seewave (seewave_1.6.3.tar.gz) package in there.
-
-You can then run:
- 	./run_config.py <config files>
-
- 	 	* reads config files and prints the config
-
- 	./run_overlaycreation.py [--help|-h|?] [--show] [--write] [<R packages>]
-
- 	 	* creates an overlay with ebuilds for the given R packages (or seewave if left out)
-
- 	 	* parameters:
- 	 	** --help  -- prints a short usage info (does not create ebuilds/...)
- 	 	** --show  -- prints the created ebuilds/metadata to console,
- 	 	               does not create Manifest files
-	
- 	 	** --write -- writes the created ebuilds/metadata to the overlay, including
- 	 	               Manifest files (see R-overlay.conf for the overlay dir)
-
- 	make <target>, where target is
-
- 	 	* seewave, test-seewave -- runs './run_overlaycreation --show examples/packages/seewave_*.tar.gz'
- 	 	* clean-log             -- removes log files in ./log/
-	 	* test-nop              -- run './nop.py' which does nothing but 'import roverlay'
+A main script is available. See ./main.py --help for usage.
 
 
 == Configuration ==
 
 * main configuration
-shell-like syntax (using shlex), TODO - roverlay/config/entrymap could be
-helpful in the meantime
+see config/R-overlay.conf
 
 * repo configuration (CRAN,...)
-to be clarified; either part of the main config as tuple
-<name>;<local dir or empty>;<rsync uri>;<src uri> in the main config file
-or in a separate file using ConfigParser syntax.
+see config/repo.list
 
 * description field configuration
-ConfigParser syntax, please see 'description_fields.conf' in this directory.
+see config/description_fields.conf
 
 * dependency rules configuration
-simple dependency rules: see simple-deprules.conf
+see config/simple-deprules.conf
 

diff --git a/config/R-overlay.conf b/config/R-overlay.conf
new file mode 100644
index 0000000..dd160b3
--- /dev/null
+++ b/config/R-overlay.conf
@@ -0,0 +1,321 @@
+# R-overlay.conf
+#  This file explains how to write a R overlay main config,
+#  it can also be used as config file.
+#
+# -- Table of contents --
+#
+# 1  -- config value types and file syntax
+# 2  -- config quickstart (basic overview of options to set)
+# 3  -- config entries
+#  a -- misc
+#  b -- overlay
+#  c -- other config files
+#  d -- logging
+#  e -- other (debugging, testing, ...)
+#
+# -- end of ToC --
+
+# = config value types and file syntax =
+
+# This file is parsed using shlex (shell-like syntax)
+#  * '#' is the comment char
+#  * variables ("${X}") are not supported
+#  * whitespace is ignored (in most cases)
+#    => whitespace in file paths is generally not supported,
+#        but may work with some restrictions
+#  * quotes are optional, but allow to span long values over multiple lines,
+#    e.g. <<
+# SIMPLE_RULES_FILE="<path to first rule file>
+# <another one>
+# "
+#    >>
+#
+#
+# some options have value type restrictions,
+#
+# special value types used in this config ("* allowed values: <type>"):
+#
+#  log level -- choose from {DEBUG, INFO, WARN, WARNING, ERROR, CRITICAL}
+#  bool      -- string that represents a boolean value,
+#                true  := {y,yes,on,1,true,enabled}
+#                false := {n,no,off,0,false,disabled}
+#                other values are not allowed
+#
+#
+# implicit value types:
+#
+# list       -- option has multiple values separated by whitespace,
+#                use quotes to specify more than one value
+#
+# file, dir  -- value will be expanded ( ~ => ${HOME}, x => ${PWD}/x etc.),
+#                value has to be a file (or dir) if it exists
+#
+# <empty>    -- often leads to errors (in case of value type restrictions),
+#                just comment out config entries
+#
+#
+#
+# "*** NOT IN USE ***" means that an option is read and integrated into
+# the config tree, but never used (normal entry in config/entrymap).
+#  => value will be validated
+#
+# "*** <option> is not available> ***" means that an option is read, but
+#  ignored ("None" entry in config/entrymap).
+#  => value won't be validated
+
+
+# = config quick start =
+# This is a listing of options to consider
+#
+# options that are required:
+#  OVERLAY_NAME,
+#  OVERLAY_DIR,       (or use --overlay <OVERLAY>)
+#  DISTFILES,         (or use --distroot <DISTROOT>)
+#  REPO_CONFIG,       (or use --repo-config <file>) # FIXME: required?
+#  FIELD_DEFINITION   (or use --field-definition <file>)
+#
+# options that are optional but essential for a usable result:
+#  OVERLAY_ECLASS,
+#  SIMPLE_RULES_FILE  (or use --deprule-file <file>)
+#
+# some options for logging:
+#  LOG_CONSOLE,
+#  LOG_FILE,
+#  LOG_LEVEL,
+#  LOG_LEVEL_FILE,
+#  LOG_LEVEL_CONSOLE
+#
+# some options for debugging and testing:
+#  LOG_FILE_UNRESOLVABLE,
+#  DESCRIPTION_DIR
+#
+
+
+# = config starts here =
+
+# == misc options ==
+
+# DISTFILES_ROOT
+#  the root directory of repo distdirs
+#   Repos will create their distdirs in this directory unless
+#   they specify another location.
+#  * alias: DISTDIR, DISTFILES
+#  * defaults to <unset> (but required!)
+#DISTFILES_ROOT = "distfiles-root"
+
+
+# == overlay options ==
+
+# OVERLAY_NAME
+#  name of the overlay
+#  * defaults to <unset> (but required!)
+#OVERLAY_NAME = "ROverlay"
+
+# OVERLAY_DIR
+#  overlay root directory
+#   This is the directory where the overlay content, e.g. ebuilds and
+#   profiles/repo_name will be written into.
+#  * defaults to <unset> (but required!)
+#OVERLAY_DIR = "overlay-root"
+
+# OVERLAY_ECLASS
+#  eclass files to import into the overlay and us in ebuilds
+#   Note that overlay creation fails if importing any of the
+#   specified eclass files fails.
+#  * accepted values: a list of files that end with '.eclass' or
+#     don't have an extension
+#  * defaults to <unset> (empty list) - this is NOT useful
+#  * alias: ECLASS
+#OVERLAY_ECLASS = "eclass/R-packages.eclass"
+
+# OVERLAY_CATEGORY
+#  overlay category of the created ebuilds
+#  * accepted values: no restrictions made, but don't insert a '/'!
+#  * defaults to sci-R
+#OVERLAY_CATEGORY = 'dev-R'
+
+# EBUILD_HEADER
+#  ebuild header file that will be included in all created ebuilds
+# *** NOT IN USE ***
+#EBUILD_HEADER = "ebuild_header.txt"
+
+# == other config files ==
+
+# some config options are split from this file for various reasons:
+# * no need to be modifed by users (in most cases)
+#  -> FIELD_DEFINITION
+# * special syntax that is not compatible with this file
+#  -> SIMPLE_RULES_FILE
+# * special syntax that eases adding/reading entries (-> all)
+# * config is independent from this file
+#  -> e.g. per-repo script runs using the same main config ("-R <file>" option)
+
+
+# FIELD_DEFINITION
+#  path to the config file that controls DESCRIPTION file reading
+#  * defaults to <unset> (but required!)
+#  * alias: FIELD_DEFINITION_FILE
+#FIELD_DEFINITION = "description_fields.conf"
+
+# REPO_CONFIG
+#  path to the repo config file
+#   Please see the example file for file format.
+#  * defaults to <unset> (but required!)
+#  * alias: REPO_CONFIG_FILE, REPO_CONFIG_FILES
+#REPO_CONFIG = "repo.list"
+
+# SIMPLE_RULES_FILE
+#  list of (simple) dependency rule files
+#   Please see the rule example file for file format.
+#  * defaults to <unset>, which effectively disables dependency resolution
+#     since no other dependency resolution methods are available.
+#     This gives poor results!
+#  * alias: SIMPLE_RULES_FILES
+#  *** TODO-note: accept directories as value ***
+#SIMPLE_RULES_FILE = "simple-deprules.d/R"
+
+# == logging ==
+
+# LOG_ENABLED
+#  enable/disable logging (globally)
+#  * accepted values: bool
+#  * defaults to enabled => use per-log target settings, e.g. LOG_CONSOLE
+#LOG_ENABLED = "no"
+
+# LOG_LEVEL
+#  the default log level
+#   Choices are DEBUG, INFO, WARN, WARNING, ERROR, CRITICAL.
+#  * defaults to <unset>, which causes console/file logging
+#     to use their own defaults
+#LOG_LEVEL = DEBUG
+
+# LOG_DATE_FORMAT
+#  date format used in logging
+#  * defaults to '%F %H:%M:%S'.
+#LOG_DATE_FORMAT = '%a, %H:%M'
+
+# *** LOG_FORMAT is not available ***
+
+
+# === console logging ===
+
+# LOG_CONSOLE
+#  enable/disable logging to console
+#  * accepted values: bool
+#  * defaults to enabled
+#  * alias: LOG_CONSOLE_ENABLED
+#LOG_CONSOLE = "no"
+
+# LOG_FORMAT_CONSOLE
+#  log format used in console logging
+#  * defaults to '%(levelname)-8s %(name)-14s: %(message)s'
+#  * alias: LOG_CONSOLE_FORMAT
+#LOG_FORMAT_CONSOLE = '[%(name)s] %(message)s'
+
+# LOG_LEVEL_CONSOLE
+#  log level for console logging, see LOG_LEVEL
+#  * accepted values: a log level
+#  * defaults to INFO
+#  * alias: LOG_CONSOLE_LEVEL
+#LOG_LEVEL_CONSOLE = "DEBUG"
+
+# *** LOG_CONSOLE_STREAM is not available ***
+
+
+# === file logging ===
+
+# LOG_FILE
+#  log file to write
+#   File logging will be disabled if left blank / commented out.
+#  * defaults to <unset>
+#LOG_FILE = ""
+
+# LOG_LEVEL_FILE
+#  log level used in file logging
+#  * accepted values: a log level, see LOG_LEVEL
+#  * defaults to: WARNING
+#  * alias: LOG_FILE_LEVEL
+#LOG_LEVEL_FILE = "ERROR"
+
+# LOG_FORMAT_FILE
+#  log format used in file logging
+#  * defaults to '%(asctime)s %(levelname)-8s %(name)-10s: %(message)s'
+#  * alias: LOG_FILE_FORMAT
+#LOG_FORMAT_FILE = '%(asctime)s $(levelname)s [%(name)s]: %(message)s'
+
+# LOG_FILE_ROTATE
+#  enable/disable log file rotation
+#   The log file will be rotated on every script run.
+#  * accepted values: bool
+#  * defaults to disabled
+#LOG_FILE_ROTATE = "yes"
+
+# LOG_FILE_ROTATE_COUNT
+#  number of rotated log files to keep
+#   Only used when log file rotation is enabled.
+#  * accepted values: int (make sure it's >= 0)
+#  * defaults to 3
+#LOG_FILE_ROTATE_COUNT = 10
+
+# LOG_FILE_BUFFERED
+#  buffer log entries in memory before writing them to the log file
+#   This should reduce I/O blocking when using low log levels with threads.
+#  * accepted values: bool
+#  * defaults to enabled
+#LOG_FILE_BUFFERED = "no"
+
+# LOG_FILE_BUFFER_COUNT
+#  max number of log entries to buffer
+#   Only used when log entry buffering is enabled.
+#  * accepted values: integer (make sure that the value is >= 1)
+#  * defaults to 250
+#  * alias: LOG_FILE_BUFFER_CAPACITY
+#LOG_FILE_BUFFER_COUNT = 50
+
+# LOG_FILE_ENABLED
+#  enable/disable logging to file
+#  * accepted values: bool
+#  * defaults to enabled (which grants LOG_FILE control over this setting)
+#LOG_FILE_ENABLED = "no"
+
+
+# == options for debugging, (manual) dependency rule creation, testing, ... ==
+
+# LOG_FILE_UNRESOLVABLE
+#  file where unresolved dependency strings will be written to
+#   Useful if you want to create new rules,
+#    run -> read unresolvable file -> create rules -> rerun.
+#   Comment out to disable.
+#  * defaults to <unset>
+#LOG_FILE_UNRESOLVABLE = "log/dep_unresolvable.log"
+
+# LOG_FILE_RESOLVED
+#  file where resolved dep strings will be written to
+#  *** NOT IN USE ***
+#LOG_FILE_RESOLVED = ""
+
+# DESCRIPTION_DIR
+#  directory where description files will be written into
+#   If enabled: write all read description files to
+#     <descfiles dir>/<R package name>_<R package version>.desc
+#   Comment out to disable.
+#  * defaults to <unset>
+#  * alias: DESCRIPTION_DESCFILES_DIR
+#DESCRIPTION_DIR = "desc-files"
+
+# EBUILD_PROG
+#  name of/path to the ebuild executable
+#  * accepted values: no restrictions made,
+#     but overlay writing will fail if the value is invalid,
+#     which is a huge time loss since ebuilds have been created before writing.
+#  * defaults to "ebuild"
+#EBUILD_PROG = "/usr/local/bin/ebuild"
+
+# RSYNC_BWLIMIT
+#  set a max. average rsync bandwidth usage (in kilobytes/second)
+#   This is a per-"rsync command" setting using rsync's "--bwlimit" option
+#   Note: you can set per-repo bwlimit's in the repo config file
+#    TODO-note: ^ make sure that this option doesn't interfere
+#  * accepted values: int (>0 expected)
+#  * defaults to <unset>
+#RSYNC_BWLIMIT = 10000

diff --git a/description_fields.conf b/config/description_fields.conf
similarity index 100%
copy from description_fields.conf
copy to config/description_fields.conf

diff --git a/config/repo.list b/config/repo.list
new file mode 100644
index 0000000..f389fd7
--- /dev/null
+++ b/config/repo.list
@@ -0,0 +1,103 @@
+# repo.list
+#  This file explains how to write repo config files.
+
+# This file is parsed used ConfigParser syntax (known from .ini files).
+
+# A repo entry describes
+# * where to find R packages that will be used for overlay creation,
+#    and optionally where and how to get the R packages (using repo types)
+# * how ebuilds can download the R packages (=> SRC_URI)
+
+# Each repository is introduced with [<section name>] and has to declare
+# some options.
+#
+# general options are:
+#
+# * required:
+#
+#   src_uri   -- this is used to determine the SRC_URI in ebuilds
+#                 (SRC_URI=<src_uri>/<package file name>)
+#                 FIXME note: check that subdirs are handled correctly
+#
+# * optional:
+#
+#   name      -- name of the repository
+#                 optional, defaults to <section name>
+#   type      -- the type of this repo, see below
+#                 optional, defaults to rsync
+#   directory -- the local package directory,
+#                 optional, defaults to <DISTFILES ROOT (from config)>/<name>
+#
+#   (base_uri -- don't use, to be removed)
+#
+#
+# There are two types of repos, "rsync" and "local" ones:
+#
+# * Local repo;
+#   A Local repo represents a directory with R packages in it.
+#   It will never be modified (i.e. synced) and has no special options.
+#
+# * Rsync repo:
+#   An Rsync repo uses a local directory to sync with a remote.
+#   Its directory will be modified whenever syncing (using the rsync program).
+#   Behaves like a local repo if syncing is disabled.
+#
+#  default rsync options (always passed to rsync):
+#   --links, --safe-links, --times, --compress, --dirs, --prune-empty-dirs,
+#   --force, --delete, --human-readable, --stats, --chmod=ugo=r,u+w,Dugo+x
+#
+#  This type has special options:
+#
+#  rsync_uri        -- required, rsync uri
+#  recursive        -- optional, passes '--recursive' to rsync
+#                       if this option is set to 'yes'
+#  extra_rsync_opts -- optional options to pass to rsync, this
+#                       can be used to exclude/include files,
+#                       show progress while syncing etc.
+#                       Note: options cannot contain whitespace! (#FIXME note: this could be allowed if useful)
+#
+#
+
+
+# == Repo entry examples ==
+
+# a local directory with packages in /var/www/R_packages
+#
+#[local_packages]
+#type      = local
+#src_uri   = http://localhost/R_packages
+#directory = /var/www/R_packages
+
+
+# a local directory with packages manually downloaded from CRAN
+# * directory will be automatically set to <DISTROOT>/CRAN/selected
+#
+#[CRAN/selected]
+#type    = local
+#src_uri = http://cran.r-project.org/src/contrib
+
+# CRAN rsync repo
+# * type will be set to rsync
+# * directory will be set to <DISTROOT>/CRAN/all
+# * rsync progress will be shown during transfer
+# * not recursive, the package archive and R release won't be fetched
+# * this needs about 2.5G disk space
+#
+#[CRAN/all]
+#src_uri   = http://cran.r-project.org/src/contrib
+#rsync_uri = cran.r-project.org::CRAN/src/contrib
+#extra_rsync_opts = --progress
+
+# CRAN rsync repo (selective transfer)
+# * type is explicitly set to rsync
+# * only packages starting with "r" or "R" will be fetched
+# * directory will be set to <DISTROOT>/CRAN/only_letter_R
+# * rsync progress will be shown during transfer
+# * not recursive
+# * this needs about 300M disk space
+#
+#[CRAN/only_letter_R]
+#type      = rsync
+#src_uri   = http://cran.r-project.org/src/contrib
+#rsync_uri = cran.r-project.org::CRAN/src/contrib
+#extra_rsync_opts = --include=r* --include=R* --exclude=* --progress

diff --git a/simple-deprules.conf b/config/simple-deprules.conf
similarity index 100%
rename from simple-deprules.conf
rename to config/simple-deprules.conf

diff --git a/description_fields.conf b/description_fields.conf
deleted file mode 100644
index 0705798..0000000
--- a/description_fields.conf
+++ /dev/null
@@ -1,159 +0,0 @@
-# R overlay -- description field definition
-# Copyright 2006-2012 Gentoo Foundation
-# Distributed under the terms of the GNU General Public License v2
-#
-
-# ----------------------------------------------------------------------------
-#
-# This file controls how DESCRIPTION fields are used
-# It is read in raw mode so that strings like '%var' are not interpolated.
-# A per-field section is introduced with [<field name>] and
-# contains flags and options.
-#
-#
-# known field options are:
-#
-#  default_value = <some value>
-#                        -- set the default value for this field,
-#                            which implies that any read description data
-#                            will contain this field (with value either
-#                            from the description file or the default one).
-#                            'Disables' the mandatory flag.
-#
-#  allowed_value = <some value>
-#                        -- declares that this field has a value
-#                            whitelist and adds <some value> to this list.
-#
-#  allowed_values = <some values>
-#                        -- same as allowed_value but witj multiple values
-#
-#  alias_withcase = <aliases>,
-#  alias = <aliases>
-#                        -- declares case-sensitive field name aliases
-#                            aliases can be used to fix typos as well as
-#                            to remap/merge fields (e.g. Title -> Description)
-#
-#  alias_nocase = <aliases>
-#                        -- declares case-insenstivite field names aliases
-#
-#
-#  flags = <flags>
-#                        -- add flags to this field; note that any value-less
-#                            option is interpreted as flag
-#
-# options with multiple values are read as a <value>[, <value>]* list
-#
-# and known field flags are:
-#  joinValues
-#         -- declares that the field's value is one string even if it
-#             spans over multiple lines (the lines will be joined with ' ')
-#             The default behavior is to join lines with ''.
-#  isList
-#         -- declares that the field's value is a list
-#            (the default regex for splitting the values is '\s*[,;]{1}\s*')
-#
-#  isWhitespaceList
-#         -- declares that the field's value is a list
-#             separated by whitespace. Has no effect if 'isList' is set.
-#  mandatory
-#         -- declares that this field has to have an value that evaluates
-#             to True (value is set and not empty).
-#             This flag is (effectively) useless in conjunction with
-#             default_value unless the default value evaluates to False.
-#
-#  ignore
-#         -- ignore this field entirely
-#
-#
-# Flags are always case-insensitive.
-# Note that it is not checked whether a flag is known or not,
-# which means you can add anything here.
-#
-# ----------------------------------------------------------------------------
-
-
-[Description]
-joinValues
-
-[Title]
-joinValues
-
-[Package]
-joinValues
-
-# not used
-ignore
-
-[License]
-isList
-
-# not used
-ignore
-
-[Version]
-joinValues
-
-# not used
-ignore
-## else
-#mandatory
-
-[Suggests]
-alias_nocase = Suggests, Suggest, %Suggests, Suggets, Recommends
-isList
-
-[Depends]
-alias_nocase = Depends, Dependencies, Dependes, %Depends, Depents, Require, Requires
-isList
-
-[Imports]
-alias_nocase = Imports, Import
-isList
-
-[LinkingTo]
-alias_nocase = LinkingTo, LinkingdTo, LinkinTo
-isList
-
-[SystemRequirements]
-alias_nocase = SystemRequirements, SystemRequirement
-isList
-
-[OS_Type]
-alias_nocase = OS_TYPE
-allowed_values = unix
-
-[Author]
-ignore
-
-[Date]
-ignore
-
-[Date/Publication]
-ignore
-
-[Encoding]
-ignore
-
-[Maintainer]
-ignore
-
-[Packaged]
-ignore
-
-[Repository]
-ignore
-
-[Type]
-ignore
-
-[URL]
-ignore
-
-[Webpage]
-ignore
-
-[ZipData]
-ignore
-
-[LazyLoad]
-ignore

diff --git a/description_fields.conf b/description_fields.conf
new file mode 120000
index 0000000..514f8d7
--- /dev/null
+++ b/description_fields.conf
@@ -0,0 +1 @@
+config/description_fields.conf
\ No newline at end of file