.TH "README_md" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
README_md \- libelektra 
\fIElektra provides a universal and secure framework to store configuration parameters in a global, hierarchical key database\&.\fP
.PP
.PP
The core is a small library implemented in C\&. The plugin-based framework fulfills many configuration-related tasks to avoid any unnecessary code duplication across applications while it still allows the core to stay without any external dependency\&. Elektra abstracts from cross-platform-related issues with an consistent API, and allows applications to be aware of other applications' configurations, leveraging easy application integration\&.
.PP
\fCWhy should I use Elektra?\fP
.PP
.SS "Contact"
.PP
Do not hesitate to ask any question on \fCgithub issue tracker\fP, \fCMailing List\fP or directly to one of the \fBauthors\fP\&.
.PP
.SS "Quickstart"
.PP
If you want to use Elektra for your application, \fBread the application integration tutorial\fP\&.
.PP
.SS "Installation"
.PP
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:
.PP
.PP
.nf
1 sudo apt-get install elektra-bin libelektra-dev
.fi
.PP
.PP
This will install the Elektra tools as well as everything needed to develop with Elektra\&.
.PP
If you're not running Debian/Ubuntu, check out the \fCpackage list\fP, \fCdownload elektra directly\fP or \fCcompile it yourself\fP\&.
.PP
It is preferable to use a recent version: They contain many bug fixes and additional features\&. See \fBINSTALL\fP for other ways to install Elektra\&.
.PP
.SS "Usage"
.PP
Now that we have Elektra installed, we can start using the \fBkdb command\fP and the \fBqt-gui\fP\&.
.PP
You can use the \fCkdb\fP command to configure your applications:
.PP
.PP
.nf
1 kdb set user/env/override/HTTP_PROXY "http://my\&.proxy:8080"
.fi
.PP
.PP
This will set the \fCHTTP_PROXY\fP environment variable to \fChttp://my.proxy:8080\fP\&. Configuration can be retrieved with \fCkdb get\fP:
.PP
.PP
.nf
1 kdb get /env/override/HTTP_PROXY
.fi
.PP
.PP
For information about elektrified environment variables, see \fBsrc/libgetenv/README\&.md\fP
.PP
.SS "Documentation"
.PP
To get an idea of Elektra, you can take a look at the \fCpresentation\fP\&.
.PP
The full documentation, including \fCtutorials\fP, \fBglossary\fP, and \fBconcepts and man pages\fP is available in the github repository\&.
.PP
You can read the documentation for the kdb tool, either
.PP
.IP "\(bu" 2
\fBhttp:\fP//libelektra\&.org/blob/master/doc/help/kdb\&.md 'on github'
.IP "\(bu" 2
\fCin the API docu\fP
.IP "\(bu" 2
by using \fCkdb --help\fP or \fCkdb help <command>\fP
.IP "\(bu" 2
by using \fCman kdb\fP
.PP
.PP
.SS "Goals"
.PP
.IP "\(bu" 2
Make it trivial for applications and administrators to access any configuration
.IP "\(bu" 2
Postpone some decisions from programmers to
.IP "\(bu" 2
Make configuration storage more safe: avoid that applications receive wrong or unexpected values that could lead to undefined behaviour\&.
.IP "\(bu" 2
Allow software to be better integrated on configuration level maintainers/administrators, e\&.g\&. which syntax and the location of configuration files\&.
.IP "\(bu" 2
Reduce rank growth of configuration parsers in our ecosystem, but foster well maintained plugins instead\&.
.PP
.PP
And in terms of quality, we want:
.PP
.IP "1." 4
Simplicity (make configuration tasks simple),
.IP "2." 4
Robustness (no undefined behaviour of applications), and
.IP "3." 4
Extensibility (gain control over configuration access)
.PP
.PP
\fBRead more about the goals of Elektra\fP
.PP
.SS "Facts and Features"
.PP
.IP "\(bu" 2
Elektra uses the \fBBSD licence\fP\&.
.IP "\(bu" 2
Elektra implements an \fCAPI\fP to fully access a global key database\&.
.IP "\(bu" 2
Elektra can be thought of a virtual file system for configuration\&.
.IP "\(bu" 2
Elektra supports mounting of existing configuration files into the global key database\&.
.IP "\(bu" 2
Elektra has dozens of \fBPlugins\fP that make it possible to have a tiny core, but still support many features, including:
.IP "  \(bu" 4
Elektra can import and export configuration files in any \fBsupported format\fP\&.
.IP "  \(bu" 4
Elektra is able to log and notify other software on any configuration changes, e\&.g\&., using \fBDbus\fP and \fBJournald\fP\&.
.IP "  \(bu" 4
Elektra can improve robustness by rejecting invalid configuration via \fBtype checking\fP, \fBregex\fP and more\&.
.IP "  \(bu" 4
Elektra provides different mechanisms to \fBlocate configuration files\fP\&.
.IP "  \(bu" 4
Elektra supports different ways to \fBescape\fP and \fBencode\fP content of configuration files\&.
.PP

