Check your code¶
Below, we provide tools and scripts that you can use to check the formatting of your code. Before you get started, please take a look at our detailed guidelines for C++ coding in NEST
Development environment¶
We have provided an environment.yml file that contains all packages to do development in NEST, including the tools to check coding style.
Tooling¶
The clang-format tool is built
on the clang compiler frontend. It prettyprints input files in a
configurable manner, and also has Vim and Emacs integration. We supply a
clang-format-file (<build_support/format_all_c_c++_files.sh>
to enforce some parts of the coding style. During
the code review process we check that there is no difference between the committed
files and the formatted version of the committed files.
Developers can benefit from the tool by formatting their changes before issuing a pull request. For fixing more files at once we provide a script that applies the formatting.
From the source directory call:
./build_support/format_all_c_c++_files.sh [start folder, defaults to '$PWD']
The code has to compile without warnings (in the default settings of the build infrastructure). We restrict ourselves to the C++11 standard for a larger support of compilers on various cluster systems and supercomputers.
We use clang-format version 13 in our CI. If your clang-format executable is not version 13, you need to specify an executable with version 13 explicitly with the –clang-format option to ensure consistency with the NEST CI.
Furthermore, we use Vera++, which
‘is a programmable tool for verification, analysis and transformation of C++
source code’. It enables further checks for the code complying to the coding
guidelines. We provide the vera-profile-nest (<build_support/vera++.profile>
) file in the
repository (which needs to be copied/symlinked into vera++home>/lib/vera++/profiles/
).
We then check that there are no messages generated by the execution of the following command:
vera++ -profile nest <committed file>
Finally, we let cppcheck statically analyse the committed files and check for severe errors. We require cppcheck version 1.69 or later.
cppcheck --enable=all <committed file>
Note
For Python, we enforce PEP8 formatting.
Local static analysis¶
We ship a script ./build_support/check_code_style.sh
that lets you perform the
checks on all changed files as we do during the Travis CI tasks.
$ ./build_support/check_code_style.sh --help
Usage: check_code_style.sh [options ...]
Usage: ./build_support/check_code_style.sh [options ...]
This script processes C/C++ and Python source code files to verify compliance with the NEST
coding style guidelines. The checks are performed the same way as in the NEST Travis CI
build and test environment. If no file is specified, a local 'git diff' is issued to obtain
the changed files in the commit range '<git-sha-start>..<git-sha-end>'. By default, this is
'master..head'.
The script expects to be run from the base directory of the NEST sources,
i.e. all executions should start like:
./build_support/check_code_style.sh ...
The setup of the tooling is explained here:
https://nest-simulator.readthedocs.io/en/latest/contribute/coding_guidelines_cpp.html
Options:
--help This help.
--[i]ncremental Prompt user before each file analysis.
--file=/path/to/file Perform the analysis on this file.
--git-start=Git_SHA_value Hash value (Git SHA) from which Git starts the diff.
Default: --git-start=master
--git-end=Git_SHA_value Hash value (Git SHA) at which Git ends the diff.
Default: --git-start=HEAD
--vera++=exe The name of the VERA++ executable.
Default: --vera++=vera++
--cppcheck=exe The name of the CPPCHECK executable.
Default: --cppcheck=cppcheck
Note: CPPCHECK version 1.69 or later is required.
This corresponds to the version installed in
the NEST Travis CI build and test environment.
--clang-format=exe The name of the CLANG-FORMAT executable.
Default: --clang-format=clang-format
Note: CLANG-FORMAT version 13 is required.
--pep8=exe The name of the PEP8 executable.
Default: --pep8=pep8
--perform-vera=on/off Turn on/off VERA++ analysis.
Default: --perform-vera=on
--perform-cppcheck=on/off Turn on/off CPPCHECK analysis.
Default: --perform-cppcheck=off
--perform-clang-format=on/off Turn on/off CLANG-FORMAT analysis.
Default: --perform-clang-format=on
--perform-pep8=on/off Turn on/off PEP8 analysis.
Default: --perform-pep8=on
Assuming you are in source directory of NEST and you want to check all changed
files between the commits 104d47c0
and d66e4465
, execute the following
line:
./build_support/check_code_style.sh --git-start=104d47c0 --git-end=d66e4465