clang format

This page describes how to use and configure clang-format. clang-format is a command line tool built on top of llvm that enforces whitespace conventions for c/c++ code. The clang-format tool is part of the clang package. This will be installed when the mantid-developer package is installed for non-Windows users. For Windows users an installer is available (here)

The configuration for it (.clang-format) is in the root directory of the repository and is discovered by the tool automatically. clang-format includes support for e.g. the coding styles: LLVM, Google, Chromium and Mozilla. Mantid uses the llvm style, see also the Mantid C++ coding standards page.

Version

Formatting is enforced by the build servers, which use version 6.0. It is strongly advised to use this version also.

Using git to format

There is a tool, git-clang-format, which adds support to git to automatically format code that is added before it is committed. This only changes the formatting of the lines that you have already edited. In general, after you make your changes you can do the following

git add <list of files>
git clang-format
git add <list of files that got formatting changes>
git commit

This will format only the lines that you had edited already, eliminating the possibility of introducing merge conflicts.

Configure your favorite IDE or editor for using clang-format

Most everything can attach to clang-format. The list in clang-format's documentation.

• BBEdit
• emacs
• vim (llvm) or vim (rhysd)
• Visual Studio: See notes below
• git-clang-format

Others have plugins/config from other sources:

• Sublime (hiding in the page)
• QTCreator (gist describing howto. Ignore the configuration and just select LLVM and it will be available in the Tools->Beautifier menu) ** To configure a keyboard shortcut go to "Tools->Options->Environment->Keyboard and search for ClangFormat. Add your desired short cut
• XCode (on github)
• [Eclipse] (https://github.com/wangzw/cppstyle) (replace Google with LLVM as style)
• CLion (Add clang-format as an external tool in File->Settings, Tools->External tools and put -i -style=file $FilePath$ in the "Parameters" field. You can then bind a key which will clang-format the current file.)

Visual Studio Integration

Visual Studio 2019 now provides native support for Clang\LLVM. The settings are on the Tools, Options screen under Text Editor, C/C++, Formatting. If the Default formatting style setting is set to "Visual Studio" then Visual Studio will look for a .clang-format file in the root of the source code directory and apply the style specified in there (which is LLVM for Mantid). The clang-format executable that is part of the Visual Studio installation isn't guaranteed to be the same as the one used by Mantid so it is recommended that the "Use custom clang-format.exe" option is used to point at the required version.

For older versions of Visual Studio (eg VS 2017) a plugin is available (http://clang.llvm.org/docs/ClangFormat.html#visual-studio-integration). This link only provides the plugin for the most recent SVN build. The plugin built against clang-format 6.0 is available in mantid\external\src\ThirdParty\bin\ClangFormat-6.0.vsix but unfortunately LLVM no longer provide this as a download.

To ensure that Visual Studio doesn't update the plugin go to:

Tools -> Extensions and Updates -> Untick Automatically Update this Extension for Clang Format