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 SLF7, 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:

• Consistent formatting between revisions means cleaner diffs
• Consistently formatted code is on the whole easier to read
• Whitespace problems are ironed out (e.g. no trailing whitespace)

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]

Xcode: You can create a 'Text Service' and run clang-format from the shell script. See [4]

# Shell script for Xcode/apple 'Text Service'
# Input (is entire selection +) receives all selected text
# Select: output replaces selected text
# You can select text in Xcode and run this 'Text Service' to format the selected text and replace it with formatted output.

/usr/bin/local/clang-format # replace /usr/bin/local with the install location of clang-format

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
• Performance tips e.g. passing by const& instead of value.

What clang-tidy looks for will depend on the enabled checks. A list of available checks can be found at [5]

IDE Integration

It goes without saying that manually running and reading clang-tidy output from the command-line is not ideal. Its output is much better served by an IDE or Text Editor.

Most editors will have support for clang-tidy and display warning messages as you update code.

• Clangd is a widely supported 'language server' interface to clang tools. Please see [6] for details and [7] for installation instructions. It works especially well for VS Code.
• XCode Clang-Analyzer [8]

To get this to work, you will need to copy over an up-to-date version of compile_commands.json for your editor to correctly run clang-tidy. If your editor environment is not SLF7, you may need to generate this with the above steps on a SLF7 machine that can set up and compile the Offline software. Make sure that when you move it to a different machine that the "directory" value on all JSON list entries point to the correct location. You can fix this quickly via a search-and-replace all operation.

In the editor environment you copy this to, you will need the correct CVMFS mounts (mu2e.opensciencegrid.org, fermilab.opensciencegrid.org) for clang-tidy to access the external headers.

Command Line Usage

Clang-tidy requires a compile_commands.json to run correctly, as it needs to know the compile flags for each build target. This can be generated by a script which scrapes these from SCons output [9]

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.