CodeTools
Introduction
A couple of 'clang' tools are now available for the standardisation of code style and to sniff out bug-prone behaviour, clang-format and clang-tidy.
To use these tools on SL7 (with CVMFS), please set them up like this:
source /cvmfs/fermilab.opensciencegrid.org/products/common/etc/setups setup mu2e setup clang v5_0_1
clang and its tools can be installed on many systems:
# Debian, Ubuntu sudo apt-get install clang-format clang-tidy # MacOS (Homebrew) brew install clang-format # smaller package, just clang-format # or: # includes clang-format and clang-tidy - but takes up a lot more space brew install llvm ln -s "$(brew --prefix llvm)/bin/clang-format" "/usr/local/bin/clang-format" ln -s "$(brew --prefix llvm)/bin/clang-tidy" "/usr/local/bin/clang-tidy" # Arch Linux sudo pacman -S clang # Fedora sudo dnf install clang
Please note that as of the current HEAD of Mu2e/Offline, there are no .clang-format or .clang-tidy configuration files.
clang-format
Clang-format re-formats code according to a configuration file. Having a consistent code style and format yields numerous benefits:
- Cleaner diffs
- Code is much easier to read
- Pesky trailing whitespace is removed
Basic Usage
To re-format a file in place:
clang-format -i <file(s)>
Glob patterns are also supported e.g. Analyses/src/*.cc
To see what it changed:
git diff
IDE Integration
Clang-format is widely supported:
clang-tidy
Clang-tidy is a static code analyzer which can perform a number of checks, including but not limited to:
- Enforce variable naming conventions
- Enforce C++ core guidelines
- Sniff out bug-prone code
What clang-tidy looks for will depend on the enabled checks. A list of available checks can be found at [4]
Basic Usage
Clang-tidy requires a compile_commands.json to run correctly, as it needs to know the compile flags. This can be generated by a script which scrapes these from SCons output [5]
To analyse <files>, and apply properly-formatted fixes in place:
cd <Offline directory>
curl https://gist.githubusercontent.com/ryuwd/47418eacdadf5369ab4e99492d583f19/raw/e7e0c4559f2af3196c665b0ab9c3aa2bd8878215/generate_compile_commands.py > generate_compile_commands.py
setup mu2e
source setup.sh
python generate_compile_commands.py
# only works for SL7 (CVMFS product)
# other systems: set CLANG_FQ_DIR to where clang include, share, and bin directories are installed
CLANG_TIDY_ARGS="-extra-arg=-isystem$CLANG_FQ_DIR/include/c++/v1 -p . -fix -format"
CLANG_TIDY_RUNNER="${CLANG_FQ_DIR}/share/clang/run-clang-tidy.py"
${CLANG_TIDY_RUNNER} ${CLANG_TIDY_ARGS} <files>
As you can probably see, the set-up required here is non-trivial, requiring the use of an external script. This may motivate adding Compilation DB support into SConstruct.
N.B. Not all checks will provide fixes. Some warning messages will require manual review.