Development/clang-format

From The Document Foundation Wiki
Jump to navigation Jump to search

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, and then copy that to the /opt/lo/bin/ folder. 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/

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.