CodeTools: Difference between revisions
No edit summary |
No edit summary |
||
Line 56: | Line 56: | ||
* vim: [https://clang.llvm.org/docs/ClangFormat.html#vim-integration] | * vim: [https://clang.llvm.org/docs/ClangFormat.html#vim-integration] | ||
* vscode: [https://code.visualstudio.com/docs/cpp/cpp-ide#_code-formatting] | * vscode: [https://code.visualstudio.com/docs/cpp/cpp-ide#_code-formatting] | ||
Xcode: You can create a 'Text Service' and run clang-format from the shell script. See [https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/MakeaSystem-WideService.html] | |||
<pre> | |||
# 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 | |||
</pre> | |||
=clang-tidy= | =clang-tidy= |
Revision as of 00:58, 29 February 2020
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:
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]
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 [6]
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.
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 [7] for details and [8] for installation instructions. It works especially well for VS Code.
- XCode Clang-Analyzer [9]
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.