Formatting Tools

This page serves to describe and document a couple of tools, one of which automatically formats C++ codes and the other which formats XML code. These tools may be of use to Albany and this page is here to gather any information we need to make choices about using them.

clang-format

clang-format has recently become the open-source tool of choice for automatically formatting C++ code. It is guaranteed not to alter the compile or runtime behavior of your code because it is founded on a very robust compiler infrastructure.

It can be installed as part of the pre-built binary distribution of LLVM.

The simplest way to use it is to modify a set of files in-place:

clang-format -i one.cpp two.hpp
clang-format -i *pp

There are also ways to integrate it into your text editor and into Git so that it only formats the code that you're currently committing.

What it does is controlled by a file named .clang-format which needs to be in the local directory or any directory higher than it in the path (typically we would place this file at the top-level project repository directory).

That file can contain many options, but fortunately there a few built-in "styles" which have reasonable default settings for these options. The styles are named after the popular projects or companies that use them: LLVM, Google, Chromium, Mozilla, and WebKit. @ibaned finds the "Google" style to be most convenient. You can begin your .clang-format file with a line such as:

BasedOnStyle: Google

or you can create your initial .clang-format file as suggested by their documentation using a command like:

clang-format -style=google -dump-config > .clang-format

xmllint

Albany heavily uses XML for its input, and xmllint is a great tool for automatically reformatting XML files. It is typically installed on most Linux machines, and it can be run like this:

xmllint --format input.xml > output.xml