Contribute

Dear Contributor,

this is an agile project, and you are welcome to make suggestions, to improve our implementation, or to evolve (and perhaps refine) the interface of LIBXSMM! There are a few rules and coding standards to follow, and we are asking you to review (and perhaps discuss and refine these rules), but to also adhere with your best effort. Right now, rules are not "enforced" by scripts or such. If this would be helpful - please let us know.

Collaboration

• List of forks ordered by date: https://api.github.com/repos/libxsmm/libxsmm/forks?sort=newest

Coding Standard

• The library is implemented in C, and more specifically adheres pedantically to the C89 standard. One may check compilation of any contribution using make PEDANTIC=2.
• Since the library also supports a header-only use case (mainly aiming for C++ libraries using LIBXSMM), the C code must be also accepted as C++ code. This is currently only weakly exercised (make test-cpp).
• Please pay attention to function attributes and naming convention. Internal functions are function private to a translation unit, such function should carry "internal_[name of the translation unit]" as a prefix (e.g., internal_dnn_handle_somefunction when it is located in libxsmm_dnn_handle.c). Such function must carry LIBXSMM_INLINE LIBXSMM_RETARGETABLE in front of the return type, and no prototype is needed.
• Sample code may be written in C, C++, Fortran, or any language used by an application represented by the sample code. For instance, Shell scripts or Python code may be another item of the list.
• Regarding Git, please follow any "good and usual practices". However, it is expected to make a meaningful comment for every commit (commit message). We do not rush code into the repository a.k.a. "update", "going home now", or "good evening".

Supported Compilers

• Our main compiler suite is based on GNU's Compiler Collection, but complemented with LLVM/Clang (clang and clang++). Our Travis CI suite tends to use older GCC/Clang versions, which is our effective minimum requirement. The actual compiler versions are exercised and stated during compilation. Travis CI must pass for any contribution.
• A variety of Intel Compiler versions is also needed to be checked prior to any release of LIBXSMM. It is not necessary to check with Intel Compiler when making a contribution. One can find the build complete build status here.
• Please rely on wrappers for compiler directives (pragmas) e.g., LIBXSMM_PRAGMA_SIMD rather than #pragma simd. If there is a certain directive missing, please request it!
• Please use the LIBXSMM_VLA_* macros rather than compiler-specific expression to handle multi-dimensional arrays. The VLA-macros do not require any further distinction between different compilers (no ifdef, etc.).

Pedantic Rules

• Beyond compiling with PEDANTIC=2, there are some "unwritten" rules such as respecting the coding style of a particular component of LIBXSMM. For instance, the frontend code (include/* and src/libxsmm*) somewhat differs in style when compared to the backend code (rest of src directory).
  More particular, please respect:
  • The way functions are called or arguments are embraced.
  • The way the signature of a function is laid out.
  • The way control structures and blocks are embraced and indented.
• Additional rules:
  • Macros should place the hash at column zero, i.e. leftmost.
  • Conditional compilation may look like #if defined(SYMBOL) or #if !defined(SYMBOL),
    except for include guards where #ifndef is preferred.
  • Make variables "as constant as possible" even when everything is "just" C code.
  • Comparisons against a constant value should bring the constant into a leading position.
    Here is an example why this is preferred: e2509a9
  • No trailing white spaces please (our head does not fall to sleep while we are coding ;-)
  • No tabs please (our code is not about dirty dishes ;-)
  • No calls to exit anywhere (except sample code).
• Good and usual practices
  • Please do not pollute the global namespace with generic symbol names (macros and code!)
  • Please do not omit curly braces for multi-line control-flow