path: root/config/R-overlay.conf.reference

# 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,      (or use --overlay-name <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'

# 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 ***
#EBUILD_HEADER = "ebuild_header.txt"

# OVERLAY_MANIFEST_IMPLEMENTATION
#  Manifest implementation to be used
#   Currently, there's only one implementation available, manifest
#   writing using the ebuild(1) executable.
#   * accepted values:
#   -> 'default'         -- use the default implementation
#   -> 'none'            -- do not use any implementation,
#                           this leads to runtime errors
#                           whenever write_manifest() is called
#   -> 'external:ebuild' -- generate Manifest files using ebuild(1)
#
#  * defaults to 'default'
#  * alias: MANIFEST_IMPLEMENTATION

# == 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 or dirs
#   Please see the rule example file for file format.
#   Directories will be non-recursively scanned for files.
#   Files can also be compressed, either bzip2 (.bz2 file ext) or gzip (.gz)
#  * defaults to <unset>, which effectively disables dependency resolution
#     since no other dependency resolution methods are available.
#     This gives poor results!
#  * alias: SIMPLE_RULES_FILES
#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