Configuration » History » Version 8
J. Moringen, 05/26/2011 02:24 AM
links to ini- and desktop-file docs
1 | 1 | J. Moringen | h1. Configuration |
---|---|---|---|
2 | 1 | J. Moringen | |
3 | 1 | J. Moringen | The configuration mechanism is based on the following principles: |
4 | 2 | J. Moringen | * 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. |
5 | 1 | J. Moringen | * The configuration mechanism works identically across implementation languages |
6 | 1 | J. Moringen | * Configuration options are obtained from multiple configuration sources: |
7 | 1 | J. Moringen | ** Configuration files |
8 | 1 | J. Moringen | ** Environment variables |
9 | 1 | J. Moringen | ** _Commandline options (planned)_ |
10 | 1 | J. Moringen | * Configuration options are organized in a tree of name-value pairs |
11 | 1 | J. Moringen | |
12 | 1 | J. Moringen | h2. Syntax and Semantics |
13 | 1 | J. Moringen | |
14 | 1 | J. Moringen | 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@. |
15 | 1 | J. Moringen | |
16 | 8 | J. Moringen | Currently the following option tree is defined (uppercase option name components are placeholders, LANGUAGE refers to the implementation language): |
17 | 1 | J. Moringen | <pre> |
18 | 1 | J. Moringen | + qualityofservice |
19 | 1 | J. Moringen | +-- reliability { UNRELIABLE, RELIABLE } |
20 | 1 | J. Moringen | +-- ordering { UNORDERED, ORDERED } |
21 | 1 | J. Moringen | + errorhandling |
22 | 1 | J. Moringen | +-- onhandlererror { LOG, PRINT, EXIT } |
23 | 7 | J. Moringen | + plugins |
24 | 7 | J. Moringen | +-- LANGUAGE |
25 | 7 | J. Moringen | +---- path list of strings |
26 | 7 | J. Moringen | +---- load list of strings |
27 | 1 | J. Moringen | + transport |
28 | 1 | J. Moringen | +-- NAME |
29 | 1 | J. Moringen | +---- enabled bool |
30 | 1 | J. Moringen | +---- TRANSPORT_SPECIFIC_OPTION ? |
31 | 1 | J. Moringen | +---- converter |
32 | 7 | J. Moringen | +------ LANGUAGE |
33 | 7 | J. Moringen | +-------- WIRE-SCHEMA string |
34 | 1 | J. Moringen | +-- spread |
35 | 1 | J. Moringen | +---- host string |
36 | 1 | J. Moringen | +---- port uint |
37 | 1 | J. Moringen | +-- inprocess |
38 | 1 | J. Moringen | </pre> |
39 | 1 | J. Moringen | |
40 | 1 | J. Moringen | h2. Processing Order |
41 | 1 | J. Moringen | |
42 | 1 | J. Moringen | 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: |
43 | 1 | J. Moringen | # Config file @${HOME}/.config/rsb.conf@ |
44 | 1 | J. Moringen | # Config file @$(pwd)/rsb.conf@ |
45 | 1 | J. Moringen | # Environment variables |
46 | 1 | J. Moringen | |
47 | 1 | J. Moringen | h3. Example and test case |
48 | 1 | J. Moringen | |
49 | 1 | J. Moringen | Consider the following situation: |
50 | 1 | J. Moringen | * Contents of @${HOME}/.config/rsb.conf@: |
51 | 1 | J. Moringen | <pre> |
52 | 1 | J. Moringen | [transport.spread] |
53 | 1 | J. Moringen | host = azurit |
54 | 5 | J. Moringen | port = 5301 |
55 | 1 | J. Moringen | </pre> |
56 | 1 | J. Moringen | * Contents of @(pwd)/rsb.conf@ |
57 | 1 | J. Moringen | <pre> |
58 | 1 | J. Moringen | [transport.spread] |
59 | 1 | J. Moringen | host = localhost |
60 | 1 | J. Moringen | </pre> |
61 | 1 | J. Moringen | * Environment Variables |
62 | 5 | J. Moringen | @RSB_TRANSPORT_SPREAD_PORT='4444'@ |
63 | 1 | J. Moringen | |
64 | 1 | J. Moringen | This would result in the following effective option values: |
65 | 1 | J. Moringen | * @transport.spread.host = localhost@ |
66 | 1 | J. Moringen | * @transport.spread.port = 4444@ |
67 | 1 | J. Moringen | |
68 | 1 | J. Moringen | h2. Sources |
69 | 1 | J. Moringen | |
70 | 1 | J. Moringen | The following sections briefly explains the currently defined configuration sources. |
71 | 1 | J. Moringen | |
72 | 1 | J. Moringen | h3. Configuration Files |
73 | 1 | J. Moringen | |
74 | 8 | J. Moringen | 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/: |
75 | 1 | J. Moringen | * Comments are initiated by the @#@ character and extend to the end of the current line |
76 | 1 | J. Moringen | * After removing comments, all lines have to be of one of the following forms: |
77 | 1 | J. Moringen | ** empty |
78 | 1 | J. Moringen | ** @[NAME]@ where @NAME@ consists of alphanumeric characters and colons |
79 | 1 | J. Moringen | ** @NAME = VALUE@ where @NAME@ consists of alphanumeric characters |
80 | 1 | J. Moringen | |
81 | 1 | J. Moringen | Here is an example: |
82 | 1 | J. Moringen | <pre> |
83 | 1 | J. Moringen | [qualityofservice] |
84 | 1 | J. Moringen | reliability = UNRELIABLE |
85 | 1 | J. Moringen | ordering = UNORDERED |
86 | 1 | J. Moringen | |
87 | 1 | J. Moringen | [errorhandling] |
88 | 1 | J. Moringen | onhandlererror = LOG |
89 | 1 | J. Moringen | |
90 | 1 | J. Moringen | [transport.spread] |
91 | 1 | J. Moringen | host = localhost |
92 | 4 | S. Wrede | port = 4803 |
93 | 4 | S. Wrede | enabled = 1 # this is the default |
94 | 1 | J. Moringen | |
95 | 6 | J. Moringen | [spread.converter.cpp] |
96 | 4 | S. Wrede | image = IplImage # wireSchema = dataType |
97 | 1 | J. Moringen | |
98 | 1 | J. Moringen | [transport.inprocess] |
99 | 4 | S. Wrede | foo = barbar |
100 | 4 | S. Wrede | factor = 1.5 |
101 | 3 | S. Wrede | enabled = 1 |
102 | 1 | J. Moringen | |
103 | 6 | J. Moringen | [plugins.cpp] |
104 | 3 | S. Wrede | path = /vol/vampire/lib:/vol/cor/lib |
105 | 7 | J. Moringen | load = rsbspread:rsbvampire # no filetype suffix |
106 | 1 | J. Moringen | </pre> |
107 | 1 | J. Moringen | |
108 | 1 | J. Moringen | h3. Environment Variables |
109 | 1 | J. Moringen | |
110 | 1 | J. Moringen | Environment variables are processed according to the following rules |
111 | 1 | J. Moringen | # Variables whose names start with @RSB_@ are processed |
112 | 1 | J. Moringen | # The @RSB_@ prefix is stripped form the name |
113 | 1 | J. Moringen | # To obtain the name of the corresponding option, the remainder of the name is converted to lower case and split at @_@ characters |
114 | 1 | J. Moringen | |
115 | 1 | J. Moringen | Example: |
116 | 1 | J. Moringen | @RSB_TRANSPORT_SPREAD_PORT -> transport.spread.port@ |