sudo apt-get install cmake git build-essential
Or on RPM based systems (CentOS):
sudo yum install -y cmake3 git gcc-c++
Or on macOS Sierra, most of the build tools can be obtained by installing Xcode (from the App Store). Other required tools may be installed using brew. First install brew as described on their website. Then issue the following command to get cmake to complete the basic requirements:
brew install cmake git
Run the following commands to compile Elektra with non-experimental parts where your system happens to fulfil the dependences (continue reading the rest of the document for details about these steps):
git clone https://github.com/ElektraInitiative/libelektra.git cd libelektra mkdir build cd build cmake .. # watch output to see if everything needed is included ccmake .. # optional: overview of the available build settings (needs cmake-curses-gui) make -j 5 make run_nokdbtests # optional: run tests
The last line only runs tests not writing into your system.
See TESTING for how to run more tests.
Afterwards you can use
sudo make install && sudo ldconfig to install Elektra.
See INSTALL for more information about
installation of self-compiled Elektra (such as how to uninstall it).
Note: You do not need to install the dependencies listed here. If they are not available, some of the functionality gets disabled automatically. The core of Elektra never depends on other libraries.
To build documentation you need doxygen (we recommend 1.8.8+), graphviz and ronn:
apt-get install doxygen graphviz ruby-ronn
Or on RPM based systems:
sudo yum install -y doxygen docbook-style-xsl graphviz ruby gem install ronn
Or on macOS Sierra using brew:
brew install doxygen graphviz brew install ruby # in case ruby is not already installed gem install ronn
To build PDF documentation you need
apt-get install pdflatex texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra
For the plugins, please refer to the README.md of the respective plugin. For example, for CentOS:
sudo yum install -y boost-devel libdb-devel GConf2-devel libxml2-devel yajl-devel \ libcurl-devel augeas-devel libgit2-devel lua-devel swig python34-devel python-devel \ java-1.8.0-openjdk-devel jna ruby-devel byacc
For the Debian package, please refer to debian/control (in the debian branch).
Elektra uses cmake3. Tested are cmake version 3.0.2 and 3.7.2 among others.
To configure Elektra graphically (with curses) run (
.. belongs to command):
mkdir build && cd build && ccmake ..
c to configure the cache (might be necessary multiple times, and once on the first time in case you don‘t see any settings).
After applying the desired settings, press
g to generate the make file.
All options described here, can also be used with
cmake rather than
.. does also here belong to the command):
mkdir build && cd build && cmake -D<OPTION1>=<VAR1> -D<OPTION2>=<VAR2> ..
For information what you can use as
OPTION2, see above.
Note: You have to enclose a value with quotes
"" if it contains a semicolon (
cmake -DPLUGINS="dump;resolver;yajl;list;spec" ..
Some scripts in the folder of the same name may help you running cmake.
For supported compilers have a look at the automatic build farm on https://build.libelektra.org/
|gcc||gcc (Debian 6.3.0-18) 6.3.0||amd64|
|gcc/g++||4.9.4 (¹)||openbsd 6.3|
(¹) OpenBSD ships an old version of GCC per default, which can not compile Elektra. A manual installation of egcc/eg++ is required. Note that not every OpenBSD mirror provides the eg++ package. Elektra builds are confirmed with egcc/eg++ 4.9.4 in OpenBSD 6.3. The packages are called gcc and g++. Compile with
To change the compiler, use cmake settings
To use gcc-4.3 for example
cmake -DCMAKE_C_COMPILER=gcc-4.3 -DCMAKE_CXX_COMPILER=g++-4.3 ..
To change the compiler with
ccmake, you may need to toggle advanced options (key
Some options, i.e.
TOOLS are either:
- a list of elements separated with a semicolon (
;) (note that shells typically need
;to be escaped)
- a special uppercase element that gets replaced by a list of elements, that are:
ALLto include all elements (except elements with unfulfilled dependencies)
NODEPto include all elements without dependencies
- elements prefixed with a minus symbol (
-) to exclude an element
Examples for this are especially in the subsection
PLUGINS below, but they work in the
same fashion for
Read about available plugins here.
Because the core of elektra is minimal, plugins are needed to actually read and write to configuration files (storage plugins), commit the changes (resolver plugins, also takes care about how the configuration files are named) and also do many other tasks related to configuration.
The minimal set of plugins you should add:
- dump is the default storage.
If you remove it, make sure you add another one and set
- resolver is the default resolver.
If you remove it, make sure you add another one and set
- list delegates work to a list of plugins.
Needed for tests. (Required with
- spec copies metadata from spec namespace
to other namespaces.
Needed for tests. (Required with
ENABLE_TESTING, except on mingw.)
- sync is very useful to not lose any data.
If you do not want to include it, make sure to set
/sw/elektra/kdb/#0/current/pluginsto a value not containing sync (e.g. an empty value). See kdb-mount(1).
By default CMake adds nearly all plugins if the dependencies are present. Only experimental plugins will be omitted by default:
To add also experimental plugins, you can use:
Note that plugins are excluded automatically if dependences are not satisfied. So make sure to install all dependencies you need before you run
cmake. For example, to include the plugin
yajl, make sure
To add all plugins except some plugins you can use:
For example, if you want all plugins except the jni plugin you would use:
To add all plugins not having additional dependencies (they need only POSIX), you can use
Note, that every
infos/status field written uppercase can
be used to select plugins that way (see README of individual plugins).
You also can combine any of these fields
and add/remove other plugins to/from it, e.g. to include all plugins without deps,
that provide storage (except
yajl) and are maintained, but not include all plugins
that are experimental, you would use:
The inclusion is determined by following preferences:
- if the plugin is explicit excluded with
- if the plugin is explicit included with
- if the plugin is excluded via a category
- if the plugin is included via a category
- plugins are excluded if they are not mentioned at all (neither by category nor by name)
Note, that changing
PLUGINS will not modify the defaults used
after Elektra was installed. For this endeavour you need to change:
The default resolver and storage will write to
Obviously, you can pass the exact list of plugins you want, e.g.:
Some plugins are compile-time configurable. Then you can choose which
features are compiled in or out. This is especially important in the
bootstrapping phase, because then only the compiled in configuration
applies. To compile-time-configure a plugin, you just pass a underscore
_) and flags after the name of the plugin.
The resolver for example distinguish between 3 different kind of flags:
Following baseflags are available:
cfor debugging conflicts
ffor enabling file locking
mfor enabling mutex locking
The user flags are (the order matters!):
puse passwd/ldap to lookup home directory using
huse the environment variable HOME
uuse the environment variable USER
buse the built-in default cmake variable
The system flags are (the order matters!):
xuse the environment variable
:are interpreted as part of filename, no searching is done!) This option is not recommended (unless for testing), because it allows users to fake system configuration.
buse the built-in default cmake variable
- note: if a path that begins with a slash (
/) is chosen, the system flags are irrelevant and the path is taken as-is.
For example, one may use:
resolver_l_h_b you need to specify
You can add resolver with any combination of the flags, even if they are
not available in
Tools are used to add extra functionality to Elektra.
The flag used to specify which tools are compiled is
-DTOOLS, thus flag works similarly to the
but is more limited in its functionality (which does not
matter, because there are not so many tools).
To add all non-experimental tools, you can use::
Note that the behavior is different to PLUGINS which includes all PLUGINS if ALL is used.
To add all tools except of race, you can use:
To specify specific tools you can use, e.g.:
Bindings are used in a like as
For example, to build all maintained bindings and exclude experimental bindings
you can use:
Note that the same languages are sometimes available over GI and SWIG. In this case, the SWIG bindings are preferred. The SWIG executable may be specified with:
If this option is not used, cmake will find the first occurrence of
swig in your environment's path.
To build GI bindings (deprecated) and gsettings (experimental) use:
Some bindings provide different APIs (and not a different language), e.g:
To not add such APIs, but only
swig bindings and
cpp, you can use:
For a list of available bindings see binding's README.md.
See help bar at bottom of
ccmake for that option or:
BUILD_SHARED BUILD_FULL BUILD_STATIC
BUILD_SHARED is the typical build you want to have on systems that support
It can be used for desktop builds, but also embedded systems as long as they support
dlopen, for example,
BUILD_SHARED is used on OpenWRT with
BUILD_SHARED every plugin is its own shared object.
BUILD_FULL links together all parts of Elektra as a single shared
This is ideal if shared libraries are available, but you want to avoid
Some tests only work with
BUILD_FULL, so you might turn it on to get full
BUILD_STATIC also links together all parts but as static
It is only useful for systems without
dlopen or if the overhead of
dlopen needs to be avoided.
All three forms of builds can be intermixed freely.
For example, to enable shared and full build, but disable static build, one would use:
cmake -DBUILD_SHARED=ON -DBUILD_FULL=ON -DBUILD_STATIC=OFF ..
Build documentation with doxygen (API) and ronn (man pages).
If ronn is not found, already compiled man pages will be used instead.
Note: Turning off building the documentation, also turns off installing the documentation, see https://issues.libelektra.org/2522 Then no man pages are available.
As developer you should enable
- enables assertions
- adds RTLD_NODELETE so that debugger finds symbols even after dlclose
ENABLE_LOGGER: enables logging By default no logging will take place, see CODING for how to get log messages.
Continue reading testing for more information about testing.
CMAKE_INSTALL_PREFIX defaults to
So by default most files will installed below
Exceptions to this are files handled by INSTALL_SYSTEM_FILES.
Edit that cache entry to change that behavior. Also called system prefix within the documentation.
If you want to create a package afterwards it is ok to use
paths that you can write to (e.g.
Lets you install libraries into architecture specific folder.
E.g. for 32/64 bit systems you might install libraries under
64 to achieve exactly that.
So the system library folder will be
By default include folders will be installed below
This entry let you change the elektra.
If the entry is empty, the include files will be
installed directly to
Similar to above, but with the plugins. Default is:
It can be also left empty to install plugins next
to other libraries.
This value specifies the root directory of a local copy of the Google Test framework.
- If it is empty (
""), then the build system will download a copy of Google Test into the build directory.
- Otherwise the build system will search for the file
CMakeLists.txtin the top level directory of
GTEST_ROOT. If this file exists, then the build system will use the sources files at
GTEST_ROOTto translate tests that use Google Test.
It can be provided as CMake or environment variable. If both options are provided the value passed via CMake takes precedence.
It is recommended that you browse through all of the options using
c again (maybe multiple times until all variables are
resolved) and then
g to generate. Finally press
e to exit.
Specifies that the build tools, i.e.
are installed (by default off). Is needed for cross-compilation.
Some of Elektra’s targets require to be installed into specific folders in the file system hierarchy to work properly.
This variable is disabled by default, since it requires the install target to have the
rights to write into the corresponding folders. Set
if you also want to install the files listed below.
If you do not have root rights you can also copy the files manually to your user folder.
Currently the installed system files are as following:
|bash-completion||bash tab auto completion file||
|zsh-completion||zsh tab auto completion file||/usr/share/zsh/vendor-completions|
|GIR||introspection file for bindings||
|GSettings||GSettings backend module||
In order to keep the binaries as small as possible this flag allows to trade memory for speed.
To build the source use:
You can pass:
-jfor parallel builds
VERBOSE=1to see the invocations of the compiler
Continue by reading INSTALL.
You can build Elektra using Code::Blocks under Gentoo:
Precondition: Make sure you have a compiler, xml2 (for kdb tool) and xsl (see later) installed. cmake configure will help you with that, it will make sure you don't forget something essential.
For Most Linux system all you have to do is open up a console and
mkdir build cd build cmake .. -G 'CodeBlocks - Unix Makefiles' make package
Note 1: You can use other editor if you like just type cmake at the console to get a list of option you can pass to cmake as long as well as a list of what code editor project cmake can create.
For Unix if you have nCurses install you can run
ccmake to set important option after
running cmake like to enable debug symbol.
Note 3: for Gentoo is recommend to emerge sys-apps/lsb-release to name the package right even thou not required.
On multiarch (multiple architectures installed in one system), you need to set
For example, if you want to have the binaries in
would use for the libraries to be installed in
If there is a directory for different architectures, simply prepend an
For example, for Debian:
By default Elektra uses
RPATH to hide its plugins. This makes it obvious that
external applications should not link against plugins. Instead every application
should use the
elektraModulesLoad() API to load Elektra’s modules.
The folder where the plugins are located is a subdirectory of where the
libraries are installed. The name of the subdirectory can be specified
TARGET_PLUGIN_FOLDER and is
elektra by default. You might
want to encode Elektra’s
SOVERSION into the folders name, if you want
different major versions of Elektra be co-installable.
Elektra’s use case for
RPATH is considered acceptable, so we recommend to use it
- plugins do not clutter the library folder nor the
- it works well with multiarch (
LIB_SUFFIXis also honored for plugins)
- which plugins are used should be decided at mount-time and be globally available in the
same way for every application.
RPATHsupports exactly that because it even overrides
Unfortunately, there are also drawbacks:
- it makes Elektra non-relocatable (
RPATHis decided at compile-time, so you cannot simply move Elektra’s installations within the file system (e.g. from
- it requires modern
ld.soimplementations that honor
RPATHfrom libraries. This is the case for most
libcimplementations including Linux and macOS, but not for, e.g.,
If you want Elektra to not use
RPATH, you can add:
Then all plugins are directly installed to the library directory and loaded
like other libraries (in any of
Alternatively, which gives you the advantage not to clutter the main library path,
is to add the plugin folder in
/etc/ld.so.conf.d/elektra. Note that it still allows
applications to link against plugins.
Dependencies not Available for Cent OS
Please enable EPEL https://fedoraproject.org/wiki/EPEL
# Install EPEL for RHEL 7 curl -o epel-release-7-8.noarch.rpm \ http://dl.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-8.noarch.rpm sudo rpm -ivh epel-release-7-8.noarch.rpm sudo yum update
For Bindings swig3 is recommended. swig2 only works on some distributions. E.g., for Debian Jessie the bindings will crash.
At time of writing, no swig 3 was available, not even in EPEL. Thus you need to install swig3 manually:
curl https://codeload.github.com/swig/swig/tar.gz/rel-3.0.10 | tar xz cd swig-rel-3.0.10 && ./autogen.sh && ./configure && make sudo make install cd ..
Also, no ronn was available, thus you need to do:
gem install ronn
In Elektra cross compiling needs two steps. If you get errors like
elektra-export-errors_EXE_LOC not found, go on reading.
In the first step, you need to compile Elektra for the host architecture and install the build tools:
cmake -DINSTALL_BUILD_TOOLS=ON \ -DCMAKE_PREFIX_PATH=$(STAGING_DIR_HOST) \ .. make -j 5 make install -j 5
$(STAGING_DIR_HOST) must be a directory to be found in the later
build process. In particular,
$(STAGING_DIR_HOST)/bin must be in a
directory found by a later
Then you need to compile Elektra again, but for the target architecture.
Now, the build tools such as
elektra-export-errors should be found in
$(STAGING_DIR_HOST)/bin where they were installed before.