|
Elektra
0.9.0
|
In Elektra different forms of application integrations are possible:
In this tutorial we will discuss (3), i.e., how to extend an application to directly access Elektra’s key database.
When the application is fully integrated in Elektra’s ecosystem following benefits arise:
We call the process of making applications aware of other's configuration "to elektrify". This tutorial is suited both for new and existing applications.
As first step, locate places where configuration is parsed or generated. Afterwards, use Elektra’s data structures instead at these locations. Before we are going to describe how to do this, we will describe some possibilities to keep all advantages your previous configuration system had.
You can keep code you want within Elektra as plugins. This allows your application, and other applications participating in Elektra’s ecosystem to access your configuration. Doing this, the syntax of the configuration file stays the same as before. You can keep the same validation as you had before. The application profits from Elektra’s infrastructure solving basic issues like getting configuration from other parts of the system, update and conflict detection, and resolving of the file name. In particular we gain a lot because every other program can also access the configuration of your software.
If you do not have the code or want to get rid of it, you can use a variety of already implemented plugins to extend the functionality of the configuration system. There are plenty of plugins that parse and generate configuration files in different formats, do syntactic checks, do notifications (e.g. via dbus), and write out events in their log files.
New applications do not have the burden to stay compatible with the configuration system they had to before. So they will prefer to use more standard plugins and contribute to make them flawless. But they can also use self-written plugins for adding needed behavior or cross-cutting concerns.
To sum up, if a developer wants to elektrify software, he or she can do that without any need for changes to the outside world regarding the format and semantics of the configuration. In the interconnected world it is a matter of time until other software also wants to access the configuration, and with elektrified software it is possible for every application to do so.
As first step in a C-application you need to create an in-memory Key. Such a Key is Elektra’s atomic unit and consists of:
Keys are either associated with entries in configuration files or used as arguments in the API to transport some information.
Thus a key is in-memory and does not need any of the other Elektra objects. We always can create one (the tutorial will use the C-API, but it describes general concepts useful for other languages in the same way):
keyNew is the name of the key. It consists of different parts, / is the hierarchy-separator:sw is for softwareorg is a URL/organization name to avoid name clashes with other application names. Use only one part of the URL/organization, so e.g. kde is enough.myapp is the name of the most specific component that has its own configuration#0 is the major version number of the configuration (increment if you need to introduce incompatible changes).current is the profile to use. Administrators need it if they want to start up applications with different configurations.KEY_END as C needs a proper termination of variable length arguments.The key name is standardized to make it easier to locate configuration.
Now we have the Key we will use to pass as argument. First we open our key database (KDB):
A Key is seldom alone, but they are often found in groups, as typical in configuration files. To represent many keys (a set of keys) Elektra has the data structure KeySet. Because the Key's name is unique we can lookup keys in a KeySet without ambiguity. Furthermore, we can iterate over all Keys in a KeySet without a hassle. To create an empty KeySet we use:
Keys we think we will have in the KeySet conf, intended for optimization purposes.KS_END.Now we have everything ready to fetch the latest configuration:
Note it is important for applications that the parentKey starts with a slash /. This ensures pulling in all keys of the so-called namespace. Such a name cannot physically exist in configuration files, but they are the most important key names to actually work with configuration within applications as we will see when introducing ksLookup.
To lookup a key, we use:
We see in this example that only Elektra paths are hard coded in the application, no configuration file or similar.
As already mentioned keys starting with slash / do not exist in configuration files, but are "representatives", "proxies" or "logical placeholders" for keys from any other namespace.
So that every tool has a consistent view to the key database it is vital that every application does a ksLookup for every key it uses. So even if your application iterates over keys, always remember to do a cascading lookup for every single key!
Thus we are interested in the value we use:
We need to convert the configuration value to the data type we need.
To do this manually has severe drawbacks:
ksLookup which gets tiresome for arraysSo (larger) applications should not directly use KeySet, but instead use code generation to provide a type-safe frontend.
For more information about that, continue reading here.
Now, we have a fully working configuration system without any hard coded information (such as configuration files). We already gained something. But, we did not discuss how we can actually achieve application integration, the goal of Elektra.
Elektra 0.8.11 introduces the so called specification for the application's configuration, located below its own namespace spec. The specification itself also consists of (meta) key-value pairs.
Keys in spec allow us to specify which keys the application reads, which fallback they might have and which is the default value using metadata.
The implementation of links are in ksLookup. When using cascading keys (those starting with /), the following features are now available (in the metadata of respective spec-keys):
override/#: use these keys in favor of the key itself (note that # is the syntax for arrays, e.g. #0 for the first element, #_10 for the 11th and so on)namespace/#: instead of using all namespaces in the predefined order, one can specify namespaces to search in a given orderfallback/#: when no key was found in any of the (specified) namespaces the fallback-keys will be searcheddefault: the value to use if nothing else was foundYou can use those features like following:
This technique provides complete transparency how a program will fetch a configuration value. In practice that means that:
, will give you the exact same value as the application gets when it uses the above lookup C code.
What we do not see in the program above are the default values and fallbacks. They are also present in the specification (namespace spec).
So lets say, that another application otherapp has the value we actually want. We want to improve the integration. In the case that we do not have a value for /sw/org/myapp/#0/current/section/subsection/key, we want to use /sw/otherorg/otherapp/#0/current/section/subsection/key.
So we specify:
Voila, we have done a system integration between myapp and otherapp!
Note that the fallback, override and cascading works on key level, and not like most other systems have implemented, on configuration file level.
To make this work within your application make sure to always call ksLookup before using a value from Elektra.
We call the files, that contain a complete schema for configuration below a specific path in form of metadata, Specfiles.
Particularly a Specfile contains metadata that defines
Now we apply this Specfile to the key database to all keys below /sw/org/myapp/#0/current:
Then the configuration of our application will be in my-config-file.ini (because of mountpoint in the specification) and it will use the INI format (because of infos/plugins in the specification). section/subsection/key contains the specification of what we already specified imperatively before.
For a description which metadata is available, have a look in METADATA.ini.
Elektra does not hard code any configuration data in your application. Using the default specification, we even can startup applications without any configuration file at all and still do not have anything hard coded in the applications binary. Furthermore, by using cascading keys for kdbGet() and ksLookup() Elektra gives you the possibility to specify how to retrieve configuration data. In this specification you can define to consider or prefer configuration data from other applications or shared places. Doing so, we can achieve configuration integration.
1.8.13