Robotics Service Bus

h1. Configuration

{{>toc}}

The configuration mechanism is based on the following principles:
* We cannot (and do not want) to handle configuration of individual participants. The configuration mechanism is intended to provide process-wide defaults. Participants that require individual configurations have to be configured programmatically.
* The configuration mechanism works identically across implementation languages
* Configuration options are obtained from multiple configuration sources:
** Configuration files
** Environment variables
** _Commandline options (planned)_
* Configuration options are organized in a tree of name-value pairs

h2. Syntax and Semantics

Option names consist of multiple components which are specified in configuration-source-dependent syntax. For example, in configuration files section names like @[transport.spread]@ are concatenated with names of contained options like @port@ to obtain @transport.spread.port@. For environment variables, the name @RSB_TRANSPORT_SPREAD_PORT@ maps to @transport.spread.port@.

Currently the following option tree is defined (uppercase option name components are placeholders, LANGUAGE refers to the implementation language):
<pre>
+ qualityofservice
+-- reliability { UNRELIABLE, RELIABLE }
+-- ordering { UNORDERED, ORDERED }
+ errorhandling
+-- onhandlererror { LOG, PRINT, EXIT }
+ plugins
+-- LANGUAGE
+---- path list of strings
+---- load list of strings
+ transport
+-- NAME
+---- enabled bool
+---- TRANSPORT_SPECIFIC_OPTION ?
+---- converter
+------ LANGUAGE
+-------- WIRE-SCHEMA string
+-- spread
+---- host string
+---- port uint
+---- maxfragmentsize uint
+---- tcpnodelay boolean
+-- inprocess
</pre>

h2. Processing Order

Configuration sources are processed in the following order such that options from sources which are processed later take precedence over options from sources which are processed earlier:
# Config file @${HOME}/.config/rsb.conf@
# Config file @$(pwd)/rsb.conf@
# Environment variables

h3. Example and test case

Consider the following situation:
* Contents of @${HOME}/.config/rsb.conf@:
<pre>
[transport.spread]
host = azurit
port = 5301
</pre>
* Contents of @(pwd)/rsb.conf@
<pre>
[transport.spread]
host = localhost
</pre>
* Environment Variables
@RSB_TRANSPORT_SPREAD_PORT='4444'@

This would result in the following effective option values:
* @transport.spread.host = localhost@
* @transport.spread.port = 4444@

h2. Sources

The following sections briefly explains the currently defined configuration sources.

h3. Configuration Files

Configuration files use the following syntax, which is similar to "INI-files":http://en.wikipedia.org/wiki/INI_file or "desktop-files":http://standards.freedesktop.org/desktop-entry-spec/latest/:
* Comments are initiated by the @#@ character and extend to the end of the current line
* After removing comments, all lines have to be of one of the following forms:
** empty
** @[NAME]@ where @NAME@ consists of alphanumeric characters and colons
** @NAME = VALUE@ where @NAME@ consists of alphanumeric characters

Here is an example:
<pre>
[qualityofservice]
reliability = UNRELIABLE
ordering = UNORDERED

[errorhandling]
onhandlererror = LOG

[transport.spread]
host = localhost
port = 4803
enabled = 1 # this is the default

[spread.converter.cpp]
image = IplImage # wire-schema = data-type

[transport.inprocess]
foo = barbar
factor = 1.5
enabled = 1

[plugins.cpp]
path = /vol/vampire/lib:/vol/cor/lib
load = rsbspread:rsbvampire # no filetype suffix
</pre>

Please note that only files with the platform's respective line endings are supported (i.e. \n on linux and \r\n on windows).

h3. Environment Variables

Environment variables are processed according to the following rules:
# Variables whose names start with @RSB_@ are processed
# The @RSB_@ prefix is stripped form the name
# To obtain the name of the corresponding option, the remainder of the name is converted to lower case and split at @_@ characters

Examples:
* @RSB_PLUGINS_CPP_LOAD <-> plugins.cpp.load@
* @RSB_TRANSPORT_SPREAD_PORT <-> transport.spread.port@

h3. Commandline Options

_This section is a proposal._

Commandline options are processed according to the following rules:
# Language-specific name components (such as @plugins.cpp.load@) are dropped
# Components are joined with/strings are split at @-@ characters

Examples:
* @--plugins-load <-> plugins.cpp.load@
* @--transport-spread-port <-> transport.spread.port@