====== parsecfg: configuration & command line parser (as of 0.8.1) ======

===== preface  =====

Especially in this document, the term **configuration** refers
to the control of the process which is implemented by 
kernel-autobuild. Not to the kernel configuration or anything else.

===== outline =====

There are mainly 3 sources of configuration input:

  * ''.conf'' files, which have a shell like syntax:
    * ''/etc/kernal-autobuild.conf''
    * ''~/.kernal-autobuild.conf''
    * ''./kernal-autobuild.conf''
  * ''.xml'' files, which contain XML data
    * ''/etc/kernal-autobuild.xml''
    * ''~/.kernal-autobuild.xml''
    * ''./kernal-autobuild.xml''
  * command line parameters which are described in [[project:kernel-autobuild:commandline]]

The ''.xml'' files contain 
  * a general section and
  * template sections providing sets of options.

As usual with *nix software, the files in /etc precede the ones inside the 
user's home directory (''~'') which precede those in the local directory 
which precede the command line options which in turn means
the settings override each other the other way round.

As far as kernel-autobuild is concerned, the ''.conf'' files also precede the ''.xml'' files.
The use of ''.conf'' files is deprecated.

And last but not least the settings from a template section inside an ''.xml'' file
override the settings from the general section.

None of these file are mandatory neither are any command line options.

===== sequence =====

In detail settings are recognized in the following order:

  * /etc/kernel-autobuild.conf
  * /etc/kernel-autobuild.xml
    * general options
    * template options
  * ~/.kernel-autobuild.conf
  * ~/.kernel-autobuild.xml
    * general options
    * template options
  * ./kernel-autobuild.conf
  * ./kernel-autobuild.xml
    * general options
    * template options
  * command line options

===== implemenation =====

==== pitfall ====

There is an implementation pitfall. One can't process the template
options at the time of reading the configuration file because the 
command line hasn't been processed yet. So you don't know about the 
selected template yet. The other way round doesn't work either.

==== how parsecfg puts things in order ====

First there is a class of structures used:

<code>
 structure
  |
  *-- general
  *-- templates
       |
       *-- template A
       *-- template B
       ...
</code>

Parsecfg reads all the configuration files at once, storing 
the data in one structure per file. 

Then it copies the contents of each structure in turn to
a master structure and by doing so it calculates the overriding
by just overwriting the values. There is an exception to options
which are allowed to be called multiple times: those values
are not overwritten but added to a list.

After that it processes the command line parameters storing all of them 
in some extra structure in the general subtree.

Next step is to look if a "''--template''" parameter has been specified.
If so inside the master structure the data from the corresponding 
template section is written to the general section. So template data supersedes
general data.

Last step is to overwrite the master structure with data from the 
command line structure. This is how in the end the command line "wins".

===== the xml format =====

<file xml kernel-autobuild.xml>
<?xml version="1.0" encoding="utf-8"?>
<!-- Stand: Fri Mar 16 13:36:58 CET 2012 -->
<applicationconfig version="0.2">
        <application name="kernel-autobuild">
                <general>
                        <opt name="TOOL_DIR"     v="/usr/share/kernel-autobuild"/>
                        <opt name="KERNEL_AUTOBUILD_BASEDIR" v="/var/lib/kernel-autobuild"/>
                        <opt name="SOURCE_IMG"   v="/var/lib/kernel-autobuild/00-resources/squeeze-kerneltest.img.xz"/>
                        <opt name="USE_CPUS"     v="8"/>
                        <opt name="PROVIDER_TAG" v="kernel-autobuild"/>
                </general>
                <templates>
                        <template name="3.4">
                                <opt name="--add-patch" v="/var/lib/kernel-autobuild/3.4/00-resources/patch-scripts-package-builddeb-v3.4.85+.diff" />
                        </template>
                        <template name="3.10">
                                <opt name="--kernel-base-version" v="3.10" />
                                <opt name="--add-patch" v="/var/lib/kernel-autobuild/3.10/00-resources/patch-scripts-package-builddeb-v3.10.35+.diff" />
                        </template>
                </templates>
        </application>
</applicationconfig>
</file>

==== some simple conversion helper ====

<file sh conf2xml>
#!/bin/bash
( 
cat << '.'
<applicationconfig version="0.2">
        <application name="kernel-autobuild">
                <general>
.
awk '
	/^#/ { print "\t\t<!--",$0,"-->" };
	/^[A-Za-z_][A-Za-z_0-9]*="/ { a=$0; b=$0; sub(/=.*/,"",a);sub(/^.*=/,"",b); printf "\t\t\t<opt name=\"%s\" v=%s />\n",a,b };
	/^[A-Za-z_][A-Za-z_0-9]*='"'"'/ { a=$0; b=$0; sub(/=.*/,"",a);sub(/^.*=/,"",b); printf "\t\t\t<opt name=\"%s\" v=%s />\n",a,b };
	/^[A-Za-z_][A-Za-z_0-9]*=[^'"'"'"]/  { a=$0; b=$0; sub(/=.*/,"",a);sub(/^.*=/,"",b); printf "\t\t\t<opt name=\"%s\" v=\"%s\" />\n",a,b };
	'
cat << '.'
                </general>
                <templates>
                        <template name="3.4">
                                <opt name="--add-patch" v="/var/lib/kernel-autobuild/3.4/00-resources/patch-scripts-package-builddeb-v3.4.85+.diff" />
                        </template>
                        <template name="3.10">
                                <opt name="--kernel-base-version" v="3.10" />
                                <opt name="--add-patch" v="/var/lib/kernel-autobuild/3.10/00-resources/patch-scripts-package-builddeb-v3.10.35+.diff" />
                        </template>
                </templates>
        </application>
</applicationconfig>
.
) < kernel-autobuild.conf > kernel-autobuild.xml

</file>