diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f89bf3b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,214 @@ +Guidelines for Developing and Contributing Code +=============================================== + +Introduction +------------ + +The 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. + +Development +----------- + +### Directory Structure + +EMB² consists of several components (modules) which are organized as follows: + +``` +/ -- Repository root + CMakeLists.txt -- Main CMake buildfile, calls component CMake buildfiles + CMakeCommon/ -- Custom CMake functions + doc/ -- Documentation (tutorial, reference manual, examples) + scripts/ -- Scripts for packaging, running tests, ... + COMPONENT_A/ -- Component name (e.g., 'base_c' or 'mtapi_cpp') + CMakeLists.txt -- Buildfile for component, called from main buildfile + include/ -- Include directory of the component + embb/ -- Users shall only include files below this directory + COMPONENT_A/ -- Component name (without suffix '_c' or '_cpp') + C++ main headers -- To be included by users of the C++ API + internal/ -- Internal headers included from C++ main headers + c/ -- C headers (main and internal), optional for C++ components + src/ -- Source files (including non-public headers) + test/ -- Unit test sources + COMPONENT_B/ -- Other component + ... +``` + +If 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`. + +### Branches + +There are two predefined branches in the Git repository: + +- `master`: This branch contains the latest stable version of EMB², i.e., the source code has been reviewed and all tests pass successfully. +- `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. + +In 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). + +### Contributing + +Bug fixes, extensions, etc. can be contributed as pull requests via GitHub (preferred way to involve the community) or as patches via mail (mailto:embb.info@gmail.com). If possible, refer to a current snapshot of the master branch. + +### Porting + +EMB² 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. + +To distinguish between compilers, EMB² currently uses the following defines: + +- EMBB_PLATFORM_COMPILER_GNUC +- EMBB_PLATFORM_COMPILER_MSVC +- EMBB_PLATFORM_COMPILER_UNKNOWN + +Different architectures are distinguished using: + +- EMBB_PLATFORM_ARCH_X86 +- EMBB_PLATFORM_ARCH_X86_32 +- EMBB_PLATFORM_ARCH_X86_64 +- EMBB_PLATFORM_ARCH_ARM +- EMBB_PLATFORM_ARCH_UNKNOWN + +Threading APIs are switched by: + +- EMBB_PLATFORM_THREADING_WINTHREADS +- EMBB_PLATFORM_THREADING_POSIXTHREADS + +Please 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. + +A list of macros to check the underlying platform, compiler versions, etc. can be found here: http://sourceforge.net/p/predef/wiki/Home/ + +Coding Guidelines +----------------- + +### General + +- Restrict dynamic memory allocation to object construction time. A (bounded) +queue, for example, shall only allocate memory in the constructor but not during +operation, i.e., in the methods for pushing and popping elements. +- Use assertions to catch bugs (always think what could theoretically happen). +- Use exceptions to catch invalid user input (by the `EMBB_THROW` macro). +- Use concepts instead of interfaces unless virtual functions are necessary. +- Use `const` whenever it makes sense. +- Use pointers only if they can be `NULL`, otherwise use const/non-const references. +- Use `size_t` if the number of elements, indices, etc. depends on a pointer (`size_t` has the same size as a pointer). +- For iterators, use `first` and `last` (as in STL), not `begin` and `end`. +- Use the same order of functions etc. in the source files as in the corresponding header files. +- Be aware of false sharing and align objects when appropriate. +- Disable construction, copy construction, and assignment whenever it makes sense by declaring the corresponding functions private without giving a definition. +- For headers, use `#include <...>` instead of `#include "..."`. +- Include paths have the format `#include `, e.g., `#include `. +- In C code, use the prefix `embb_component_` for globally visible symbols. For example, the thread creation function is named `embb_base_ThreadCreate`. +- Similarly, use the prefix `EMBB_COMPONENT_` for preprocessor macros. + +### Tool Support + +- 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): +``` + git config --global core.autocrlf input +``` +- 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. +- 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: +``` + cppcheck --enable=warning,style,performance,portability --inconclusive +``` +- 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: +``` + cmake -g "Unix Makefiles" .. -DWARNINGS_ARE_ERRORS=ON +``` +- Use the following scheme to disable inappropriate MSVC warnings: +```c++ +#ifdef EMBB_COMPILER_MSVC +// Suppress warning +#pragma warning(push) +#pragma warning(disable : 4265) // 4265 is an example warning number +#endif +// Code that produces the warning (should consist of only very few lines) +#ifdef EMBB_COMPILER_MSVC +#pragma warning(pop) // Reset warning 4265 +#endif +``` + +Documentation Guidelines +------------------------ + +### General + +The source code is documented using [Doxygen](http::www.doxygen.org/). Please adhere to the following rules: + +- Document at least all entities visible to the user (API). +- Member variables need only be documented if their names are not self-explanatory. +- Check whether Doxygen emits any warnings or errors (e.g., undocumented functions). +- Enable spell checking in your IDE and proofread the documentation generated by Doxygen. +- Use full stops at the end of complete sentences (and only there). +- The first sentence ending with a full stop is parsed as brief description by Doxygen. +- Use `\` instead of `@` for Doxygen commands. +- Typeset code fragments including constants such 'true' and 'false' in typewriter font using `\c` (example: `returns \c true if ...`). +- Use `...` instead of `\c` for complex expressions that include, for example, braces (otherwise, the code might not be formatted correctly). +- Use `@code` for multiple lines of code (examples etc.). +- Document parameters in place (after the parameter) using `/**< [in,out,in/out] ... documentation ... */` +- Refer to functions by adding braces after the name (example: `Fun()` but not just `Fun`). +- Explicit or implicit dynamic memory allocation must be documented using the `\memory` command (see below). + +### Special Commands + +Use special commands to specify properties important in embedded systems: + +- `\memory`: Use if and only if a function/method dynamically allocates memory. Give a short comment and optionally specify the asymptotic memory consumption. +- `\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`. +- `\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. +- `\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". + +### Structure + +The following sequence of descriptions and commands shall be obeyed to achieve a consistent layout of the documentation: + +1. Brief description ending with a full stop (without `\brief`) +2. More detailed description [optional] +3. `\pre`: Preconditions that must hold when calling the function [optional] +4. `\post`: Postconditions that holld after calling the function [optional] +5. `\return`: Description of return value [optional] +6. `\throws`: Thrown exceptions (repeat for each exception) [optional] +7. `\memory`: Dynamic memory allocation (see above) [optional] +8. `\notthreadsafe`, `\threadsafe`, `\lockfree`, `\waitfree`: Thread safety and progress guarantees (see above) +9. `\note`: Additional notes/comments [optional] +10. `\see`: Links to other related functions, types, etc. [optional] +11. `\tparam`: Template parameters [optional] + +### Example + +The example shown below demonstrates how to document a class according to the given rules: + +```c++ +/** + * Concurrent queue. + * \tparam Type Type of the queue elements + */ +template +class Queue { + public: + /** + * Creates a queue with the specified capacity. + * \memory Allocates \c capacity elements of type \c Type. + * \notthreadsafe + */ + Queue( + size_t capacity + /**< [IN] Capacity of the queue */ + ); + + /** + * Returns the capacity of the queue. + * \return Number of elements the queue can hold + * \waitfree + */ + size_t GetCapacity(); + + /** + * Tries to enqueue an element. + * \return \c true if the element could be enqueued, otherwise \c false + * \threadsafe + */ + bool TryEnqueue( + Type const & element + /**< [IN] Const reference to the element that shall be enqueued */ + ); +}; +``` diff --git a/README.md b/README.md index 0d13ae0..287fe83 100644 --- a/README.md +++ b/README.md @@ -1,211 +1,134 @@ Embedded Multicore Building Blocks (EMB²) ========================================= +Introduction +------------ + +### Overview + +The Embedded Multicore Building Blocks (EMB²) are an easy to use yet powerful and efficient C/C++ library for the development of parallel applications. EMB² has been specifically designed for embedded systems and the typical requirements that accompany them, such as real-time capability and constraints on memory consumption. As a major advantage, low-level operations are hidden in the library which relieves software developers from the burden of thread management and synchronization. This not only improves productivity of parallel software development, but also results in increased reliability and performance of the applications. -Overview --------- - -The Embedded Multicore Building Blocks (EMB²) are an easy to use yet powerful -and efficient C/C++ library for the development of parallel applications. EMB² -has been specifically designed for embedded systems and the typical -requirements that accompany them, such as real-time capability and constraints -on memory consumption. As a major advantage, low-level operations are hidden -in the library which relieves software developers from the burden of thread -management and synchronization. This not only improves productivity of -parallel software development, but also results in increased reliability and -performance of the applications. - -EMB² is independent of the hardware architecture (x86, ARM, ...) and runs on -various platforms, from small devices to large systems containing numerous -processor cores. It builds on MTAPI, a standardized programming interface for -leveraging task parallelism in embedded systems containing symmetric or -asymmetric multicore processors. A core feature of MTAPI is low-overhead -scheduling of fine-grained tasks among the available cores during runtime. -Unlike existing libraries, EMB² supports task priorities and affinities, which -allows the creation of soft real-time systems. Additionally, the scheduling -strategy can be optimized for non-functional requirements such as minimal -latency and fairness. - -Besides the task scheduler, EMB² provides basic parallel algorithms, concurrent -data structures, and skeletons for implementing stream processing applications -(see figure below). These building blocks are largely implemented in a -non-blocking fashion, thus preventing frequently encountered pitfalls like -lock contention, deadlocks, and priority inversion. As another advantage in -real-time systems, the algorithms and data structures give certain progress -guarantees. For example, wait-free data structures guarantee system-wide -progress which means that every operation completes within a finite number of -steps independently of any other concurrent operations on the same data -structure. +EMB² is independent of the hardware architecture (x86, ARM, ...) and runs on various platforms, from small devices to large systems containing numerous processor cores. It builds on MTAPI, a standardized programming interface for leveraging task parallelism in embedded systems containing symmetric or asymmetric (heterogeneous) multicore processors. A core feature of MTAPI is low-overhead scheduling of fine-grained tasks among the available cores during runtime. Unlike existing libraries, EMB² supports task priorities and affinities, which allows the creation of soft real-time systems. Additionally, the scheduling strategy can be optimized for non-functional requirements such as minimal latency and fairness. + +Besides the task scheduler, EMB² provides basic parallel algorithms, concurrent data structures, and skeletons for implementing stream processing applications (see figure below). These building blocks are largely implemented in a non-blocking fashion, thus preventing frequently encountered pitfalls like lock contention, deadlocks, and priority inversion. As another advantage in real-time systems, the algorithms and data structures give certain progress guarantees. For example, wait-free data structures guarantee system-wide progress which means that every operation completes within a finite number of steps independently of any other concurrent operations on the same data structure. Building blocks of EMB² -Community and Contact ---------------------- +### Community and Contact -Project home: +GitHub: - https://github.com/siemens/embb -Git: +Repository: - https://github.com/siemens/embb.git (HTTP) - git@github.com:siemens/embb.git (SSH) -Mailing lists: - - embb-announcements@googlegroups.com (announcements) - - embb-dev@googlegroups.com (development) - -Subscription: - - https://groups.google.com/forum/#!forum/embb-announcements/join - - https://groups.google.com/forum/#!forum/embb-dev/join +Mailing list: + - embb-announcements@googlegroups.com (announcements)
+ https://groups.google.com/forum/#!forum/embb-announcements/join Contact: - - embb.info@gmail.com or - - tobias.schuele@siemens.com, sebnem.rusitschka@siemens.com + - embb.info@gmail.com +### License -License -------- +See the file [COPYING.md](https://github.com/siemens/embb/blob/master/COPYING.md) in the project's root directory. -See the file "COPYING.md" in the project's root directory. +### Contributions +See the file [CONTRIBUTING.md](https://github.com/siemens/embb/blob/master/CONTRIBUTING.md) in the project's root directory. -Requirements ------------- +Build and Installation +---------------------- -This project is based on the standards C99 (for C code) and C++03 (for C++ -code) to be usable on a wide range of target systems. It has been tested on -the following OS/compiler/architecture combinations: - - - Linux (Ubuntu 12.04) / GCC 4.8.1 / x86, x86_64 - - Linux (Ubuntu 12.04) / Clang 3.0.0 / x86_64 - - Linux (Ubuntu 14.04) / GCC 4.8.2 / ARMv7 - - Windows - * MSVC 12.0.21005.1 REL / x86, x86_64 - * MSVC 11.0.50727.42 VSLRSTAGE / x86, x86_64 - -Other compilers and operating systems may be supported without any changes to -the source code. The project includes unit tests that can be used to find out -whether a system not officially supported is suitable to run EMB². If there is -a requirement to support a system on which the unit tests do not pass, please -contact us: embb-dev@googlegroups.com. - - -Directory Structure -------------------- - -EMB² consists of various building blocks. For some of them, there exist C and -C++ versions, others are only implemented in C++. The directory names are -postfixed with either "_cpp" or "_c" for the C++ and C versions, respectively. -Currently, EMB² contains the following components: - - - base: base_c, base_cpp - - mtapi: mtapi_c, mtapi_cpp and - mtapi_plugins_c (mtapi_network_c and mtapi_opencl_c) - - algorithms: algorithms_cpp - - dataflow: dataflow_cpp - - containers: containers_cpp - -Each component consists of an include, a src, and a test subfolder that contain -the header files, source files, and unit tests, respectively. - -Component base_c contains abstractions for threading, synchronization, atomic -operations, and other functionalities. As the name indicates, the code is -implemented in C. Component base_cpp is mainly a C++ wrapper around the base_c -functions. Component mtapi_c is a task scheduler written in C and mtapi_cpp a -C++ wrapper for the scheduler (mtapi_network_c and mtapi_opencl_c are scheduler -plugins for distributed and OpenCL-based heterogeneous systems, respectively). -Component algorithms_cpp provides high-level constructs for typical -parallelization tasks in C++, and dataflow_cpp generic skeletons for the -development of parallel stream-based applications. Finally, containers_cpp -provides data structures for storing objects in a thread-safe way. +### General +It is strongly recommended to build from a release file and not from a repository snapshot in order to get the documentation and the examples out-of-the box. The release files can be found at https://github.com/siemens/embb/releases. -Build and Installation ----------------------- +### Platforms -Note: It is recommended to build from a release file and not from a repository -snapshot in order to get the documentation and the examples out-of-the box. -The release files can be found at https://github.com/siemens/embb/releases. +EMB² is regularly built and tested on a variety of OS/compiler/architecture combinations including Linux (x86 and ARM using GCC/Clang) and Windows (x86 using MSVC). Other platforms may be supported without any changes to the source code. The included unit tests can be used to find out whether a system not officially supported is suitable to run EMB². If the build process or the unit tests fail on your system, please contact us. -EMB² is built using CMake (version 2.8.9 or higher). CMake is a build file -generator which allows to abstract from the concrete build tools. To generate -and invoke the platform-specific build files, open a shell (on Windows, use -the Visual Studio developer shell to have the correct environment variables) -and change to the project's root directory. Create a subdirectory, where you -want to build the library, e.g., "build". Change to that subdirectory. It is -assumed that the project's root directory is now the parent directory. +### Prerequisites -### 1. Generation of native build files +The project is based on the standards C99 (for C code) and C++03 (for C++ code) to be usable on a wide range of target systems. Besides a C/C++ compiler supporting these standards, [CMake](https://cmake.org/) 2.8.9 or higher is required to build EMB². is a build file generator which abstracts from the concrete build tools. -Choose an appropriate build file generator for your system. +### Quick Installation on Linux - - For Linux, GCC/Clang, x86/x86_64/ARM: "Unix Makefiles" - - For Windows, MSVC of VS 2013, x86: "Visual Studio 12" - - For Windows, MSVC of VS 2013, x86_64: "Visual Studio 12 Win64" - - For Windows, MSVC of VS 2012, x86: "Visual Studio 11" - - For Windows, MSVC of VS 2012, x86_64: "Visual Studio 11 Win64" +To generate and invoke the platform-specific build files, open a shell and change to the project's root directory. Create a subdirectory, where you want to build the library, e.g., "build", and change to that subdirectory. In the following, it is assumed that the project's root directory is the parent directory. Now you can generate the build files using CMake: -A list of all available generators can be displayed by typing "cmake" without -any options. The build files can be generated using the following command: + cmake .. - cmake -G .. [OPTIONS] +As the next step, compile EMB²: -Note that on Linux, the architecture (32/64 bit) cannot be selected by the -generator. However, the build mode (Release/Debug) can be specified using the -option -DCMAKE_BUILD_TYPE=[Release|Debug]. If no build mode is given on Linux, -the default (Release) is used. The Visual Studio generators create build files -for both modes (the selection is done at build time). + cmake --build . -You may choose a custom compiler instead the default one by defining -CMAKE_CXX_COMPILER and/or CMAKE_C_COMPILER. For example, to use Clang on Linux -use: +After compilation has finished, execute the tests: - cmake .. -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang + binaries/run_tests.sh -In the same way you may cross compile to another platform. For example, to cross -compile to ARM Linux using GCC, you need to specify the cross compiler itself and -the target architecture as an argument to the compiler: +Finally, install EMB² (the default path is `/usr/local`): - cmake .. -DCMAKE_CXX_COMPILER=arm-linux-gnueabi-gcc++ - -DCMAKE_CXX_FLAGS=-march=armv7-a - -DCMAKE_C_COMPILER=arm-linux-gnueabi-gcc - -DCMAKE_C_FLAGS=-march=armv7-a + sudo cmake --build . --target install + +### Quick Installation on Windows -EMB² can be built with and without C++ exception handling, which has to be -specified on build file generation. When exceptions are turned off, an error -message is emitted and the program aborts in case of an exception within EMB². -To disable exceptions, add the option -DUSE_EXCEPTIONS=OFF. +To generate and invoke the platform-specific build files, open a Developer Command Prompt for Visual Studio and change to the project's root directory. Create a subdirectory, where you want to build the library, e.g., "build", and change to that subdirectory. In the following, it is assumed that the project's root directory is the parent directory. Now you can generate the build files using CMake (a list of supported CMake generators can be displayed by typing `cmake --help`). For example: -Similarly, automatic initialization of the task scheduler by the MTAPI C++ -interface can be disabled with -DUSE_AUTOMATIC_INITIALIZATION=OFF. This way, -unexpected delays after startup can be avoided, e.g. for timing measurements. + cmake -G "Visual Studio 14 2015" .. -The tutorial of EMB² comes with example source files in doc/examples/. These -can be built with the other source files using CMake option -DBUILD_EXAMPLES=ON -in the generation step. Note, however, that the examples use C++11 features and -require a corresponding compiler. +As the next step, compile EMB²: -Now you can generate the build files as shown by the following examples. + cmake --build . --config Release -For a Linux Debug build with exception handling, type +After compilation has finished, execute the tests: - cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Debug + binaries\run_tests.bat -For a default Linux build without automatic MTAPI C++ initialization, type +Finally, install EMB² with *administrator privileges*: + + cmake --build . --target install --config Release + +### Detailed Installation Instructions + +EMB² provides several options which allow you to configure it to your needs. This section explains these options and describes the build process in more detail. + +#### 1. Generation of Native Build Files + +As mentioned above, it is recommended to build EMB² in a subdirectory such as "build". The actual build files are generated by the following command (a list of available generators can be displayed by typing `cmake --help`): + + cmake -G .. [OPTIONS] + +Note that on Linux, the architecture (32/64 bit) cannot be selected by the generator. The default is "Unix Makefiles" for which reason `-G ` may be omitted. + +EMB² can be built in Release or Debug mode. The latter contains additional checks during runtime and is only recommended for development purposes. On Linux, the build mode can be specified using the option `-DCMAKE_BUILD_TYPE=[Release|Debug]`, for example: + + cmake .. -DCMAKE_BUILD_TYPE=Debug + +If no build mode is given, the default (Release) is used. The Visual Studio generators create build files for both modes (the selection is done at build time as described below). + +You may choose a custom compiler instead the default one by defining `CMAKE_CXX_COMPILER` and/or `CMAKE_C_COMPILER`. For example, to use Clang on Linux, type: + + cmake .. -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang + +In the same way, you may cross compile to another platform. For example, to cross compile to ARM v7 using GCC, you need to specify the cross compiler itself and the target architecture as an argument to the compiler: + + cmake .. -DCMAKE_CXX_COMPILER=arm-linux-gnueabi-gcc++ \ + -DCMAKE_CXX_FLAGS=-march=armv7-a \ + -DCMAKE_C_COMPILER=arm-linux-gnueabi-gcc \ + -DCMAKE_C_FLAGS=-march=armv7-a - cmake .. -DUSE_AUTOMATIC_INITIALIZATION=OFF +EMB² can be built with C++ exception handling (default) or without exceptions. When exceptions are turned off, a message is emitted in case of an error and the program aborts. To disable exceptions, add the option `-DUSE_EXCEPTIONS=OFF`. -For a Windows build (VS 2013, x86) without exception handling, type +Similarly, automatic initialization of the task scheduler by the MTAPI C++ interface can be disabled with `-DUSE_AUTOMATIC_INITIALIZATION=OFF`. This way, unexpected delays after startup can be avoided, e.g. for timing measurements. - cmake -G "Visual Studio 12" .. -DUSE_EXCEPTIONS=OFF +The tutorial of EMB² comes with a number of examples in `doc/examples/`. These can be built with the other source files using the option `-DBUILD_EXAMPLES=ON`. Note, however, that the examples use C++11 features and require an appropriate compiler. -Note that "Visual Studio 12" refers to the version number of Visual Studio and -not to the year in which it was released (2013). +By default, the included unit tests are built as part of the installation process. To override the default behavior, add the option `-DBUILD_TESTS=OFF`. -### 2. Compiling and linking +#### 2. Compiling and Linking -As the next step, you can compile the library using the generated build files. -On Linux, the build mode (Release|Debug) is already given in the build files, -whereas on Windows, it has to be specified now. +As the next step, you can compile the library using the generated build files. On Linux, the build mode (Release|Debug) is already given in the build files, whereas on Windows, it has to be specified now. For a Linux build, type @@ -215,10 +138,15 @@ For a Windows Release build, type cmake --build . --config Release -### 3. Running the tests +If you are a developer working on a repository snapshot of EMB², you can build the documentation as follows (provided that you have [Doxygen](http://www.doxygen.org/) installed): -To check whether EMB² was compiled correctly, run the tests. The test -executables are contained in the subfolder "binaries". + cmake --build . --target doxygen + +Note that this is *not* necessary if you build from a release file. + +#### 3. Running the Tests + +To check whether EMB² was compiled correctly, run the tests. The test executables are contained in the subfolder "binaries". On Linux, type @@ -228,9 +156,9 @@ On Windows, type binaries\run_tests.bat -If no error message occurs, EMB² is working fine. +If no error message occurs, EMB² works fine. -### 4. Installation +#### 4. Installation The default installation path on Linux is @@ -238,7 +166,11 @@ The default installation path on Linux is and on Windows - C:\Program Files\embb-X.Y.Z\ or C:\Program Files (x86)\embb-X.Y.Z + C:\Program Files\embb-X.Y.Z\ + +or + + C:\Program Files (x86)\embb-X.Y.Z depending on the target architecture. @@ -246,146 +178,60 @@ If you want a different installation path, you can change it now by typing cmake -DINSTALL_PREFIX=YourCustomPath .. -The option "-DINSTALL_PREFIX=YourCustomPath" can also be given in Step 1. - To install the files, use the command cmake --build . --target install -which copies the contents of the "install" folder to the "bin", "lib", and -"include" folders in the installation path. For the default paths, the -installation has to be run with administrator / root privileges. - +which copies the contents of the "install" folder to the "bin", "lib", and "include" folders in the installation path. For the default paths, the installation has to be run with administrator / root privileges. Using the Library ----------------- -To use EMB², the include files have to be made available during compilation of -your application and the libraries have to be added during linking. +### Components + +For some of the components, there exist C and C++ versions, wheras others are only implemented in C++. The directory names are postfixed with either "_cpp" or "_c" for the C++ and C versions, respectively. Currently, EMB² is composed of the following components: + + - Base library: base_c, base_cpp + - MTAPI: mtapi_c, mtapi_cpp, and mtapi_plugins_c (mtapi_network_c, mtapi_opencl_c, mtapi_cuda_c) + - Algorithms: algorithms_cpp + - Dataflow: dataflow_cpp + - Containers: containers_cpp -### 1. Using C++ +Directory "base_c" contains abstractions for threading, synchronization, atomic operations, and other functionalities. As the name indicates, the code is implemented in C. Directory "base_cpp" contains C++ wrappers around the "base_c" functions. Similarly, the MTAPI task scheduler is available for programs written in C ("mtapi_c") or C++ ("mtapi_cpp"). Heterogeneous and distributed systems are supported via the plugins contained in "mtapi_plugins_c". Directory "algorithms_cpp" provides high-level constructs for typical parallelization tasks in C++, and "dataflow_cpp" generic skeletons for the development of parallel stream-based applications. Finally, "containers_cpp" provides data structures for storing objects in a thread-safe way. -If you want to use the C++ functionalities of EMB², you have to link the -following libraries (names will be different on Windows and on Linux) in the -given order: +### Using C++ - embb_dataflow_cpp, embb_algorithms_cpp, embb_containers_cpp, - embb_mtapi_cpp, embb_mtapi_c, embb_base_cpp, embb_base_c +If you want to use the C++ functionalities of EMB², you have to link the following libraries (names will be slightly different on Windows and on Linux) in the given order: + + embb_dataflow_cpp, embb_algorithms_cpp, embb_containers_cpp, embb_mtapi_cpp, embb_mtapi_c, embb_base_cpp, embb_base_c The C++ header files can be included as follows: - #include #include + #include #include + #include #include -### 2. Using C +### Using C -The following libraries have to be linked in the given order: +If you only want to use the C versions of MTAPI and the base library, link them in the following order: embb_mtapi_c, embb_base_c The C header files can be included as follows: - #include or #include #include + #include +Alternatively, you can include MTAPI by `#include`. -Documentation -------------- - -The release files of EMB² come with a tutorial, example programs, and a -reference manual (HTML) describing the APIs. All documentation is contained in -the "doc" folder. The root document of the HTML reference is -"doc/reference/index.html". Note that generated documentation files are not -under version control and hence not contained in the repository. As mentioned -above, it is therefore recommended to download one of the packaged release -files in order to have ready-to-use documentation. - - -Code Quality ------------- - -For the C++ parts of EMB², we respect most rules of the "Google C++ Style -Guide" which are checked using the cpplint 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, which confuses the cpplint tool. -Moreover, we do not tolerate compiler warnings and regularly check the source -code using Cppcheck, a static analysis tool for C++. - - -Known Bugs and Limitations --------------------------- - -- For memory management reasons, the number of threads EMB² can deal with - is bounded by a predefined but modifiable constant (see functions - embb_thread_get_max_count() / embb_thread_set_max_count() and class - embb::base::Thread). -- While MTAPI fully supports heterogeneous systems, the algorithms and - dataflow components are currently limited to homogeneous systems. - - -Development and Contribution ----------------------------- - -The EMB² team welcomes all kinds of contributions, preferably as pull requests -or patches via the development mailing lists (see above). If possible, please -refer to a current snapshot of the development branch. - -EMB² is supposed to be easily portable to platforms unsupported so far. Almost -all platform specific code is located in the base_c and base_cpp modules. All -existing platform specific code is fenced by EMBB_PLATFORM_* defines. - -To distinguish between compilers, EMB² currently uses the following defines: - - - EMBB_PLATFORM_COMPILER_GNUC - - EMBB_PLATFORM_COMPILER_MSVC - - EMBB_PLATFORM_COMPILER_UNKNOWN - -Different architectures are distinguished using: - - - EMBB_PLATFORM_ARCH_X86 - - EMBB_PLATFORM_ARCH_X86_32 - - EMBB_PLATFORM_ARCH_X86_64 - - EMBB_PLATFORM_ARCH_ARM - - EMBB_PLATFORM_ARCH_UNKNOWN - -Threading APIs are switched by: - - - EMBB_PLATFORM_THREADING_WINTHREADS - - EMBB_PLATFORM_THREADING_POSIXTHREADS - -Please use these defines for new platform specific code. If additional defines -are needed, they can be defined in the config.h or cmake_config.h.in files. - - -Important Notes ---------------- - -- The MTAPI C++ interface supports automatic initialization, which allows for - easy usage of the MTAPI C++, Algorithms, and Dataflow components. For - performance measurements, explicit initialization is strongly recommended - since the measurements will otherwise include the initialization time of - MTAPI. -- When using ThreadSanitizer there is a bug that causes the built-in CMake type - size determination to fail which in turn leads to a broken configuration. - Therefore, you have to do a normal build first and then rerun CMake with - flags and libs configured for ThreadSanitizer. +### Documentation +The release files of EMB² come with a tutorial, example programs, and a reference manual (HTML) describing the APIs. All documentation is contained in the "doc" folder. The root document of the HTML reference is `doc/reference/index.html`. Note that the generated documentation files are not under version control and hence not contained in the repository. As mentioned above, it is therefore recommended to download one of the packaged release files in order to have ready-to-use documentation. -Links ------ +### Limitations and Important Notes - - Multicore Association: - http://www.multicore-association.org - - MTAPI: - http://www.multicore-association.org/workgroup/mtapi.php - - CMake: - http://www.cmake.org/ - - Google C++ Style Guide: - http://google-styleguide.googlecode.com/svn/trunk/cppguide.html - - cpplint: - http://google-styleguide.googlecode.com/svn/trunk/cpplint/ - - Cppcheck: - http://cppcheck.sourceforge.net/ +- For memory management reasons, the number of threads EMB² can deal with is bounded by a predefined but modifiable constant (see functions `embb_thread_get_max_count()` / `embb_thread_set_max_count()` and class `embb::base::Thread`). +- The MTAPI C++ interface supports automatic initialization, which allows for easy usage of the MTAPI C++, Algorithms, and Dataflow components. For performance measurements, explicit initialization is strongly recommended since the measurements will otherwise include the initialization time of MTAPI. +- When using ThreadSanitizer, a bug causes the built-in CMake type size determination to fail which in turn leads to a broken configuration. Therefore, you have to do a normal build first and then run CMake again with flags and libs configured for ThreadSanitizer.