Using clang-format on rtems.git

General
1

We have just about finished making an initial pass over most of rtems.git using clang-format with two supported styles:

For most of rtems.git we expect to use the RTEMS Style. The modified LLVM style is used in a few areas:

  • cpukit/debugger and its header files
  • cpukit/libfs/src/rfs and its header files
  • cpukit/lbdl and its header files
  • cpukit/librtemcxx and its header files

At present, we are not applying any formatting to BSPs. In the future, we would expect each BSP to either adopt one of the above two styles, or to come with its own clang-format configuration to use.

To use clang-format with the RTEMS Style, you need to have the newest (yet to be released) version. We recommend using the RTEMS Source Builder to build it, for example my build command is:

cd rtems-source-builder/bare
../source-builder/sb-set-builder --log=l-clang-format.txt --prefix=/mnt/devel/development/rtems/7 devel/clang-format

This is the same prefix where I put my RTEMS tools etc., so that this clang-format will be picked up in my PATH environment when I’m working with RTEMS.

How To

You can integrate clang-format with your IDE, see https://clang.llvm.org/docs/ClangFormat.html for details on several common IDEs.

Additionally, clang-format has a git extension that will be installed to the prefix/bin. You can see if it is working with: git clang-format -h

Using it on git is really easy, you can either run it on staged (i.e., git add) but uncommited files, on commits, or on differences between commit ranges. At this moment, you need to provide a .clang-format-ignore file to disable formatting in areas of rtems.git that are not using the RTEMS Style. For now, you can download this clang-format-ignore.txt (970 Bytes) and rename it to rtems.git/.clang-format-ignore

I think the easiest way to use it is by running git clang-format after staging but before committing. The next easiest is after you make a commit. Here are the two basic workflows:

After staging before committing

git add/rm/mv/etc
git clang-format
git commit

After committing

git commit -a
git clang-format HEAD~1
git commit -a -m "fixup! `git rev-parse --short HEAD`"
git rebase -i --autosquash HEAD~2

This can be simplified a bit, I just added a few things that might help with automation if you’re so inclined.

Caveats

Now you can use clang-format in rtems.git and it will work on most of the files that are designated as RTEMS Style formatted. I’ll update this information as the state of support evolves. Much of the ongoing discussion related to this support is in Handling clang-format style files in rtems.git tree (#5458) · Issues · RTEMS / RTOS / RTEMS · GitLab and Source code formatting locations. (#24) · Issues · Administration / Integration · GitLab. Currently this only works for the RTEMS Style formatting, and does not work on all files that use that format, but it works on most of them. Once these issues are resolved, hopefully it can be made to work for all format styles we use and all files.