README_md(3) libelektra

Contact

Do not hesitate to ask any question on github issue tracker, Mailing List or directly to one of the authors.

Quickstart

If you want to use Elektra for your application, read the application integration tutorial.

Installation

The preferred way to install Elektra is by using packages provided for your distribution. On Debian/Ubuntu, this can be done by running the following command:

1 sudo apt-get install elektra-bin libelektra-dev

This will install the Elektra tools as well as everything needed to develop with Elektra.

If you're not running Debian/Ubuntu, check out the package list, download elektra directly or compile it yourself.

It is preferable to use a recent version: They contain many bug fixes and additional features. See INSTALL for other ways to install Elektra.

Usage

Now that we have Elektra installed, we can start using the kdb command and the qt-gui.

You can use the kdb command to configure your applications:

1 kdb set user/env/override/HTTP_PROXY "http://my.proxy:8080"

This will set the HTTP_PROXY environment variable to http://my.proxy:8080. Configuration can be retrieved with kdb get:

1 kdb get /env/override/HTTP_PROXY

For information about elektrified environment variables, see src/libgetenv/README.md

Documentation

To get an idea of Elektra, you can take a look at the presentation.

The full documentation, including tutorials, glossary, and concepts and man pages is available in the github repository.

You can read the documentation for the kdb tool, either

  • http://libelektra.org/blob/master/doc/help/kdb.md 'on github'
  • in the API docu
  • by using kdb --help or kdb help <command>
  • by using man kdb

Goals

  • Make it trivial for applications and administrators to access any configuration
  • Postpone some decisions from programmers to
  • Make configuration storage more safe: avoid that applications receive wrong or unexpected values that could lead to undefined behaviour.
  • Allow software to be better integrated on configuration level maintainers/administrators, e.g. which syntax and the location of configuration files.
  • Reduce rank growth of configuration parsers in our ecosystem, but foster well maintained plugins instead.

And in terms of quality, we want:

1.
Simplicity (make configuration tasks simple),
2.
Robustness (no undefined behaviour of applications), and
3.
Extensibility (gain control over configuration access)

Read more about the goals of Elektra

Facts and Features

Elektra uses the BSD licence.
Elektra implements an API to fully access a global key database.
Elektra can be thought of a virtual file system for configuration.
Elektra supports mounting of existing configuration files into the global key database.
Elektra has dozens of Plugins that make it possible to have a tiny core, but still support many features, including:
Elektra can import and export configuration files in any supported format.
Elektra is able to log and notify other software on any configuration changes, e.g., using Dbus and Journald.
Elektra can improve robustness by rejecting invalid configuration via type checking, regex and more.
Elektra provides different mechanisms to locate configuration files.
Elektra supports different ways to escape and encode content of configuration files.

  • Elektra is multi-process safe and can be used in multi-threaded programs.
  • Elektra (except for some plugins) is portable and completely written in Ansi-C99.
  • Elektra (except for some plugins) has no external dependency.
  • Elektra is suitable for embedded systems and early boot stage programs.
  • Elektra uses simple key/value pairs that include metadata for any other information.
  • Elektra provides many powerful Bindings to avoid low-level access code.
  • Elektra provides powerful Code Generation Techniques for high-level configuration access.

News

  • 17 Sep 2015 0.8.13 adds elektrify-getenv
  • 12 Jul 2015 0.8.12 adds dir namespace
  • 03 Apr 2015 0.8.11 adds spec namespace
  • 02 Dec 2014 0.8.10 adds XDG/OpenICC compatibility
  • 04 Nov 2014 0.8.9 adds qt-gui
  • 02 Sep 2014 0.8.8 adds 3-way merging

Also see News and its RSS feed.

Sources

Packages

The preferred way to install Elektra is by using packages provided for your distribution:

  • Fedora
  • Gentoo
  • Arch Linux
  • Debian
  • Ubuntu

Available, but not up-to-date (Version 0.7):

  • Mageia
  • Linux Mint

For OpenSUSE, CentOS, Fedora, RHEL and SLE Kai-Uwe Behrmann kindly provides packages for download. For Debian wheezy and jessie amd64 we provide latest builds. See build server below.

If there are no packages available for your distribution, see the installation document.

Download

Elektra's uses a git repository at github.

You can clone the latest version of Elektra by running:

     git clone https://github.com/ElektraInitiative/libelektra.git

Releases can be downloaded from http and ftp://ftp.libelektra.org/elektra/releases/

Compiling

After downloading or cloning Elektra, cd to the directory and run the following commands to compile it:

  • mkdir -p build
  • cd build
  • cmake ..
  • make

Then you can use sudo make install to install it.

You can also use the `./configure` command to generate a cmake command with special options.

For more information, especially how to set CMake Cache, see here. Make sure to read how to add plugins, tools and bindings.

Build Server

The build server builds Elektra on every commit in various ways and also produces LCOV code coverage report.

To use the debian repository of the latest builds from master put following files in /etc/apt/sources.list. For jessie:

    deb     [trusted=yes] http://194.117.254.29/elektra-stable/ jessie main
    deb-src [trusted=yes] http://194.117.254.29/elektra-stable/ jessie main

For wheezy:

     deb     [trusted=yes] http://build.libelektra.org/debian/ wheezy main
     deb-src [trusted=yes] http://build.libelektra.org/debian/ wheezy main

Develop

To start development, just clone the repo and start hacking!

  • We encourage you to improve documentation, especially the README.md as if they were a webpage.
  • You should read the coding document before you issue a pull request.
  • Make yourself familiar with the KeySet (also in the API docu) the central data structure in Elektra.
  • You should read the design document before you make design relevant decisions.
  • You can always peek into the TODOs, if you don't know what to do.