This document provides an introduction in how the source code of
libelektra is organized and how and where to add functionality.

Make sure to read DESIGN together with this document.

= Folder structure =

After you downloaded and unpacked Elektra you see untypically many
folders. The reason is that Elektra project consists of many activities.

The most important are:
src ... Here is the source for the library and the tools itself.
tests ... Is the testing framework for the Source

= Source Code =

libelektra is the ANSI/ISO C-Core which does interacts between the user
and the backends.

libhelper needs POSIX (at the moment) and provides common functionality
between backends. Next to locking, methods to convert keys to filenames
it takes care of utf8 conversations.

libloader is responsible for loading the backend modules. It works for
various operating systems by using libltdl, but has an optimized code
for static linking and win32.

kdb and preload are tools to access and initialize the Elektra database.

= Compiling =

To compile a program using Elektra, use:
 $ cc `pkg-config --cflags elektra` -o myapp.o -c myapp.c
 $ cc `pkg-config --libs elektra`   -o myapp myapp.o

To compile a backend for Elektra, use:
 $ cc -fpic `pkg-config --cflags elektra` -o myback.o -c myback.c
 $ cc -shared -fpic `pkg-config --libs elektra` -o libelektra-myback.so myback.o

= Add a plugin =

To add a backend, make a new folder according to your pluginname below src/plugins.
Copy the contents from src/plugins/template to your new folder.
Rename it from template.* to the plugins name.
Substitute all template names to your backendname in both files using:

 $ sed -i s/TEMPLATE/$ALLCAP/g $1.c $1.h CMakeLists.txt
 $ sed -i s/Template/$Firstcap/g $1.c $1.h CMakeLists.txt
 $ sed -i s/template/$allsmall/g $1.c $1.h CMakeLists.txt

If your plugin is not portable you can write some detection code if your plugin
would compile on the current system or not. If it is known not to compile you
can remove your backend using the Macro remove_plugin.

= Search path of backends =

Backends and libraries (libelektratools) are loaded with the libloader.
libloader uses different techniques for different uses cases and operating
systems:
1) Static case
2) Win32
3) Generic libtldl

In the static case it looks up symbols which were compiled into the .a archive
previously. Looking up works with the backend_symbols.c generated by exportsymbols.sh.
The collecting of the symbols is done by linking the output from `cat objects`.
The file objects is generated by exportobjects.sh.

The generic libtldl searchs for .la or .so (or others e.g. dynlib on mac) in
following directories (can be changed by configure options):

backenddir, default /usr/lib/elektra
hlvlbackenddir, default ulibdir, for libelektratools
ulibdir, default /usr/lib
libdir, default /lib

The prefered place for backends is of course backenddir. libdir might be useful
for backends which are needed at the bootup process.


= Regular expressions =

Here is a collection of regular expressions to help you generate some code.
To do so just delete the old text and copy the text which should be used to generate
from to the appropriate place. Mark it with 'V', press ':' and then 'ctrl-f'.
Now open the file REGEXP with :r and press enter at the suitable line.

== KDBCap ==

use vim regular expression in REGEXP to generate the getters out of KDBCap struct

@see kdbStrError for a similar one

to enter ^M use: ^Q and <enter>
to enter ^I use: <tab>
explanation of wildcards:
:'<,'>s>>-------substitute visual block
%>------>-------used as seperate mark
^>------>-------start of line
\s>----->-------whitespaces
\([A-Z_]*\)>----catch something containing A-Z and _ and store it in \1
\=>----->-------means 0 or 1 time
\*>----->-------the * itself
\!>----->-------the ! itself

== Errors ==

To get this format out from kdb.h you can use vim regular expression in REGEXP
to enter ^M use: ^Q and <enter>
to enter ^I use: <tab>
explanation of wildcards:
:'<,'>s		substitute visual block
%		used as seperate mark
^		start of line
\s		whitespaces
\([A-Z_]*\)	catch something containing A-Z and _ and store it in \1
\=		means 0 or 1 time
\*		the * itself
\!		the ! itself

