diff options
Diffstat (limited to 'src/kconfig_compiler/README.dox')
| -rw-r--r-- | src/kconfig_compiler/README.dox | 446 |
1 files changed, 446 insertions, 0 deletions
diff --git a/src/kconfig_compiler/README.dox b/src/kconfig_compiler/README.dox new file mode 100644 index 00000000..b9606f1d --- /dev/null +++ b/src/kconfig_compiler/README.dox @@ -0,0 +1,446 @@ +/** +\page kconfig_compiler The KDE Configuration Compiler + +kconfig_compiler generates C++ source code from an XML file containing +information about configuration options (.kcfg) and a file that provides +the code generation options (.kcfgc) The generated class is based on +KConfigSkeleton and provides an API for the application to access its +configuration data. + +The generated C++ source code is output to a .h and a .cpp file, whose base +name is the same as that of the .kcfgc file. + +<h2>XML description of the configuration options</h2> + +The structure of the .kcfg file is described by its DTD kcfg.xsd. + +The \<kcfgfile\> tag may contain either the "name" attribute, which should be the name +of the configuration file described, or the "arg" attribute, which, if set to +"true", will allow you to pass the KSharedConfig::Ptr object to use. + +If neither "name" nor "arg" is set, the default configuration file +("\<appname\>rc") will be used. + +The \<include\> tags are optional and may contain C++ header files that +are needed to compile the code needed to compute default values. To generate +a \#include "..." statement instead of \#include \<...\>, enclose the header +file name in double quotes (e.g. \<include\>"header.h"\</include\>). + +The remaining entries in the XML file are grouped by the tag \<group\> +which describes the corresponding group in the configuration file. + +The individual entries must have at least a name or a key. The key is used +as the key in the config file, while the name is used to create accessor and +modifier functions. If \<key\> is given, but not \<name\>, the name is +constructed by removing all spaces from \<key\>. If \<name\> is given, but +not \<key\>, the key is the same as \<name\>. + +An entry must also have a type. The list of allowable types is +specified in the DTD and loosely follows the list of types supported +by the QVariant with exception of the clearly binary types +(e.g. Pixmap, Image...) which are not supported. Besides those basic +types the following special types are supported: + +- Path This is a string that is specially treated as a file-path. + In particular paths in the home directory are prefixed with $HOME in + when being stored in the configuration file. + +- Enum This indicates an enumeration. The possible enum values and optional + enum name should be provided via the \<choices\> tag. Enum values are + accessed as integers by the application but stored as strings in the + configuration file. This makes it possible to add more values at a later + date without breaking compatibility. + +- IntList This indicates a list of integers. This information is provided + to the application as QValueList<int>. Useful for storing QSplitter + geometries. + +An entry can optionally have a default value which is used as default when +the value isn't specified in any config file. Default values are interpreted +as literal constant values. If a default value needs to be computed +or if it needs to be obtained from a function call, the \<default\> tag +should contain the code="true" attribute. The contents of the \<default\> +tag is then considered to be a C++ expression. Note that in this case you +might have to add an \<include\> tag as described above, or a +SourceIncludeFiles entry in the .kcfgc file as described below, so that the +code which computes the default value can be compiled. + +Additional code for computing default values can be provided outside any +entry definition via the \<code\> tag. The contents of the \<code\> tag is +inserted as-is. A typical use for this is to compute a common default value +which can then be referenced by multiple entries that follow. + +<h2>Code generation options</h2> + +The options for generating the C++ sources are read from the file with the +extension .kcfgc. To generate a class add the corresponding kcfgc file to the +SOURCES line in the Makefile.am. + +The following options are read from the kcfgc file: + +<table> +<tr> + <td><b><i>Name</i></b></td> + <td><b><i>Type</i></b></td> + <td><b><i>Default</i></b></td> + <td><b><i>Description</i></b></td> +</tr> +<tr> + <td><b>File</b></td> + <td>string</td> + <td>programname.kcfg</td> + <td>Name of kcfg file containing the options the class is generated for</td> +</tr> +<tr> + <td><b>NameSpace</b></td> + <td>string</td> + <td>-</td> + <td>Optional namespace for generated class</td> +</tr> +<tr> + <td><b>ClassName</b></td> + <td>string</td> + <td>-</td> + <td>Name of generated class (required)</td> +</tr> +<tr> + <td><b>Inherits</b></td> + <td>string</td> + <td>KConfigSkeleton</td> + <td>Class the generated class inherits from. This class must inherit + KConfigSkeleton.</td> +</tr> +<tr> + <td><b>Visibility</b></td> + <td>string</td> + <td>-</td> + <td>Inserts visibility directive (for example KDE_EXPORT) between "class" keyword and class + name in header file</td> +</tr> +<tr> + <td><b>Singleton</b></td> + <td>bool</td> + <td>false</td> + <td>Generated class is a singleton.</td> +</tr> +<tr> + <td><b>CustomAdditions</b></td> + <td>bool</td> + <td>-</td> + <td></td> +</tr> +<tr> + <td><b>MemberVariables</b></td> + <td>string: public|protected|private|dpointer</td> + <td>private</td> + <td>C++ access modifier used for member variables holding the configuration + values</td> +</tr> +<tr> + <td><b>IncludeFiles</b></td> + <td>comma separated list of strings</td> + <td>-</td> + <td>Names of files to be included in the header of the generated class. Enclose a + file name in (escaped) double quotes to generate \#include "..." instead of + \#include \<...\>.</td> +</tr> +<tr> + <td><b>SourceIncludeFiles</b></td> + <td>comma separated list of strings</td> + <td>-</td> + <td>Names of files to be included in the source file of the generated class. Enclose + a file name in (escaped) double quotes to generate \#include "..." instead of + \#include \<...\>.</td> +</tr> +<tr> + <td><b>Mutators</b></td> + <td>true, false or a comma separated list of options</td> + <td>false</td> + <td>If true, mutator functions for all configuration options are generated. + If false, no mutator functions are generated. If a list is provided, + mutator functions are generated for the options that are listed.</td> +</tr> +<tr> + <td><b>DefaultValueGetters</b></td> + <td>true, false or a comma separated list of options</td> + <td>false</td> + <td>If true, functions to return the default value of all configuration options + are generated. If false, no default value functions are generated. If a list + is provided, default value functions are generated for the options that are listed.</td> +</tr> +<tr> + <td><b>ItemAccessors</b></td> + <td>bool</td> + <td>false</td> + <td>Generate accessor functions for the KConfigSkeletonItem objects + corresponding to the configuration options. If <b>SetUserTexts</b> is set, + <b>ItemAccessors</b> also has to be set.</td> +</tr> +<tr> + <td><b>SetUserTexts</b></td> + <td>bool</td> + <td>false</td> + <td>Set the label and whatthis texts of the items from the kcfg file.If + <b>SetUserTexts</b> is set, <b>ItemAccessors</b> also has to be set.</td> +</tr> +<tr> + <td><b>GlobalEnums</b></td> + <td>bool</td> + <td>false</td> + <td>If set to true all choices of Enum items will be created in the global + scope of the generated class. If set to false, each Enum item whose enum is not + explicitly named will get its own namespace for its choices.</td> +</tr> +<tr> + <td><b>UseEnumTypes</b></td> + <td>bool</td> + <td>false</td> + <td>If set to true, all Enum items whose enums are named will use enum types for + the return value of accessor functions and for the parameter of mutator + functions. This eliminates the need to cast accessor return values to the enum + type if you want to use the enum type in your own code. If set to false, + accessor return values and mutator parameters will be of type int.</td> +</tr> +<tr> + <td><b>ForceStringFilename</b></td> + <td>bool</td> + <td>false</td> + <td>If set to true, forces the first parameter of the generated class to be a QString when using an argument for the filename. This is useful to specify at runtime the filename of the configuration class.</td> +</table> + + +<h2>Advanced options</h2> + +There are several possibilities to parameterize entries. + +- Parameterized entries + +An entry can be parameterized using a fixed range parameter specified with +the \<parameter\> tag. Such parameter can either be an Enum or an int. An Enum +parameter should specify the possible enumeration values with the \<choices\> +tag. An int parameter should specify its maximum value. Its minimum value +is always 0. + +A parameterized entry is expanded to a number of entries, one for each +value in the parameter range. The name and key should contain a reference +to the parameter in the form of $(parameter-name). When expanding the entries +the $(parameter-name) part is replaced with the value of the parameter. +In the case of an Enum parameter it is replaced with the name of the +enumuration value. In the case of an int parameter it is replaced with +the numeric value of the parameter. + +Parameterized entries all share the same default value unless different +default values have been specified for specific parameter values. +This can be done with the param= attribute of the \<default\>. When a +param attribute is specified the default value only applies to that +particular parameter value. + +Example 1: +\verbatim + <entry name="Color$(ColorIndex)" type="Color" key="color_$(ColorIndex)"> + <parameter name="ColorIndex" type="Int" max="3"/> + <default param="0">#ff0000</default> + <default param="1">#00ff00</default> + <default param="2">#0000ff</default> + <default param="3">#ffff00</default> + </entry> +\endverbatim + +The above describes 4 color configuration entries with the following defaults: + +\verbatim +color_0=#ff0000 +color_1=#00ff00 +color_2=#0000ff +color_3=#ffff00 +\endverbatim + +The configuration options will be accessible to the application via +a QColor color(int ColorIndex) and a +void setColor(int ColorIndex, const QColor &v) function. + +Example 2: +\verbatim + <entry name="Sound$(SoundEvent)" type="String" key="sound_$(SoundEvent)"> + <parameter name="SoundEvent" type="Enum"> + <values> + <value>Explosion</value> + <value>Crash</value> + <value>Missile</value> + </values> + </parameter> + <default param="Explosion">boom.wav</default> + <default param="Crash">crash.wav</default> + <default param="Missile">missile.wav</default> + </entry> +\endverbatim + +The above describes 3 string configuration entries with the following defaults: + +sound_Explosion=boom.wav +sound_Crash=crash.wav +sound_Missile=missile.wav + +The configuration options will be accessible to the application via +a QString sound(int SoundEvent) and a +void setSound(int SoundEvent, const QString &v) function. + +- Parameterized groups + +A group name can be parametrized using a parameter given to the KConfigSkeleton +instance (which means this feature cannot be used with singleton classes). + +Example 1: +\verbatim + <kcfgfile name="testrc"> + <parameter name="groupname"/> + </kcfgfile> + <group name="$(groupname)"> + <entry key="Text" type="string"> + </entry> + </group> +\endverbatim + +In this case passing "Group2" as the 'groupname' parameter to the generated class +will make it use group "Group2" for the entry "Text". + +- Enums + +By default, if <b>GlobalEnums</b> is set to false, a separate named enum will be generated +for each Enum entry. Since each enum is defined in a little enclosing class of its own, +this allows the same Enum value names to be used in different enums. For example, the +.kcfg entry + +\verbatim +<entry name="KeepData" type="Enum"> + <choices> + <choice name="Do"> + <choice name="Dont"> + </choices> +</entry> +\endverbatim + +will generate this public class containing the enum definition, inside the generated class: + +\verbatim + class EnumKeepData + { + public: + enum type { Do, Dont, COUNT }; + }; +\endverbatim + +Alternatively, if <b>GlobalEnums</b> is set to true, all Enum items are defined as +unnamed enums in the global scope of the generated class. In this case, all Enum values +must have different names to avoid clashes. However, you can use a 'prefix' argument +in \<choices\> to prevent duplicate enum member names clashing. Using this, the Enum value +names are prefixed in code with the string you specify. For example, if <b>GlobalEnums</b> +is set to true, the .kcfg entry + +\verbatim +<entry name="KeepData" type="Enum"> + <choices prefix="Keep_"> + <choice name="Do"> + <choice name="Dont"> + </choices> +</entry> +\endverbatim + +will generate config file entries of "KeepData=Do" and "KeepData=Dont", but the enum +will be declared + +\verbatim + enum { Keep_Do, Keep_Dont }; +\endverbatim + +It is possible to specify your own name for a generated enum, by including a +'name' parameter in \<choices\>. Just like unnamed enums, this enum will be defined in +the global scope of the generated class (without any enclosing class of its own). +Therefore the names of Enum values must be unique across both unnamed enums (if +<b>GlobalEnums</b> is set to true) and all specifically named enums. + +An example of a specifically named enum: + +\verbatim +<entry name="KeepData" type="Enum"> + <choices name="Types"> + <choice name="Do"> + <choice name="Dont"> + </choices> +</entry> +\endverbatim + +which results in the following enum declaration, inside the generated class: + +\verbatim + enum Types { Do, Dont }; +\endverbatim + +It is also possible to specify the use of enums external to the generated class, by +including the string "::" in the enum name - just ensure that it is sufficiently +qualified to be unambiguous in use. To specify use of an unnamed enum, append a +trailing "::". For example, to use the enum 'myEnum' defined in class ClassA, use +either of + +\verbatim +<choices name="ClassA::myEnum"> +<choices name="::ClassA::myEnum"> +\endverbatim + +To specify an unnamed enum in namespace ProgSpace, use + +\verbatim +<choices name="ProgSpace::"> +\endverbatim + +To specify a top-level unnamed enum, use + +\verbatim +<choices name="::"> +\endverbatim + +To specify the top-level enum 'anotherEnum', use + +\verbatim +<choices name="::anotherEnum"> +\endverbatim + + +- Signal support. + +An entry can emit a signal when it gets changed. First of all, you must +define a list of signals for the configuration class. The signal's name may be +any legal identifier you wish. The \<argument\> tag allows you to specify arguments +for the emitted signal. It supports all types as defined in +the KConfigXT DTD. The argument value must specify the name, without spaces, of one +of the entries defined in the .kcfg file. +A signal definition can also contain a \<label\> tag which will be +the documentation line in the generated file. + +\verbatim +<signal name="emoticonSettingsChanged" /> + +<signal name="styleChanged"> + <label>Tell when a complete style change.</label> + <argument type="String">stylePath</argument> + <argument type="String">StyleCSSVariant</argument> +</signal> +\endverbatim + +After defining the signals, you must tell which signal to emit for the entry. +A signal can be emitted by multiple entries. Also, you don't need to specify the arguments +for a signal, the signal name will suffice. + +\verbatim +<entry key="stylePath" type="String"> + <label>Absolute path to a directory containing a Adium/Kopete chat window style.</label> + <emit signal="styleChanged" /> +</entry> +\endverbatim + +You can also use the generic configChanged() signal from KConfigSkeleton to notify your application +about configuration changes. + +If you have questions or comments please contact Cornelius Schumacher +<schumacher@kde.org> or Waldo Bastian <bastian@kde.org> +*/ |