Contributing¶
License Agreement¶
The code I am contributing is mine, and I have the right to license it.
By submitting a pull request for this project I am granting you a license to distribute said code under the MIT License for the project.
Pull-request guidelines¶
Our code contriubtion guidelines closely follows the model of GitHub pull-requests. The hipBLAS repository follows a workflow which dictates a /master branch where releases are cut, and a /develop branch which serves as an integration branch for new code. Pull requests should:
target the develop branch for integration
ensure code builds successfully.
do not break existing test cases
new unit tests should integrate within the existing googletest framework.
tests must have good code coverage
code must also have benchmark tests, and performance must approach the compute bound limit or memory bound limit.
StyleGuide¶
This project follows the CPP Core guidelines, with few modifications or additions noted below. All pull-requests should in good faith attempt to follow the guidelines stated therein, but we recognize that the content is lengthy. Below we list our primary concerns when reviewing pull-requests.
Interface¶
All public APIs are C99 compatible; all other library code should use C++14
Our minimum supported compiler is clang 3.6
Avoid snake_case
This rule applies specifically to publicly visible APIs, but is also encouraged (not mandated) for internal code
Philosophy¶
Implementation¶
SF.1: Use a
.cpp
suffix for code files and an.h
suffix for interface files if your project doesn’t already follow another conventionWe modify this rule:
.h
: C header files.hpp
: C++ header files
SF.5: A
.cpp
file must include the.h
file(s) that defines its interfaceSF.7: Don’t put a
using
-directive in a header fileSF.8: Use
#include
guards for all.h
filesSF.21: Don’t use an unnamed (anonymous)
namespace
in a headerSL.10: Prefer using
std::array
orstd::vector
instead of a C arrayC.9: Minimize the exposure of class members
F.3: Keep functions short and simple
ES.11: Use
auto
to avoid redundant repetition of type namesES.20: Always initialize an object
ES.23: Prefer the
{}
initializer syntaxCP.1: Assume that your code will run as part of a multi-threaded program
I.2: Avoid global variables
Format¶
C and C++ code is formatted using clang-format
. To run clang-format
use the version in the /opt/rocm/llvm/bin
directory. Please do not use your
system’s built-in clang-format
, as this may be an older version that
will result in different results.
To format a file, use:
/opt/rocm/llvm/bin/clang-format -style=file -i <path-to-source-file>
To format all files, run the following script in rocBLAS directory:
#!/bin/bash
git ls-files -z *.cc *.cpp *.h *.hpp *.cl *.h.in *.hpp.in *.cpp.in | xargs -0 /opt/rocm/llvm/bin/clang-format -style=file -i
Also, githooks can be installed to format the code per-commit:
./.githooks/install
Guidelines:¶
Do not use unnamed namespaces inside of header files.
Use either
template
orinline
(or both) for functions defined outside of classes in header files.Do not declare namespace-scope (not
class
-scope) functionsstatic
inside of header files unless there is a very good reason, that the function does not have any non-const
static
local variables, and that it is acceptable that each compilation unit will have its own independent definition of the function and itsstatic
local variables. (static
class
member functions defined in header files are okay.)Use
static
forconstexpr
template
variables until C++17, after whichconstexpr
variables becomeinline
variables, and thus can be defined in multiple compilation units. It is okay if theconstexpr
variables remainstatic
in C++17; it just means there might be a little bit of redundancy between compilation units.
Static Code Analysis¶
cppcheck
is an open-source static analysis tool. This project uses this tool for performing static code analysis.
Users can use the following command to run cppcheck locally to generate the report for all files.
$ cd hipBLAS
$ cppcheck --enable=all --inconclusive --library=googletest --inline-suppr -i./build --suppressions-list=./CppCheckSuppressions.txt --template="{file}:{line}: {severity}: {id} :{message}" . 2> cppcheck_report.txt
For more information on the command line options, refer to the cppcheck manual on the web.