Elektra
0.8.17
|
intensively (except for file headers).
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.
After you downloaded and unpacked Elektra you see unusually many folders. The reason is that the Elektra project consists of many activities.
The most important are:
libelektra is the ANSI/ISO C-Core which coordinates the interactions between the user and the plugins.
The plugins have all kinds of dependencies. It is the responsibility of the plugins to find and check them using CMake. The same guidelines apply to all code in the repository including the plugins.
libloader
is responsible for loading the backend modules. It works on various operating systems by using libltdl
. This code is optimized for static linking and win32.
kdb is the commandline-tool to access and initialize the Elektra database.
You are only allowed to break a guideline if there is a good reason to do so. When you do, document the fact, either in the commit message, or as comment next to the code.
Of course, all rules of good software engineering apply: Use meaningful names and keep the software both testable and reusable.
The purpose of the guidelines is to have a consistent style, not to teach programming.
If you see broken guidelines do not hesitate to fix them. At least put a TODO marker to make the places visible.
If you see inconsistency do not hesitate to talk about it with the intent to add a new rule here.
See DESIGN document too, they complement each other.
Split up when those limits are reached. Rationale: Readability with split windows.
elektra
for internal usage. External API either starts with ks
, key
or kdb
./**/
with doxygen style for functions.//
for single line statements about the code in the next line.(
).*
from Pointers.,
of every function argument.const
as much as possible.static
methods if they should not be externally visible..c
, Header files .h
.Example: src/libs/elektra/kdb.c
.cpp
, Header files .hpp
.static
, but anonymous namespaces.Example: src/bindings/cpp/include/kdb.hpp
doxygen
is used to document the API and to build the html and pdf output. We also support the import of Markdown pages. Doxygen 1.8.8 or later is required for this feature (Anyways you can find the API Doc online). Links between Markdown files will be converted with the Markdown Link Converter. Markdown pages are used in the pdf, therefore watch which characters you use and provide a proper encoding!
@
to start Doxygen tags\copydetails
, @copybrief
and @copydetails
intensively (except for file headers).Files should start with:
/** * @file * * @brief <short statement about the content of the file> * * @copyright BSD License (see doc/COPYING or http://www.libelektra.org) */
Note:
@
file
has no parameters.@
brief
should contain a short statement about the content of the file and is needed so that your file gets listed at http://doc.libelektra.org/api/latest/html/files.htmlThe duplication of the filename, author and date is not needed, because this information is tracked using git and doc/AUTHORS already.