The incomplete Guide to Lumiera Configuration
=============================================
:author: ct
:date: 8/2008

WARNING: this is a draft from the early days of Lumiera +
         IMHO, the whole topic ``Configuration'' requires further
         discussion and design.
+
-- -- Ichthyo

'''''''''''''
'''''''''''''

Order is roughly alphabetically, depending on the mood of the writer.
Defaults are noted if present. Not all are implemented yet.

General Introduction
--------------------

Lumiera uses plaintext files with a INI file like syntax for
configuration. This Syntax is strictly line based. There are only a
few syntactic elements.

TODO:describe config syntax here

Config Subsystem
----------------

The path where Lumiera searches its configuration. Single components are
separated by colons as in PATH and other such environment variables.
Here it might be handy that any Lumiera configuration can be
overridden by a environment variable:
'LUMIERA_CONFIG_PATH=somewhere:else lumiera ...'
A default are initialized at installation time, this is important to
bootstrap the whole configuration system.

 config.path


The config system check for a preferred format when writing config
entries. For each key 'foo.bar', these can be overridden with a key
'config.format.foo.bar' linking to the desired format.

 config.formatkey ='config.format.%s'


The following are links to the default formatting when no explicit
format is set for a key. Changing these to a wrong type will break the
system!

 config.formatdef.link < config.formatstr.link
 config.formatdef.number < config.formatstr.number.dec
 config.formatdef.real < config.formatstr.real
 config.formatdef.string < config.formatstr.string
 config.formatdef.word < config.formatstr.word
 config.formatdef.bool < config.formatstr.bool


This are the low level formating specifications for the buildin
types, DONT TOUCH THESE!

 config.formatstr.link = '< %s'
 config.formatstr.number.dec = '= %lld'
 config.formatstr.number.hex = '= 0x%llX'
 config.formatstr.number.oct = '= 0%llo'
 config.formatstr.real = '= %Lg'
 config.formatstr.real.dec = '= %Lf'
 config.formatstr.real.sci = '= %Le'
 config.formatstr.string = '= %s'
 config.formatstr.string.dquoted = '= \"%s\"'
 config.formatstr.string.quoted = '= ''%s'''
 config.formatstr.word = '= %s'
 config.formatstr.bool = '= %d'


Plugin System
-------------

The path where Lumiera searches its plugins. Single components are
separated by colons as in PATH and other such environment variables.
Here it might be handy that any Lumiera configuration can be
overridden by a environment variable:
'LUMIERA_PLUGIN_PATH=somewhere:else lumiera ...'
Sensible defaults are initialized at installation time.

 plugin.path


I/O Backend
-----------

File handling
~~~~~~~~~~~~~

How many filehandles the backend shall use [approx 2/3 of all available]

 vault.file.max_handles



Memory mapped Files
~~~~~~~~~~~~~~~~~~~

Address space limit (memory mapping)
Defaults:
3GiB on 32 bit arch
192TiB on 64 bit arch

 vault.mmap.as_limit

Default start size for mmaping windows.
128MB on 32 bit arch
2GB on 64 bit arch

 vault.mmap.window_size

How many memory mappings shall be established at most
Default 60000

 vault.mmap.max_maps