$darkmode
Elektra 0.11.0
Header File Structure

kdb.h contains the public API for both libelektra-core and libelektra-kdb. It is confusing and makes it hard to see what library a function actually belongs to.

The big problem is kdbprivate.h. It has two main problems:

  1. It contains stuff from many different libraries. I found at least libelektra-core, libelektra-kdb and libelektra-highlevel.
  2. It contains things that are different levels of "private".

The decision is split into 4 subsections "Libraries", "Plugins", "Tools" and "Tests", because the different parts of Elektra have different requirements.

A library can be monolithic or modularized. Monolithic libraries should be small and bigger libraries with large APIs should be modularized.

A monolithic library foo may have these headers (covering categories 3 & 4 from above):

A modularized library foo may have these headers (covering categories 3 & 4 from above):

Additionally, all libraries may also have private headers:

Plugins do not declare their API via header files. Their headers are never installed and can be named any way the developer wants.

Importantly, however, headers belonging to plugins must not be used outside the plugin.

Tools do not have a C API, so their headers are also never installed. Consequently, there are no naming rules for header files belonging to tools.

Just like with plugins, the headers belonging to tools must not be used elsewhere.

For category 2 from above (private but needs to be tested), one of the following should be done:

  1. Declare functions as static in a .c file and #include "" this file from the test.
  2. Add a private non-installed header (e.g., src/lib/foo/testapi.h) that declares the API that needs testing, #include "" that and compile the test sources together with the .o files from the library (static linking).

If a symbol is needed in only one file and for tests, option 1 should be preferred. For symbols that are used in multiple files, a header needs to exist anyway. In any case, these unit tests should not be installed and should statically link the library into the test executable. This way we don't pollute our symbols.map files and keep the number of exported symbols down.