From bacef33e78ea930826406c2b18c4fe16e8458c13 Mon Sep 17 00:00:00 2001 From: Tobias Schuele Date: Sun, 3 Jul 2016 21:52:58 +0200 Subject: [PATCH] Revised README.md and CONTRIBUTING.md --- CONTRIBUTING.md | 34 ++++++++-------------------------- README.md | 83 +++++++++++++++++++---------------------------------------------------------------- 2 files changed, 27 insertions(+), 90 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9eca6e2..296d66e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,31 +1,13 @@ Guidelines for Developing and Contributing Code =============================================== -Table of Contents ------------------ - -1. Introduction -2. Development - - Directory Structure - - Branches - - Contributing - - Porting -3. Coding Guidelines - - General - - Tool Support -4. Documentation Guidelines - - General - - Special Commands - - Structure - - Example - -1. Introduction ---------------- +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. -2. Development --------------- +Development +----------- ### Directory Structure @@ -93,8 +75,8 @@ Please use these defines for new platform specific code. If additional defines a A list of macros to check the underlying platform, compiler versions, etc. can be found here: http://sourceforge.net/p/predef/wiki/Home/ -3. Coding Guidelines --------------------- +Coding Guidelines +----------------- ### General @@ -144,8 +126,8 @@ operation, i.e., in the methods for pushing and popping elements. #endif ``` -4. Documentation Guidelines ---------------------------- +Documentation Guidelines +------------------------ ### General diff --git a/README.md b/README.md index 3f6e641..2e8cf21 100644 --- a/README.md +++ b/README.md @@ -189,7 +189,17 @@ which copies the contents of the "install" folder to the "bin", "lib", and "incl 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 + +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. ### Using C++ @@ -216,70 +226,15 @@ The C header files can be included as follows: #include #include -or simply - - #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++. +Alternatively, you can include MTAPI by `#include`. +### Documentation -Known Bugs and Limitations --------------------------- +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. -- 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. +### Limitations and Important Notes +------------------------------ - - -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. - - - -Components ----------- - -EMB² consists of various components. 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² 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 - -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. +- 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. -- libgit2 0.26.0