.IP "\(bu" 2
Elektra is multi-process safe and can be used in multi-threaded programs\&.
.IP "\(bu" 2
Elektra (except for some \fBplugins\fP) is portable and completely written in Ansi-C99\&.
.IP "\(bu" 2
Elektra (except for some \fBplugins\fP) has no external dependency\&.
.IP "\(bu" 2
Elektra is suitable for embedded systems and early boot stage programs\&.
.IP "\(bu" 2
Elektra uses simple key/value pairs that include metadata for any other information\&.
.IP "\(bu" 2
Elektra provides many powerful \fBBindings\fP to avoid low-level access code\&.
.IP "\(bu" 2
Elektra provides powerful \fBCode Generation Techniques\fP for high-level configuration access\&.
.PP
.PP
.SS "News"
.PP
.IP "\(bu" 2
\fC17 Sep 2015 0\&.8\&.13\fP adds elektrify-getenv
.IP "\(bu" 2
\fC12 Jul 2015 0\&.8\&.12\fP adds dir namespace
.IP "\(bu" 2
\fC03 Apr 2015 0\&.8\&.11\fP adds spec namespace
.IP "\(bu" 2
\fC02 Dec 2014 0\&.8\&.10\fP adds XDG/OpenICC compatibility
.IP "\(bu" 2
\fC04 Nov 2014 0\&.8\&.9\fP adds qt-gui
.IP "\(bu" 2
\fC02 Sep 2014 0\&.8\&.8\fP adds 3-way merging
.PP
.PP
Also see \fBNews\fP and its \fCRSS feed\fP\&.
.PP
.SS "Sources"
.PP
.SS "Packages"
.PP
The preferred way to install Elektra is by using packages provided for your distribution:
.IP "\(bu" 2
\fCFedora\fP
.IP "\(bu" 2
\fCGentoo\fP
.IP "\(bu" 2
\fCArch Linux\fP
.IP "\(bu" 2
\fCDebian\fP
.IP "\(bu" 2
\fCUbuntu\fP
.PP
.PP
Available, but not up-to-date (Version 0\&.7):
.IP "\(bu" 2
\fCMageia\fP
.IP "\(bu" 2
\fCLinux Mint\fP
.PP
.PP
For \fCOpenSUSE, CentOS, Fedora, RHEL and SLE\fP Kai-Uwe Behrmann kindly provides packages \fCfor download\fP\&. For Debian wheezy and jessie amd64 we provide latest builds\&. See build server below\&.
.PP
If there are no packages available for your distribution, see the \fBinstallation document\fP\&.
.PP
.SS "Download"
.PP
Elektra's uses a \fCgit repository at github\fP\&.
.PP
You can clone the latest version of Elektra by running: 
.PP
.nf
     git clone https://github.com/ElektraInitiative/libelektra.git

.fi
.PP
.PP
Releases can be downloaded from \fChttp\fP and \fCftp://ftp.libelektra.org/elektra/releases/\fP
.PP
.SS "Compiling"
.PP
After downloading or cloning Elektra, \fCcd\fP to the directory and run the following commands to compile it:
.PP
.IP "\(bu" 2
\fCmkdir -p build\fP
.IP "\(bu" 2
\fCcd build\fP
.IP "\(bu" 2
\fCcmake \&.\&.\fP
.IP "\(bu" 2
\fCmake\fP
.PP
.PP
Then you can use \fCsudo make install\fP to install it\&.
.PP
You can also use the \fB`\&./configure`\fP command to generate a \fCcmake\fP command with special options\&.
.PP
For more information, especially how to set CMake Cache, see \fBhere\fP\&. Make sure to read how to add plugins, tools and bindings\&.
.PP
.SS "Build Server"
.PP
The \fCbuild server\fP builds Elektra on every commit in various ways and also produces \fCLCOV code coverage report\fP\&.
.PP
To use the debian repository of the latest builds from master put following files in /etc/apt/sources\&.list\&. For jessie: 
.PP
.nf
    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

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

.fi
.PP
.PP
.SS "Develop"
.PP
To start development, just clone the repo and start hacking!
.PP
.IP "\(bu" 2
We encourage you to improve documentation, especially the README\&.md as if they were a webpage\&.
.IP "\(bu" 2
You should read the \fBcoding document\fP before you issue a pull request\&.
.IP "\(bu" 2
Make yourself familiar with the \fBKeySet\fP (also in the \fCAPI docu\fP) the central data structure in Elektra\&.
.IP "\(bu" 2
You should read the \fBdesign document\fP before you make design relevant decisions\&.
.IP "\(bu" 2
You can always peek into the \fBTODOs\fP, if you don't know what to do\&. 
.PP