This document provides an introduction in how the source code of libelektra is organized and how and where to add functionality.\hypertarget{doc_CODING_md_autotoc_md963}{}\doxysection{Folder structure}\label{doc_CODING_md_autotoc_md963}
After you downloaded and unpacked Elektra you should see some folders. The most important are\+:
\begin{DoxyItemize}
\item {\bfseries{src\+:}} This directory contains the source of the libraries, tools and plugins.
\item {\bfseries{doc\+:}} General documentation for the project and the core library.
\item {\bfseries{examples\+:}} Examples on how to use the core library.
\item {\bfseries{tests\+:}} Contains the testing framework for the source ({\bfseries{src}}).
\end{DoxyItemize}
More about the structure you find in the folder\textquotesingle{}s {\ttfamily R\+E\+A\+D\+M\+E.\+md}.\hypertarget{doc_CODING_md_autotoc_md964}{}\doxysection{General Information}\label{doc_CODING_md_autotoc_md964}
\begin{DoxyItemize}
\item Keep to the style that is already present, except if this document says otherwise\+: then please open an issue for offending code.
\item We use Unix line endings
\item Large files should be in \href{http://blobs.libelektra.org/}{\texttt{ http\+://blobs.\+libelektra.\+org/}} or \href{https://rawdata.libelektra.org}{\texttt{ https\+://rawdata.\+libelektra.\+org}}
\item `find . -\/not -\/regex '\mbox{[}/.a-\/z\+A-\/\+Z0-\/9\+\_\+-\/\mbox{]}$\ast$\textquotesingle{}\`{} should not find your file names
\end{DoxyItemize}\hypertarget{doc_CODING_md_autotoc_md965}{}\doxysection{Source Code}\label{doc_CODING_md_autotoc_md965}
The same guidelines apply to all code in the repository including the plugins.\hypertarget{doc_CODING_md_autotoc_md966}{}\doxysubsection{General Guidelines}\label{doc_CODING_md_autotoc_md966}
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.\hypertarget{doc_CODING_md_autotoc_md967}{}\doxysubsection{Code Comments}\label{doc_CODING_md_autotoc_md967}
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)\+:
\begin{DoxyEnumerate}
\item Comment functions with {\ttfamily /$\ast$$\ast$/} and Doxygen, see below.
\item 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\+:
{\ttfamily \#include $<$\mbox{\hyperlink{kdbassert_8h}{kdbassert.\+h}}$>$}
{\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+S\+S\+E\+RT (condition, \char`\"{}formatted text to be printed when assert fails\char`\"{}, ...)}
Note\+: Do not use assert for user-\/\+A\+P\+Is, always handle arguments of user-\/\+A\+P\+Is like untrusted input.
\item If the \char`\"{}comment\char`\"{} might be useful to be printed during execution, use logging\+:
{\ttfamily \#include $<$\mbox{\hyperlink{kdblogger_8h}{kdblogger.\+h}}$>$}
{\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+OG (\char`\"{}formatted text to be printed according to log filters\char`\"{}, ...)}
Read \mbox{\hyperlink{doc_dev_logging_md}{H\+E\+RE}} for how to enable the logger.
\item Otherwise comment within source with {\ttfamily //} or with {\ttfamily /$\ast$$\ast$/} for multi-\/line comments. Use {\ttfamily T\+O\+DO} to indicate that something is not yet done. Before merging, relevant {\ttfamily T\+O\+DO}s should be fixed or \href{https://issues.libelektra.org}{\texttt{ issues}} created for left-\/overs.
\end{DoxyEnumerate}\hypertarget{doc_CODING_md_autotoc_md968}{}\doxysubsection{Coding Style}\label{doc_CODING_md_autotoc_md968}
\begin{DoxyItemize}
\item Limits
\begin{DoxyItemize}
\item Functions should not exceed 100 lines.
\item Files should not exceed 1000 lines.
\item A line should not be longer than 140 characters.
\end{DoxyItemize}
Split up when those limits are reached. Rationale\+: Readability with split windows.
\item Indentation
\begin{DoxyItemize}
\item Use tabs for indentation.
\item One tab equals 8 spaces.
\end{DoxyItemize}
\item Blocks
\begin{DoxyItemize}
\item Use blocks even for single line statements.
\item Curly braces go on a line on their own on the previous indentation level.
\item Avoid multiple variable declarations at one place.
\item Declare Variables as late as possible, preferable within blocks.
\end{DoxyItemize}
\item Naming
\begin{DoxyItemize}
\item Use camel\+Case for functions and variables.
\item Start types with upper-\/case, everything else with lower-\/case.
\item Prefix names with {\ttfamily elektra} for internal usage. External A\+PI either starts with {\ttfamily ks}, {\ttfamily key} or {\ttfamily kdb}.
\end{DoxyItemize}
\item Whitespaces
\begin{DoxyItemize}
\item Use space before and after equal when assigning a value.
\item Use space before round parenthesis ( {\ttfamily (} ).
\item Use space before and after {\ttfamily $\ast$} from Pointers.
\item Use space after {\ttfamily ,} of every function argument.
\end{DoxyItemize}
\end{DoxyItemize}
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 \mbox{\hyperlink{doc_tutorials_run_reformatting_script_with_docker_md}{use docker}} to ensure that you have the correct version of all our reformatting tools at hand.\hypertarget{doc_CODING_md_autotoc_md969}{}\doxysubsection{C Guidelines}\label{doc_CODING_md_autotoc_md969}
\begin{DoxyItemize}
\item The compiler shall not emit any warning (or error).
\item Use goto only for error situations.
\item Use {\ttfamily const} as much as possible.
\item Use {\ttfamily static} methods if they should not be externally visible.
\item C-\/\+Files have extension {\ttfamily .c}, Header files {\ttfamily .h}.
\item Use internal functions\+: prefer to use {\ttfamily elektra\+Malloc}, {\ttfamily elektra\+Free}.
\end{DoxyItemize}
{\bfseries{Example\+:}} \href{/home/mpranj/workspace/libelektra/src/libs/elektra/kdb.c}{\texttt{ src/libs/elektra/kdb.\+c}}\hypertarget{doc_CODING_md_autotoc_md970}{}\doxysubsubsection{Clang Format}\label{doc_CODING_md_autotoc_md970}
To guarantee consistent formatting we use \href{https://clang.llvm.org/docs/ClangFormat.html}{\texttt{ {\ttfamily clang-\/format}}} (version {\ttfamily 9}) 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 {\ttfamily clang-\/format} a certain build server uses please check\+:
\begin{DoxyItemize}
\item the Debian sid Docker image,
\item the Travis configuration file , and
\item the Cirrus configuration file
\end{DoxyItemize}
and search for the relevant packages ({\ttfamily clang-\/format}, {\ttfamily llvm}). Currently we use clang-\/format {\ttfamily 9}
\begin{DoxyItemize}
\item in the Travis configuration file ,
\item in the Debian sid Docker container on the Jenkins build server, and
\item in the Cirrus mac\+OS build jobs.
\end{DoxyItemize}\hypertarget{doc_CODING_md_autotoc_md971}{}\doxyparagraph{Installation}\label{doc_CODING_md_autotoc_md971}
\doxysubparagraph*{mac\+OS}
On mac\+OS you can install {\ttfamily clang-\/format} using \href{https://brew.sh}{\texttt{ Homebrew}} either directly\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{brew install clang-\/format}
\end{DoxyCode}
or by installing the whole \href{http://llvm.org}{\texttt{ L\+L\+VM}} infrastructure\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{brew install llvm}
\end{DoxyCode}
. Please note, that both of these commands will install current versions of {\ttfamily clang-\/format} that might format code a little bit differently than Clang-\/\+Format {\ttfamily 9} in certain edge cases. If you want you can also install Clang-\/\+Format {\ttfamily 9} using L\+L\+VM {\ttfamily 9}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{brew install llvm@9}
\end{DoxyCode}
\doxysubparagraph*{Debian}
In Debian the package for Clang-\/\+Format {\ttfamily 9} is called {\ttfamily clang-\/format-\/9}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{apt-\/get install clang-\/format-\/9}
\end{DoxyCode}
\hypertarget{doc_CODING_md_autotoc_md972}{}\doxyparagraph{Usage}\label{doc_CODING_md_autotoc_md972}
For the basic use cases you can use {\ttfamily clang-\/format} directly. To do that, just call the tool using the option {\ttfamily -\/i} and specify the name of the files you want to reformat. For example, if you want to reformat the file {\ttfamily \mbox{\hyperlink{kdb_8hpp}{src/bindings/cpp/include/kdb.\+hpp}}} you can use the following command\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{\# On some systems such as Debian the `clang-\/format` executable also contains}
\DoxyCodeLine{\# the version number. For those systems, please replace `clang-\/format`,}
\DoxyCodeLine{\# with `clang-\/format-\/9` in the command below.}
\DoxyCodeLine{clang-\/format -\/i src/bindings/cpp/include/kdb.hpp}
\end{DoxyCode}
. 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
\begin{DoxyCode}{0}
\DoxyCodeLine{scripts/dev/reformat-\/c \# This script will probably take some seconds to execute}
\end{DoxyCode}
\hypertarget{doc_CODING_md_autotoc_md973}{}\doxyparagraph{Tool Integration}\label{doc_CODING_md_autotoc_md973}
If you work on Elektra’s code base regularly you might want to integrate the formatting step directly in your development setup. \href{https://clang.llvm.org/docs/ClangFormat.html}{\texttt{ Clang\+Format’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 I\+DE, you can usually add support for external tools such as {\ttfamily clang-\/format} to advanced editors or I\+D\+Es pretty easily.
\doxysubparagraph*{Text\+Mate}
While \href{https://macromates.com}{\texttt{ Text\+Mate}} supports {\ttfamily clang-\/format} for the current file directly via the keyboard shortcut {\ttfamily ctrl}+{\ttfamily ⇧}+{\ttfamily H}, the editor does not automatically reformat the file on save. To do that
\begin{DoxyEnumerate}
\item open the bundle editor (“\+Bundles” → “\+Edit Bundles”),
\item navigate to the “\+Reformat Code” item of the C bundle (“\+C” → “\+Menu Actions” → “\+Reformat Code”),
\item insert {\ttfamily callback.\+document.\+will-\/save} into the field “\+Semantic Class”, and
\item change the menu option for the field “\+Save” to “\+Nothing”
\end{DoxyEnumerate}
. After that change Text\+Mate will reformat C and C++ code with {\ttfamily clang-\/format} every time you save a file.\hypertarget{doc_CODING_md_autotoc_md974}{}\doxysubsection{C++ Guidelines}\label{doc_CODING_md_autotoc_md974}
\begin{DoxyItemize}
\item Everything as in C if not noted otherwise.
\item Do not use goto at all, use R\+A\+II instead.
\item Do not use raw pointers, use smart pointers instead.
\item C++-\/\+Files have extension {\ttfamily .cpp}, Header files {\ttfamily .hpp}.
\item Do not use {\ttfamily static}, but anonymous namespaces.
\item Write everything within namespaces and do not prefix names.
\item Oriented towards \href{https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md}{\texttt{ more safe and modern usage}}.
\end{DoxyItemize}
{\bfseries{Example\+:}} \href{/home/mpranj/workspace/libelektra/src/bindings/cpp/include/kdb.hpp}{\texttt{ src/bindings/cpp/include/kdb.\+hpp}}\hypertarget{doc_CODING_md_autotoc_md975}{}\doxysubsection{C\+Make Guidelines}\label{doc_CODING_md_autotoc_md975}
We use a similar style for C\+Make as we do for other code\+:
\begin{DoxyItemize}
\item The length of a functions should not exceed 100 lines.
\item The length of a file should not exceed 1000 lines.
\item A line should not be longer than 140 characters.
\item Use tabs for indentation.
\item One tab equals 8 spaces.
\item Declare variables as late as possible, preferable within blocks.
\item Add a space character before round parenthesis ( {\ttfamily (} ).
\item Use lower case for command names (e.\+g. {\ttfamily set} instead of {\ttfamily S\+ET})
\end{DoxyItemize}\hypertarget{doc_CODING_md_autotoc_md976}{}\doxysubsubsection{cmake format}\label{doc_CODING_md_autotoc_md976}
We use \href{https://github.com/cheshirekow/cmake_format}{\texttt{ {\ttfamily cmake-\/format}}} to reformat code according to the guidelines given above. Since {\ttfamily cmake-\/format} currently does not support tabs, we use the standard command {\ttfamily unexpand} to fix this issue. For example, to reformat the file {\ttfamily C\+Make\+Lists.\+txt} in the root folder of the repository we use the following command\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{\# This command uses `sponge`, which is part of the [moreutils](https://joeyh.name/code/moreutils/) package.}
\DoxyCodeLine{cmake-\/format CMakeLists.txt | unexpand | sponge CMakeLists.txt}
\end{DoxyCode}
\hypertarget{doc_CODING_md_autotoc_md977}{}\doxyparagraph{Installation}\label{doc_CODING_md_autotoc_md977}
Since {\ttfamily cmake-\/format} is written in \href{https://www.python.org}{\texttt{ Python}} you usually install it via Python’s package manager {\ttfamily pip}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{\# Install cmake format `0.6.3` with support for YAML config files}
\DoxyCodeLine{pip install cmake-\/format[yaml]==0.6.3}
\end{DoxyCode}
. Please make sure, that you install the correct version ({\ttfamily 0.\+6.\+3}) of cmake format\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{cmake-\/format -\/-\/version}
\DoxyCodeLine{\#> 0.6.3}
\end{DoxyCode}
, since otherwise the formatted code might look quite different.
We also use the \href{https://joeyh.name/code/moreutils}{\texttt{ moreutils}} in our C\+Make formatting script, which you can install on mac\+OS using \href{https://brew.sh}{\texttt{ Homebrew}}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{brew install moreutils}
\end{DoxyCode}
and on Debian using {\ttfamily apt-\/get}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{apt-\/get install moreutils}
\end{DoxyCode}
\hypertarget{doc_CODING_md_autotoc_md978}{}\doxyparagraph{Usage}\label{doc_CODING_md_autotoc_md978}
If you want to reformat the whole codebase you can use the script \`{}reformat-\/cmake\`{}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{scripts/dev/reformat-\/cmake \# Running this script for the whole code base takes some time.}
\end{DoxyCode}
. To reformat specific files add a list of file paths after the command\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{\# The command below reformats the file `cmake/CMakeLists.txt`.}
\DoxyCodeLine{scripts/dev/reformat-\/cmake cmake/CMakeLists.txt}
\end{DoxyCode}
\hypertarget{doc_CODING_md_autotoc_md979}{}\doxyparagraph{Tool Integration}\label{doc_CODING_md_autotoc_md979}
If you work on C\+Make code quite often you probably want to integrate cmake format into your development workflow. The homepage of \href{https://github.com/cheshirekow/cmake_format\#integrations}{\texttt{ cmake format}} list some integration options.
\doxysubparagraph*{Text\+Mate}
While Text\+Mate does not support cmake format directly, you can quickly create a command that applies {\ttfamily cmake-\/format} every time you save a C\+Make file yourself. The steps below show one option to do that.
\begin{DoxyEnumerate}
\item Open the “\+Bundle Editor”\+: Press {\ttfamily $^\wedge$} + {\ttfamily ⌥} + {\ttfamily ⌘} + {\ttfamily B}
\item Create a new command\+:
\begin{DoxyEnumerate}
\item Press {\ttfamily ⌘} + {\ttfamily N}
\item Select “\+Command”
\item Press the button “\+Create”
\end{DoxyEnumerate}
\item Configure your new command
\begin{DoxyEnumerate}
\item Use “\+Reformat Document” or a similar text as “\+Name”
\item Enter {\ttfamily source.\+cmake} in the field “\+Scope Selector”
\item Use {\ttfamily $^\wedge$} + {\ttfamily ⇧} + {\ttfamily H} as “\+Key Equivalent”
\item Copy the text {\ttfamily callback.\+document.\+will-\/save} into the field “\+Semantic Class”
\item Select “\+Document” as “\+Input”
\item Select “\+Replace Document” in the dropdown menu for the option “\+Output”
\item Select “\+Line Interpolation” in the menu “\+Caret Placement”
\item Copy the following code into the text field\+:
\`{}\`{}\`{} \#!/bin/bash
set -\/o pipefail if ! \char`\"{}\$\{\+T\+M\+\_\+\+C\+M\+A\+K\+E\+\_\+\+F\+O\+R\+M\+A\+T\+:-\/cmake-\/format\}\char`\"{} -\/ $\vert$ \$\{T\+M\+\_\+\+C\+M\+A\+K\+E\+\_\+\+F\+O\+R\+M\+A\+T\+\_\+\+F\+I\+L\+T\+ER\+:-\/tee\}; then . \char`\"{}\$\+T\+M\+\_\+\+S\+U\+P\+P\+O\+R\+T\+\_\+\+P\+A\+T\+H/lib/bash\+\_\+init.\+sh\char`\"{} exit\+\_\+show\+\_\+tool\+\_\+tip fi \`{}\`{}\`{}
\item Save your new command\+: {\ttfamily ⌘} + {\ttfamily S}
\item Store the value {\ttfamily unexpand} in the variable {\ttfamily T\+M\+\_\+\+C\+M\+A\+K\+E\+\_\+\+F\+O\+R\+M\+A\+T\+\_\+\+F\+I\+L\+T\+ER}. To do that save the text
\end{DoxyEnumerate}
\end{DoxyEnumerate}
\begin{DoxyCode}{0}
\DoxyCodeLine{TM\_CMAKE\_FORMAT\_FILTER = "unexpand"}
\end{DoxyCode}
in a file called \href{https://macromates.com/blog/2011/git-style-configuration}{\texttt{ {\ttfamily .tm\+\_\+properties}}} in the root of Elektra’s repository.\hypertarget{doc_CODING_md_autotoc_md980}{}\doxysubsection{Groovy Guidelines}\label{doc_CODING_md_autotoc_md980}
Please follow \href{https://google.github.io/styleguide/javaguide.html}{\texttt{ Google Java Style Guide}} for Groovy (used by Jenkins) files.
Most notably use\+:
\begin{DoxyItemize}
\item 2 spaces for indentation
\item Variable and function names in lower\+Camel\+Case
\item K \& R style brackets
\end{DoxyItemize}\hypertarget{doc_CODING_md_autotoc_md981}{}\doxysubsection{Java}\label{doc_CODING_md_autotoc_md981}
We use a similar style for Java and C/\+C++ code. This means we also use {\ttfamily clang-\/format} to format Java code. For more information on how to install {\ttfamily clang-\/format}, please take a look at the subheading “\+Clang Format” of the {\bfseries{“C Guidelines”}}.\hypertarget{doc_CODING_md_autotoc_md982}{}\doxysubsubsection{Clang Format}\label{doc_CODING_md_autotoc_md982}
\hypertarget{doc_CODING_md_autotoc_md983}{}\doxyparagraph{Usage}\label{doc_CODING_md_autotoc_md983}
If you want to reformat all Java files in the repository you can use the script \`{}reformat-\/java\`{}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{scripts/dev/reformat-\/java}
\end{DoxyCode}
. To reformat specific files add a list of file paths after the command\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{\# The command below reformats the file `cmake/CMakeLists.txt`.}
\DoxyCodeLine{scripts/dev/reformat-\/java src/bindings/jna/libelektra4j/src/main/java/org/libelektra/KDB.java}
\end{DoxyCode}
\doxysubparagraph*{Text\+Mate}
The steps below show you how to create a \href{https://macromates.com}{\texttt{ Text\+Mate}} command that formats a documents with \mbox{[}{\ttfamily clang-\/format}\mbox{]}\mbox{[}\mbox{]} every time you save it.
\begin{DoxyEnumerate}
\item Open the “\+Bundle Editor”\+: Press {\ttfamily $^\wedge$} + {\ttfamily ⌥} + {\ttfamily ⌘} + {\ttfamily B}
\item Create a new command\+:
\begin{DoxyEnumerate}
\item Press {\ttfamily ⌘} + {\ttfamily N}
\item Select “\+Command”
\item Press the button “\+Create”
\end{DoxyEnumerate}
\item Configure your new command
\begin{DoxyEnumerate}
\item Use “\+Reformat Document” or a similar text as “\+Name”
\item Enter {\ttfamily source.\+java} in the field “\+Scope Selector”
\item Use {\ttfamily $^\wedge$} + {\ttfamily ⇧} + {\ttfamily H} as “\+Key Equivalent”
\item Copy the text {\ttfamily callback.\+document.\+will-\/save} into the field “\+Semantic Class”
\item Select “\+Document” as “\+Input”
\item Select “\+Replace Input” in the dropdown menu for the option “\+Output”
\item Select “\+Line Interpolation” in the menu “\+Caret Placement”
\item Copy the following code into the text field\+:
\`{}\`{}\`{} \#!/bin/bash
if ! \char`\"{}\$\{\+T\+M\+\_\+\+C\+L\+A\+N\+G\+\_\+\+F\+O\+R\+M\+A\+T\+:-\/clang-\/format\}\char`\"{} \textbackslash{} -\/style=\char`\"{}\$\{\+T\+M\+\_\+\+C\+L\+A\+N\+G\+\_\+\+F\+O\+R\+M\+A\+T\+\_\+\+S\+T\+Y\+L\+E\+:-\/file\}\char`\"{} \textbackslash{} -\/assume-\/filename=\char`\"{}\$\{\+T\+M\+\_\+\+F\+I\+L\+E\+P\+A\+T\+H\}\char`\"{}; then . \char`\"{}\$\+T\+M\+\_\+\+S\+U\+P\+P\+O\+R\+T\+\_\+\+P\+A\+T\+H/lib/bash\+\_\+init.\+sh\char`\"{} exit\+\_\+show\+\_\+tool\+\_\+tip fi \`{}\`{}\`{}
\item Save your new command\+: {\ttfamily ⌘} + {\ttfamily S}
\end{DoxyEnumerate}
\end{DoxyEnumerate}\hypertarget{doc_CODING_md_autotoc_md984}{}\doxysubsection{Java\+Script Guidelines}\label{doc_CODING_md_autotoc_md984}
\hypertarget{doc_CODING_md_autotoc_md985}{}\doxysubsubsection{Prettier}\label{doc_CODING_md_autotoc_md985}
We use \href{https://prettier.io}{\texttt{ {\ttfamily prettier}}} to format Java\+Script files.\hypertarget{doc_CODING_md_autotoc_md986}{}\doxyparagraph{Installation}\label{doc_CODING_md_autotoc_md986}
\doxysubparagraph*{mac\+OS}
On mac\+OS you can install \href{https://prettier.io}{\texttt{ {\ttfamily prettier}}} using \href{https://brew.sh}{\texttt{ Homebrew}}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{brew install prettier}
\end{DoxyCode}
\doxysubparagraph*{General}
To install \href{https://prettier.io}{\texttt{ {\ttfamily prettier}}} using Node’s package manager \href{https://www.npmjs.com}{\texttt{ npm}} you can use the command below
\begin{DoxyCode}{0}
\DoxyCodeLine{npm install -\/-\/global prettier@1.19.1}
\end{DoxyCode}
\hypertarget{doc_CODING_md_autotoc_md987}{}\doxyparagraph{Usage}\label{doc_CODING_md_autotoc_md987}
To format all Java\+Script files in the repository you can use the script \`{}reformat-\/javascript\`{}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{scripts/dev/reformat-\/javascript}
\end{DoxyCode}
. To format only some files, please specify a list of filenames after the command\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{scripts/dev/reformat-\/markdown src/tools/qt-\/gui/qml/ErrorDialogCreator.js \# Reformat this file}
\end{DoxyCode}
\hypertarget{doc_CODING_md_autotoc_md988}{}\doxysubsection{Markdown Guidelines}\label{doc_CODING_md_autotoc_md988}
\begin{DoxyItemize}
\item File Ending is {\ttfamily .md} or integrated within Doxygen comments
\item Only use {\ttfamily \#} characters at the left side of headers/titles
\item Use \href{https://help.github.com/en/articles/creating-and-highlighting-code-blocks}{\texttt{ fences}} for code/examples
\item Prefer fences which indicate the used language for better syntax highlighting
\item Fences with sh are for the shell recorder syntax
\item {\ttfamily R\+E\+A\+D\+M\+E.\+md} and tutorials should be written exclusively with shell recorder syntax so that we know that the code in the tutorial produces output as expected
\item Please use \href{https://en.wiktionary.org/wiki/title_case}{\texttt{ {\bfseries{title-\/case}}}} for headings in the general documentation.
\item For man pages please use {\bfseries{only capital letters for subheadings}} and only {\bfseries{small letters for the main header}}. We use this header style to match the look and feel of man pages for Unix tools such as {\ttfamily ls} or {\ttfamily mkdir}.
\end{DoxyItemize}\hypertarget{doc_CODING_md_autotoc_md989}{}\doxysubsubsection{Prettier}\label{doc_CODING_md_autotoc_md989}
We use \href{https://prettier.io}{\texttt{ {\ttfamily prettier}}} to format the documentation according to the guidelines given above.
Under certain {\bfseries{exceptional}} circumstances you might want to prevent {\ttfamily prettier} from formatting certain parts of a Markdown file. To do that you can
\begin{DoxyItemize}
\item enclose the Markdown code in {\ttfamily $<$!-\/-\/ prettier-\/ignore-\/start -\/-\/$>$} and {\ttfamily $<$!-\/-\/ prettier-\/ignore-\/end -\/-\/$>$} tags, or
\item use {\ttfamily $<$!-\/-\/ prettier-\/ignore -\/-\/$>$} to disable formatting till the end of a file
\end{DoxyItemize}\hypertarget{doc_CODING_md_autotoc_md990}{}\doxyparagraph{Installation}\label{doc_CODING_md_autotoc_md990}
For information on how to install the tool, please take a look at “\+Java\+Script Guidelines” → “\+Prettier” → “\+Installation”.\hypertarget{doc_CODING_md_autotoc_md991}{}\doxyparagraph{Usage}\label{doc_CODING_md_autotoc_md991}
You can format all Markdown files in the repository using the script \`{}reformat-\/markdown\`{}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{scripts/dev/reformat-\/markdown}
\end{DoxyCode}
. To format only some files, please specify a list of filenames after the command\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{scripts/dev/reformat-\/markdown doc/CODING.md \# Reformat this file}
\end{DoxyCode}
\hypertarget{doc_CODING_md_autotoc_md992}{}\doxyparagraph{Tool Integration}\label{doc_CODING_md_autotoc_md992}
The \href{https://prettier.io}{\texttt{ homepage of Prettier}} lists various options to integrate the tool into your workflow.
\doxysubparagraph*{Text\+Mate}
To reformat a Markdown document in \href{https://macromates.com}{\texttt{ Text\+Mate}} every time you save it, please follow the steps listed below.
\begin{DoxyEnumerate}
\item Open the “\+Bundle Editor”\+: Press {\ttfamily $^\wedge$} + {\ttfamily ⌥} + {\ttfamily ⌘} + {\ttfamily B}
\item Create a new command\+:
\begin{DoxyEnumerate}
\item Press {\ttfamily ⌘} + {\ttfamily N}
\item Select “\+Command”
\item Press the button “\+Create”
\end{DoxyEnumerate}
\item Configure your new command
\begin{DoxyEnumerate}
\item Use “\+Reformat Document” or a similar text as “\+Name”
\item Enter {\ttfamily text.\+html.\+markdown} in the field “\+Scope Selector”
\item Use {\ttfamily $^\wedge$} + {\ttfamily ⇧} + {\ttfamily H} as “\+Key Equivalent”
\item Copy the text {\ttfamily callback.\+document.\+will-\/save} into the field “\+Semantic Class”
\item Select “\+Document” as “\+Input”
\item Select “\+Replace Input” in the dropdown menu for the option “\+Output”
\item Select “\+Line Interpolation” in the menu “\+Caret Placement”
\item Copy the following code into the text field\+:
\`{}\`{}\`{} \#!/bin/bash
if ! \char`\"{}\$\{\+T\+M\+\_\+\+P\+R\+E\+T\+T\+I\+E\+R\+:-\/prettier\}\char`\"{} --stdin --stdin-\/filepath \char`\"{}\$\{\+T\+M\+\_\+\+F\+I\+L\+E\+P\+A\+T\+H\}\char`\"{} then . \char`\"{}\$\+T\+M\+\_\+\+S\+U\+P\+P\+O\+R\+T\+\_\+\+P\+A\+T\+H/lib/bash\+\_\+init.\+sh\char`\"{} exit\+\_\+show\+\_\+tool\+\_\+tip fi \`{}\`{}\`{}
\item Save your new command\+: {\ttfamily ⌘} + {\ttfamily S}
\end{DoxyEnumerate}
\end{DoxyEnumerate}\hypertarget{doc_CODING_md_autotoc_md993}{}\doxysubsection{Shell Guidelines}\label{doc_CODING_md_autotoc_md993}
\begin{DoxyItemize}
\item Please only use \href{https://en.wikipedia.org/wiki/POSIX}{\texttt{ P\+O\+S\+IX}} functionality.
\end{DoxyItemize}\hypertarget{doc_CODING_md_autotoc_md994}{}\doxysubsubsection{shfmt}\label{doc_CODING_md_autotoc_md994}
We use \href{https://github.com/mvdan/sh}{\texttt{ {\ttfamily shfmt}}} to format Shell files in the repository.\hypertarget{doc_CODING_md_autotoc_md995}{}\doxyparagraph{Installation}\label{doc_CODING_md_autotoc_md995}
\doxysubparagraph*{mac\+OS}
You can install \href{https://github.com/mvdan/sh}{\texttt{ {\ttfamily shfmt}}} on mac\+OS using \href{https://brew.sh}{\texttt{ Homebrew}}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{brew install shfmt}
\end{DoxyCode}
\doxysubparagraph*{General}
\href{https://github.com/mvdan/sh/releases}{\texttt{ shfmt’s Git\+Hub 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\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{mkdir -\/p "\$HOME/bin" \&\& cd "\$HOME/bin" \&\& \(\backslash\)}
\DoxyCodeLine{ curl -\/L "https://github.com/mvdan/sh/releases/download/v2.6.4/shfmt\_v2.6.4\_linux\_amd64" -\/o shfmt \&\& \(\backslash\)}
\DoxyCodeLine{ chmod u+x shfmt}
\end{DoxyCode}
. Please note that you have to make sure, that your {\ttfamily P\+A\+TH} includes {\ttfamily \$\+H\+O\+ME/bin}, if you use the command above\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{export PATH=\$PATH:"\$HOME/bin"}
\end{DoxyCode}
\hypertarget{doc_CODING_md_autotoc_md996}{}\doxyparagraph{Usage}\label{doc_CODING_md_autotoc_md996}
We provide the script \`{}reformat-\/shell\`{} that formats the whole codebase with \href{https://github.com/mvdan/sh}{\texttt{ {\ttfamily shfmt}}}\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{scripts/dev/reformat-\/shell}
\end{DoxyCode}
. You can also reformat specific files by listing filenames after the script\+:
\`{}\`{}{\ttfamily scripts/dev/reformat-\/shell scripts/dev/reformat-\/shell \# Reformat the source of}reformat-\/shell\`{}
\begin{DoxyCode}{0}
\DoxyCodeLine{.}
\DoxyCodeLine{}
\DoxyCodeLine{\#\#\#\#\# Tool Integration}
\DoxyCodeLine{}
\DoxyCodeLine{The GitHub project page of [`shfmt`][] offers some options to integrate the tool into your development workflow [here](https://github.com/mvdan/sh\#related-\/projects).}
\DoxyCodeLine{}
\DoxyCodeLine{\#\#\#\#\#\# TextMate}
\DoxyCodeLine{}
\DoxyCodeLine{The steps below show you how to create a [TextMate][] command that formats a documents with [`shfmt`][] every time you save it.}
\DoxyCodeLine{}
\DoxyCodeLine{1. Open the “Bundle Editor”: Press \string^ + ⌥ + ⌘ + B}
\DoxyCodeLine{2. Create a new command:}
\DoxyCodeLine{ 1. Press ⌘ + N}
\DoxyCodeLine{ 2. Select “Command”}
\DoxyCodeLine{ 3. Press the button “Create”}
\DoxyCodeLine{3. Configure your new command}
\DoxyCodeLine{}
\DoxyCodeLine{ 1. Use “Reformat Document” or a similar text as “Name”}
\DoxyCodeLine{ 2. Enter `source.shell` in the field “Scope Selector”}
\DoxyCodeLine{ 3. Use \string^ + ⇧ + H as “Key Equivalent”}
\DoxyCodeLine{ 4. Copy the text `callback.document.will-\/save` into the field “Semantic Class”}
\DoxyCodeLine{ 5. Select “Document” as “Input”}
\DoxyCodeLine{ 6. Select “Replace Input” in the dropdown menu for the option “Output”}
\DoxyCodeLine{ 7. Select “Line Interpolation” in the menu “Caret Placement”}
\DoxyCodeLine{ 8. Copy the following code into the text field:}
\end{DoxyCode}
\begin{DoxyVerb} #!/bin/bash
if ! "${TM_SHFMT_FORMAT:-shfmt}" -s -sr; then
. "$TM_SUPPORT_PATH/lib/bash_init.sh"
exit_show_tool_tip
fi
```
\end{DoxyVerb}
\begin{DoxyEnumerate}
\item Save your new command\+: {\ttfamily ⌘} + {\ttfamily S}
\end{DoxyEnumerate}\hypertarget{doc_CODING_md_autotoc_md997}{}\doxysubsection{Doxygen Guidelines}\label{doc_CODING_md_autotoc_md997}
{\ttfamily doxygen} is used to document the A\+PI 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 \href{https://doc.libelektra.org/api/latest/html/}{\texttt{ A\+PI Doc}} online). Links between Markdown files will be converted with the \mbox{\hyperlink{doc_markdownlinkconverter_README_md}{Markdown Link Converter}}. {\bfseries{Markdown pages are used in the pdf, therefore watch which characters you use and provide a proper encoding!}}
\begin{DoxyItemize}
\item use {\ttfamily @} to start Doxygen tags
\item Do not duplicate information available in git in Doxygen comments.
\item Use {\ttfamily @copydoc}, {\ttfamily @copybrief} and {\ttfamily @copydetails} intensively (except for file headers).
\end{DoxyItemize}\hypertarget{doc_CODING_md_autotoc_md998}{}\doxysubsection{File Headers}\label{doc_CODING_md_autotoc_md998}
Files should start with\+:
\begin{DoxyCode}{0}
\DoxyCodeLine{}
\end{DoxyCode}
Note\+:
\begin{DoxyItemize}
\item {\ttfamily @} {\ttfamily file} has {\itshape no} parameters.
\item {\ttfamily @} {\ttfamily brief} should contain a short statement about the content of the file and is needed so that your file gets listed at \href{https://doc.libelektra.org/api/latest/html/files.html}{\texttt{ https\+://doc.\+libelektra.\+org/api/latest/html/files.\+html}}
\end{DoxyItemize}
The duplication of the filename, author and date is not needed, because this information is tracked using git and \mbox{\hyperlink{doc_AUTHORS_md}{doc/\+A\+U\+T\+H\+O\+RS.md}} already.\hypertarget{doc_CODING_md_autotoc_md999}{}\doxysection{Further Readings}\label{doc_CODING_md_autotoc_md999}
\begin{DoxyItemize}
\item Make sure to read \mbox{\hyperlink{doc_DESIGN_md}{D\+E\+S\+I\+GN}} together with this document.
\end{DoxyItemize}