1Guidelines for Developing and Contributing Code 2=============================================== 3 4Introduction 5------------ 6 7The EMB² team welcomes all kinds of feedback and contributions. Please don't hesitate to contact us if you have any questions, comments, bug reports, suggestions for improvement, extensions or the like (see [README.md](https://github.com/siemens/embb/blob/master/README.md) for general contact information). In the following, we give an overview the main development principles and sketch how to port EMB² to other platforms. Moreover, we describe our coding and documentation guidelines that should be adhered to when contributing code. 8 9Development 10----------- 11 12### Directory Structure 13 14EMB² consists of several components (modules) which are organized as follows: 15 16``` 17/ -- Repository root 18 CMakeLists.txt -- Main CMake buildfile, calls component CMake buildfiles 19 CMakeCommon/ -- Custom CMake functions 20 doc/ -- Documentation (tutorial, reference manual, examples) 21 scripts/ -- Scripts for packaging, running tests, ... 22 COMPONENT_A/ -- Component name (e.g., 'base_c' or 'mtapi_cpp') 23 CMakeLists.txt -- Buildfile for component, called from main buildfile 24 include/ -- Include directory of the component 25 embb/ -- Users shall only include files below this directory 26 COMPONENT_A/ -- Component name (without suffix '_c' or '_cpp') 27 C++ main headers -- To be included by users of the C++ API 28 internal/ -- Internal headers included from C++ main headers 29 c/ -- C headers (main and internal), optional for C++ components 30 src/ -- Source files (including non-public headers) 31 test/ -- Unit test sources 32 COMPONENT_B/ -- Other component 33 ... 34``` 35 36If you add a directory, e.g., for a new plugin, please don't forget to update all relevant `CMakeLists.txt` files as well as `doc/reference/Doxyfile.in` and `scripts/run_cpplint.sh`. 37 38### Branches 39 40There are two predefined branches in the Git repository: 41 42- `master`: This branch contains the latest stable version of EMB², i.e., the source code has been reviewed and all tests pass successfully. 43- `development`: Implementation takes place in this branch. In contrast to feature branches (see below), the source code in this branch has to be compilable. When new features are stable, the development branch is merged back into the master branch. 44 45In addition to these two branches, there may be arbitrarily many feature branches for implementing new functionality or fixing bugs. There are no requirements on the source code in these branches. After finishing the implementation, a feature branch is merged into the development branch (make sure that the source code is still compilable afterwards). 46 47### Contributing 48 49Please report bugs, feature requests, etc. via GitHub (https://github.com/siemens/embb/issues). Alternatively, e.g. in case of vulnerabilities, send an email to embb.info@gmail.com. Bug fixes, extensions, etc. can be contributed as pull requests via GitHub or as patches via mail. If possible, refer to a current snapshot of the master branch and create pull requests against the *development* branch. Moreover, please include regression tests or additional unit tests that check new functionality. When signing-off a contribution (using your real name), you declare the following: 50 51``` 52Developer's Certificate of Origin 1.1 53 54By making a contribution to this project, I certify that: 55 56(a) The contribution was created in whole or in part by me and I 57 have the right to submit it under the open source license 58 indicated in the file; or 59 60(b) The contribution is based upon previous work that, to the best 61 of my knowledge, is covered under an appropriate open source 62 license and I have the right under that license to submit that 63 work with modifications, whether created in whole or in part 64 by me, under the same open source license (unless I am 65 permitted to submit under a different license), as indicated 66 in the file; or 67 68(c) The contribution was provided directly to me by some other 69 person who certified (a), (b) or (c) and I have not modified 70 it. 71 72(d) I understand and agree that this project and the contribution 73 are public and that a record of the contribution (including all 74 personal information I submit with it, including my sign-off) is 75 maintained indefinitely and may be redistributed consistent with 76 this project or the open source license(s) involved. 77``` 78 79### Porting 80 81EMB² is easily portable to platforms unsupported so far. Almost all platform specific code is located in the `base_c` and `base_cpp` directories, and platform specific code is fenced using `EMBB_PLATFORM_*` defines. 82 83To distinguish between compilers, EMB² currently uses the following defines: 84 85- EMBB_PLATFORM_COMPILER_GNUC 86- EMBB_PLATFORM_COMPILER_MSVC 87- EMBB_PLATFORM_COMPILER_UNKNOWN 88 89Different architectures are distinguished using: 90 91- EMBB_PLATFORM_ARCH_C11 92- EMBB_PLATFORM_ARCH_CXX11 93- EMBB_PLATFORM_ARCH_X86 94- EMBB_PLATFORM_ARCH_X86_32 95- EMBB_PLATFORM_ARCH_X86_64 96- EMBB_PLATFORM_ARCH_ARM 97- EMBB_PLATFORM_ARCH_UNKNOWN 98 99Threading APIs are switched by: 100 101- EMBB_PLATFORM_THREADING_WINTHREADS 102- EMBB_PLATFORM_THREADING_POSIXTHREADS 103 104Please use these defines for new platform specific code. If additional defines are needed, they can be included in the `config.h` or `cmake_config.h.in` files. 105 106A list of macros to check the underlying platform, compiler versions, etc. can be found here: http://sourceforge.net/p/predef/wiki/Home/ 107 108Coding Guidelines 109----------------- 110 111### General 112 113- Restrict dynamic memory allocation to object construction time. A (bounded) 114queue, for example, shall only allocate memory in the constructor but not during 115operation, i.e., in the methods for pushing and popping elements. 116- Use assertions to catch bugs (always think what could theoretically happen). 117- Use exceptions to catch invalid user input (by the `EMBB_THROW` macro). 118- Use concepts instead of interfaces unless virtual functions are necessary. 119- Use `const` whenever it makes sense. 120- Use pointers only if they can be `NULL`, otherwise use const/non-const references. 121- Use `size_t` if the number of elements, indices, etc. depends on a pointer (`size_t` has the same size as a pointer). 122- For iterators, use `first` and `last` (as in STL), not `begin` and `end`. 123- Use the same order of functions etc. in the source files as in the corresponding header files. 124- Be aware of false sharing and align objects when appropriate. 125- Disable construction, copy construction, and assignment whenever it makes sense by declaring the corresponding functions private without giving a definition. 126- For headers, use `#include <...>` instead of `#include "..."`. 127- Include paths have the format `#include <embb/component_name/...>`, e.g., `#include <embb/base/internal/some_header.h>`. 128- In C code, use the prefix `embb_component_` for globally visible symbols. For example, the thread creation function is named `embb_base_ThreadCreate`. 129- Similarly, use the prefix `EMBB_COMPONENT_` for preprocessor macros. 130 131### Tool Support 132 133- All source files in the repository must have LF (Unix) line endings. Git can take care of this (using the following option, newly checked-in files and changes to them will automatically be converted from CRLF to LF if necessary): 134``` 135 git config --global core.autocrlf input 136``` 137- For the C++ parts of EMB², we follow [Google's C++ style guide](https://google.github.io/styleguide/cppguide.html) which can be checked using the [cpplint](https://raw.githubusercontent.com/google/styleguide/gh-pages/cpplint/cpplint.py) tool. However, we ignore some rules as they are not applicable or yield false results for this project. For example, we respect the include order of the Google style guide, but use <> instead of "" for project includes (see above). To check whether your code adheres to the style guide, use the `run_cpplint.sh` script containted in the `scripts` folder. You may use [clang-format](http://clang.llvm.org/docs/ClangFormat.html) with option `-style=Google` to pretty print your code but be aware that line breaking of Doxygen comments may not work properly. 138- Moreover, we regularly check the code using [Cppcheck](http://cppcheck.sourceforge.net/), a light-weight static analysis tool for C/C++. To run Cppcheck on all files in a certain directory, call it as follows: 139``` 140 cppcheck --enable=warning,style,performance,portability --inconclusive <directory> 141``` 142- We do not accept compiler warnings with a few exceptions when using MSVC (see below). By default, warnings are enabled using `-Wall -Wextra` (GCC) or `/Wall` (MSVC). To make sure that no warnings are overlooked, you can treat warnings as errors by setting `WARNINGS_ARE_ERRORS` to `ON`, for example: 143``` 144 cmake -g "Unix Makefiles" .. -DWARNINGS_ARE_ERRORS=ON 145``` 146- Use the following scheme to disable inappropriate MSVC warnings: 147```c++ 148#ifdef EMBB_COMPILER_MSVC 149// Suppress <brief description> warning 150#pragma warning(push) 151#pragma warning(disable : 4265) // 4265 is an example warning number 152#endif 153// Code that produces the warning (should consist of only very few lines) 154#ifdef EMBB_COMPILER_MSVC 155#pragma warning(pop) // Reset warning 4265 156#endif 157``` 158 159Documentation Guidelines 160------------------------ 161 162### General 163 164The source code is documented using [Doxygen](http::www.doxygen.org/). Please adhere to the following rules: 165 166- Document at least all entities visible to the user (API). 167- Member variables need only be documented if their names are not self-explanatory. 168- Check whether Doxygen emits any warnings or errors (e.g., undocumented functions). 169- Enable spell checking in your IDE and proofread the documentation generated by Doxygen. 170- Use full stops at the end of complete sentences (and only there). 171- The first sentence ending with a full stop is parsed as brief description by Doxygen. 172- Use `\` instead of `@` for Doxygen commands. 173- Typeset code fragments including constants such 'true' and 'false' in typewriter font using `\c` (example: `returns \c true if ...`). 174- Use `<tt>...</tt>` instead of `\c` for complex expressions that include, for example, braces (otherwise, the code might not be formatted correctly). 175- Use `@code` for multiple lines of code (examples etc.). 176- Document parameters in place (after the parameter) using `/**< [in,out,in/out] ... documentation ... */` 177- Refer to functions by adding braces after the name (example: `Fun()` but not just `Fun`). 178- Explicit or implicit dynamic memory allocation must be documented using the `\memory` command (see below). 179 180### Special Commands 181 182Use special commands to specify properties important in embedded systems: 183 184- `\memory`: Use if and only if a function/method dynamically allocates memory. Give a short comment and optionally specify the asymptotic memory consumption. 185- `\notthreadsafe`, `\threadsafe`, `\lockfree`, `\waitfree`: Always use one (!) of these commands to specify the behaviour related to concurrent execution. Note that `\lockfree` includes `\threadsafe` and `\waitfree` includes `\lockfree`. 186- `\threadsafe` means that a shared state (e.g., the member variables of an object, but also pointers/references passed as arguments to a function) is accessed in a synchronized way. This implies that a C function that gets `const` pointers as arguments is not thread-safe if there are other functions that can modify the arguments concurrently. Similarly, if a method doesn't modify the state of an object, but other methods are able to do so, the method is not thread-safe. 187- `\lockfree` means that at least one thread is always guaranteed to make progress, and `\waitfree` means that all threads are guaranteed to always make progress. A more detailed classification can be found in "M. Herlihy and N. Shavit. *On the nature of progress*. Principles of Distributed Systems (OPODIS'11), Springer-Verlag, 2011". 188 189### Structure 190 191The following sequence of descriptions and commands shall be obeyed to achieve a consistent layout of the documentation: 192 1931. Brief description ending with a full stop (without `\brief`) 1942. More detailed description [optional] 1953. `\pre`: Preconditions that must hold when calling the function [optional] 1964. `\post`: Postconditions that holld after calling the function [optional] 1975. `\return`: Description of return value [optional] 1986. `\throws`: Thrown exceptions (repeat for each exception) [optional] 1997. `\memory`: Dynamic memory allocation (see above) [optional] 2008. `\notthreadsafe`, `\threadsafe`, `\lockfree`, `\waitfree`: Thread safety and progress guarantees (see above) 2019. `\note`: Additional notes/comments [optional] 20210. `\see`: Links to other related functions, types, etc. [optional] 20311. `\tparam`: Template parameters [optional] 204 205### Example 206 207The example shown below demonstrates how to document a class according to the given rules: 208 209```c++ 210/** 211 * Concurrent queue. 212 * \tparam Type Type of the queue elements 213 */ 214template<typename Type> 215class Queue { 216 public: 217 /** 218 * Creates a queue with the specified capacity. 219 * \memory Allocates \c capacity elements of type \c Type. 220 * \notthreadsafe 221 */ 222 Queue( 223 size_t capacity 224 /**< [IN] Capacity of the queue */ 225 ); 226 227 /** 228 * Returns the capacity of the queue. 229 * \return Number of elements the queue can hold 230 * \waitfree 231 */ 232 size_t GetCapacity(); 233 234 /** 235 * Tries to enqueue an element. 236 * \return \c true if the element could be enqueued, otherwise \c false 237 * \threadsafe 238 */ 239 bool TryEnqueue( 240 Type const & element 241 /**< [IN] Const reference to the element that shall be enqueued */ 242 ); 243}; 244``` 245