$darkmode
Elektra 0.11.0
|
This document provides an introduction in how the source code of libelektra is organized and how and where to add functionality.
After you downloaded and unpacked Elektra you should see some folders. The most important are:
You can find more information about the structure in the README.md
.
The same guidelines apply to all code in the repository including the plugins.
You are only allowed to break a guideline if there is a good reason to do so. When you do, document the fact 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 code that breaks guidelines do not hesitate to fix them or at least open issues.
If you see inconsistency within the rules do not hesitate to open an issue about it.
Code is not only for the computer, but it should be readable for humans, too. Up-to-date code comments are essential to make code understandable for others. Thus please use following techniques (in order of preference):
/**/
and Doxygen, see below.You should also add assertions to state what should be true at a specific position in the code. Their syntax is checked and they are automatically verified at run-time. So they are not only useful for people reading the code but also for tools. Assertions in Elektra are used by:
#include <kdbassert.h>
ELEKTRA_ASSERT (condition, "formatted text to be printed when assert fails", ...)
Note: Do not use assert for user-APIs, always handle arguments of user-APIs like untrusted input.
If the "comment" might be useful to be printed during execution, use logging:
#include <kdblogger.h>
ELEKTRA_LOG ("formatted text to be printed according to log filters", ...)
Read HERE for how to enable the logger.
//
or with /**/
for multi-line comments. Use TODO
to indicate that something is not yet done. Before merging, relevant TODO
s should be fixed or issues created for left-overs.Limits
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
.(
).*
from Pointers.,
of every function argument.The reformat script can ensure most code style rules, but it is obviously not capable of ensuring everything (e.g. naming conventions). So do not give this responsibility out of hands entirely. You can use docker to ensure that you have the correct version of all our reformatting tools at hand. You can also enable that formatting runs automatically before commiting using scripts/dev/enable-pre-commit-hook
and disable it again using scripts/dev/disable-pre-commit-hook
const
as much as possible.static
methods if they should not be externally visible..c
, Header files .h
.elektraMalloc
, elektraFree
.Example: src/libs/elektra/kdb.c
To guarantee consistent formatting we use clang-format
(version 12
) to format all C and C++ code in the repository. Since our build servers also check the style for every pull request you might want to make sure you reformat your C/C++ code changes with this tool.
To find out which version of clang-format
a certain build server uses please check:
and search for the relevant packages (clang-format
, llvm
). Currently we use clang-format 12
On macOS you can install clang-format
using Homebrew either directly:
or by installing the whole LLVM infrastructure:
Please note, that both of these commands will install current versions of clang-format
that might format code a little bit differently than Clang-Format 12
in certain edge cases. If you want you can also install a specific version of LLVM and Clang-Format: e.g. Clang-Format 11
using LLVM 11
:
In Debian (Sid) the package for Clang-Format 12
is called clang-format-12
:
For the basic use cases you can use clang-format
directly. To do that, just call the tool using the option -i
and specify the name of the files you want to reformat. For example, if you want to reformat the file src/bindings/cpp/include/kdb.hpp
you can use the following command:
While this works fine, if you want to format only a small number of file, formatting multiple files can be quite tedious. For that purpose you can use the script `reformat-c` that reformats all C and C++ code in Elektra’s code base
If you work on Elektra’s code base regularly you might want to integrate the formatting step directly in your development setup. ClangFormat’s homepage includes a list of integrations for various tools that should help you to do that. Even if this webpage does not list any integrations for your favorite editor or IDE, you can usually add support for external tools such as clang-format
to advanced editors or IDEs pretty easily.
While TextMate supports clang-format
for the current file directly via the keyboard shortcut ctrl
+⇧
+H
, the editor does not automatically reformat the file on save. To do that
callback.document.will-save
into the field “Semantic Class”, andAfter that change TextMate will reformat C and C++ code with clang-format
every time you save a file.
.cpp
, Header files .hpp
.static
, but anonymous namespaces.Example: src/bindings/cpp/include/kdb.hpp
We use a similar style for CMake as we do for other code:
(
).set
instead of SET
)We use cmake-format
to reformat code according to the guidelines given above. Since cmake-format
currently does not support tabs, we use the standard command unexpand
to fix this issue. For example, to reformat the file CMakeLists.txt
in the root folder of the repository we use the following command:
Since cmake-format
is written in Python you usually install it via Python’s package manager pip
:
Please make sure, that you install the correct version (0.6.13
) of cmake-format:
since otherwise the formatted code might look quite different.
We also use the moreutils in our CMake formatting script, which you can install on macOS using Homebrew:
and on Debian using apt-get
:
If you want to reformat the whole codebase you can use the script `reformat-cmake`:
To reformat specific files add a list of file paths after the command:
If you work on CMake code quite often you probably want to integrate cmake-format into your development workflow. The homepage of cmake-format list some integration options.
While TextMate does not support cmake-format directly, you can quickly create a command that applies cmake-format
every time you save a CMake file yourself. The steps below show one option to do that.
^
+ ⌥
+ ⌘
+ B
⌘
+ N
source.cmake
in the field “Scope Selector”^
+ ⇧
+ H
as “Key Equivalent”callback.document.will-save
into the field “Semantic Class”Copy the following code into the text field:
``` #!/bin/bash
set -o pipefail if ! "${TM_CMAKE_FORMAT:-cmake-format}" - | ${TM_CMAKE_FORMAT_FILTER:-tee}; then . "$TM_SUPPORT_PATH/lib/bash_init.sh" exit_show_tool_tip fi ```
⌘
+ S
unexpand
in the variable TM_CMAKE_FORMAT_FILTER
. To do that save the textin a file called .tm_properties
in the root of Elektra’s repository.
Please follow Google Java Style Guide for Groovy (used by Jenkins) and Java files.
Most notably use:
If you want to reformat all Java files in the repository you can use the script `reformat-java`:
To reformat specific files add a list of file paths after the command:
We use prettier
to format JavaScript files.
On macOS you can install prettier
using Homebrew:
To install prettier
using Node’s package manager npm you can use the command below
To format all JavaScript files in the repository you can use the script `reformat-javascript`:
To format only some files, please specify a list of filenames after the command:
.md
or integrated within Doxygen comments#
characters at the left side of headers/titlesREADME.md
and tutorials should be written exclusively with shell recorder syntax so that we know that the code in the tutorial produces output as expectedls
or mkdir
.We use prettier
to format the documentation according to the guidelines given above.
Under certain exceptional circumstances you might want to prevent prettier
from formatting certain parts of a Markdown file. To do that you can
<!-- prettier-ignore-start -->
and <!-- prettier-ignore-end -->
tags, or<!-- prettier-ignore -->
to disable formatting till the end of a fileFor information on how to install the tool, please take a look at “JavaScript Guidelines” → “Prettier” → “Installation”.
You can format all Markdown files in the repository using the script `reformat-markdown`:
To format only some files, please specify a list of filenames after the command:
The homepage of Prettier lists various options to integrate the tool into your workflow.
To reformat a Markdown document in TextMate every time you save it, please follow the steps listed below.
^
+ ⌥
+ ⌘
+ B
⌘
+ N
text.html.markdown
in the field “Scope Selector”^
+ ⇧
+ H
as “Key Equivalent”callback.document.will-save
into the field “Semantic Class”Copy the following code into the text field:
``` #!/bin/bash
if ! "${TM_PRETTIER:-prettier}" –stdin –stdin-filepath "${TM_FILEPATH}" then . "$TM_SUPPORT_PATH/lib/bash_init.sh" exit_show_tool_tip fi ```
⌘
+ S
Every shell script must start with either of two shebangs:
#!/bin/sh
#!/usr/bin/env <shell>
, where <shell>
is an appropriate shell, e.g. #!/usr/bin/env bash
Note that even if a shebang is added by a preprocessor macro or similar code generation tools, it must also be present in the templated file.
We use shfmt
to format Shell files in the repository.
You can install shfmt
on macOS using Homebrew:
shfmt’s GitHub release page offers binaries for various operating systems. For example, to install the binary for the current user on Linux you can use the following command:
Please note that you have to make sure, that your PATH
includes $HOME/bin
, if you use the command above:
We provide the script `reformat-shell` that formats the whole codebase with shfmt
:
You can also reformat specific files by listing filenames after the script:
The GitHub project page of shfmt
offers some options to integrate the tool into your development workflow here.
The steps below show you how to create a TextMate command that formats a documents with shfmt
every time you save it.
^
+ ⌥
+ ⌘
+ B
⌘
+ N
source.shell
in the field “Scope Selector”^
+ ⇧
+ H
as “Key Equivalent”callback.document.will-save
into the field “Semantic Class”Copy the following code into the text field:
``` #!/bin/bash
if ! "${TM_SHFMT_FORMAT:-shfmt}" -s -sr; then . "$TM_SUPPORT_PATH/lib/bash_init.sh" exit_show_tool_tip fi ```
⌘
+ S
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 (Anyway, 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@copydoc
, @copybrief
and @copydetails
intensively (except for file headers).Further Doxygen documentation can be found in the Doxygen README.
Files should start with:
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 https://doc.libelektra.org/api/master/html/files.htmlThe duplication of the filename, author and date is not needed, because this information is tracked using Git and doc/AUTHORS.md already.