CodeTools

Introduction

A number of 'clang' tools are now available for the standardisation of code style and to sniff out bug-prone behaviour. Here we will be using 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:

• emacs: [1]
• vim: [2]
• vscode: [3]

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. Alternatively, it may be more convenient to invoke clang-tidy directly from SCons.