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

    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

    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.