Difference between revisions of "CodeTools"
(Created page with "==Introduction== ==Formatting== ==Include file checker==") |
|||
| Line 1: | Line 1: | ||
| − | == | + | =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. |
| − | ==Include | + | |
| + | To use these tools on SL7 (with CVMFS), please set them up like this: | ||
| + | <pre> | ||
| + | source /cvmfs/fermilab.opensciencegrid.org/products/common/etc/setups | ||
| + | setup mu2e | ||
| + | setup clang v5_0_1 | ||
| + | </pre> | ||
| + | |||
| + | clang and its tools can be installed on many systems: | ||
| + | <pre> | ||
| + | # 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 | ||
| + | |||
| + | </pre> | ||
| + | |||
| + | '''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: | ||
| + | <pre> | ||
| + | clang-format -i <file(s)> | ||
| + | </pre> | ||
| + | Glob patterns are also supported ''e.g. Analyses/src/*.cc'' | ||
| + | |||
| + | To see what it changed: | ||
| + | <pre> | ||
| + | git diff | ||
| + | </pre> | ||
| + | |||
| + | == IDE Integration == | ||
| + | Clang-format is widely supported: | ||
| + | * emacs: [https://clang.llvm.org/docs/ClangFormat.html#emacs-integration] | ||
| + | * vim: [https://clang.llvm.org/docs/ClangFormat.html#vim-integration] | ||
| + | * vscode: [https://code.visualstudio.com/docs/cpp/cpp-ide#_code-formatting] | ||
| + | |||
| + | =clang-tidy= | ||
| + | Clang-tidy is a static code analyzer which performs 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 [https://clang.llvm.org/extra/clang-tidy/checks/list.html] | ||
| + | |||
| + | == 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 [https://gist.github.com/ryuwd/47418eacdadf5369ab4e99492d583f19] | ||
| + | |||
| + | To analyse '''<files>''', and apply properly-formatted fixes ''in place'': | ||
| + | <pre> | ||
| + | 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 | ||
| + | |||
| + | 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> | ||
| + | |||
| + | </pre> | ||
| + | |||
| + | As you can probably see, the set-up required here is non-trivial. | ||
| + | |||
| + | =Include What You Use (IWYU)= | ||
Revision as of 04:33, 25 February 2020
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:
clang-tidy
Clang-tidy is a static code analyzer which performs 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
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.