Jump to content

Development/clang-format

From The Document Foundation Wiki

Introduction

Sometimes when you a submit a patch to Gerrit that you expect to be OK, you get this error from the CI build by Jenkins:

ERROR: The above differences were found between the code to commit 
and the clang-format rules. Tips:

- You may run '/opt/lo/bin/clang-format -i <problematic file>' to fix up style automatically.
- See solenv/clang-format/README on where to get the required version of clang-format binaries.
- If you renamed an excluded file, update solenv/clang-format/excludelist accordingly to keep it excluded.
solenv/clang-format/check-last-commit: KO
Makefile:485: recipe for target 'clang-format-check' failed
make: *** [clang-format-check] Error 1

See .git-hooks/pre-commit and check-last-commit

The problem is that your code does not conform to the coding conventions used in the new files. This is not the case for older cxx/hxx files, as they are kept with the old coding conventions from Apache OpenOffice, in order to minimize the changes, and keep the git history usable. In 2025, ~15000 files in clang-format/excludelist.

If you have encountered the above error message, you have to install clang-format, and then run it on your code to format the code according to the convention for the new files.

Installing clang-format

The easy way to install specific version of clang-format used in LibreOffice is to install it from the binaries. The binaries for clang-format are available here: https://dev-www.libreoffice.org/bin/

You should download the appropriate binary from the above link[1], and then copy that to the /opt/lo/bin/ folder[2]. For example, in x64 Linux you can do the installation with these commands:

wget https://dev-www.libreoffice.org/bin/clang-format-5.0.0-linux64
chmod +x clang-format-5.0.0-linux64
sudo mkdir -p /opt/lo/bin/
sudo cp clang-format-5.0.0-linux64 /opt/lo/bin/clang-format

Then you should make sure that you are running the correct clang-format. You should use /opt/lo/bin/clang-format instead of the system clang-format.

$ which clang-format
/usr/bin/clang-format

$ clang-format --version
clang-format version 10.0.0-4ubuntu1 

$ /opt/lo/bin/clang-format --version
clang-format version 5.0.0 (tags/RELEASE_500/final)

As you can see, the version is different.

Checking the format

To make sure that the formatting of your code is OK, you can invoke this command:

make clang-format-check

Automatic reformatting of the code

After the installation is done, you should use the second one. You should use it this way:

/opt/lo/bin/clang-format -i path/to/thefile.cxx

After re-formatting the source code, just add it to the staging area of the git:

git add path/to/thefile.cxx

and then commit, and resubmit to Gerrit to see it as a new patch set, and then hopefully see the successful build in Jenkins CI.

Notes

  1. If you want to build clang-format from the sources, you should refer to solenv/clang-format/README for the instructions. It should be noted that you don't need to do this step.
  2. As an alternative to putting clang-format in /opt/lo/bin, you can use CLANG_FORMAT environment variable to point to the binary. Another option would be rename the downloaded file to clang-format, and set PATH environment variable in such a way to use it instead of the system binary. These methods are especially useful if you don't have permission to put the binary in the system paths.