Development/clang-format

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

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

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.

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

↑ 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.
↑ 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.

[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.

[1]

[2]