Using Clang Format

We use clang-format to maintain our coding style, and it is enforced for any new pull requests to the main branch. However, even if you do not plan to contribute to the public code we recommend using it, as having a clear and consistently structured code helps avoid errors and makes your code more readable.

Note that some of the following instructions will only work with newer versions of Python (e.g. v3.6+). If you are working on a cluster, the system Python version may be too old (As of January 2020, Python 2 is deprecated and should be avoided.) and you may need to load a newer version from a module.

Getting Clang Format

We recommend installing clang-format using the Python package manager pip (see here if you don't have pip available). You should install the version that is current enforced by the GitHub action that checks it (currently v16 at time of writing). This can be done with a command such as

python3 -m pip install --user clang-format==16.0.4

Note that the --user flag means that clang-format will be installed to your home directory (specifically $HOME/.local/bin) rather than a system directory but you can of course omit this flag and install to a system directory if you prefer and have superuser permissions. Make sure the directory in which it is installed is in your PATH environment variable so you can run the command clang-format without having to specify the full path. This can be done by adding the line

export PATH=${HOME}/.local/bin:$PATH

to your ~/.bashrc file (assuming you are using BASH - the corresponding file for ZSH is ~/.zshrc).

Alternatively, you can install clang-format using your system's package manager (e.g. apt on Ubuntu/Debian) or Homebrew on macOS. However, this will probably install a different version to the one we check with which may result in slightly different formatting.

Running Clang Format

Before committing any changes that you have made, you should run clang-format on all files by executing the run_clang_format script in the repository base directory.

Alternatively, you may be able to set up your text editor to automatically run clang-format when you save a file. There are guides for several editors such as

• Vim
• Emacs
• Atom
• VS Code
• Sublime

Note that some of these guides may assume you have installed clang-format in a different way to that described above. If you set up your editor using one of these guides make sure they are enforcing the -style=file option as this will use our style configuration rather than a different one.

Setting up the pre-commit hook

Since it is easy to forget to run clang-format, we have added a pre-commit hook to check the formatting before committing.

To set up the pre-commit hook on your local clone of the repository, install the pre-commit python package using a command such as

python3 -m pip install --user pre-commit

Then cd into your local clone of GRChombo e.g.

cd /path/to/GRChombo

and run

pre-commit install

The next time you try to commit a change, it will configure the pre-commit hook environment which may take a minute or two but subsequently it should be much faster. If there are any staged changes which do not conform to the style, it will not allow you to commit and will make the necessary changes to format the code correctly. Note that these changes will not be staged and you will have to manually do this with git add.