UnrealEngine/Engine/Extras/clang-format

This is a work-in-progress project to set up clang-format for the Unreal Engine codebase.

Required binaries

Right now, you have to add clang-format.exe and clang-format-diff.py by yourself. Download them from an LLVM release and put them into this directory.

clang-format-diff

Clang comes with a handy script called clang-format-diff which uses clang-format to format only the lines of code that has changed according to your version control system.

To diff lines that have changed according to Perforce, you can use the script perforce-clang-format-diff.ps1.

Formatting changed lines on save in Rider

You can format files automatically using clang-format-diff when you save changes to them from the Rider IDE.

To do this, go to Rider's "Settings > Tools > File Watchers" and add a two new ones. Here are examples of values from a successful setup of these (the only that change between them is "File type"):

Field	Value
File type	C++ header files (or "C++ files" for .cpp files)
Scope	Open Files
Program	pwsh.exe
Arguments	-File PATH-TO-CHECKOUT\Engine\Extras\clang-format\perforce-clang-format-diff.ps1 FilePath -PerformSlateFiltering
Working directory	FileDir

Note that this example enables the -PerformSlateFiltering flag (see below for info).

Note that the "Show console" option can be useful to debug the watcher.

macOS support

The new perforce-clang-format-diff.py works on both Windows and macOS. You can set it up in Rider like this:

Field	Value
File type	C++ header files (or "C++ files" for .cpp files)
Scope	Open Files
Program	python
Arguments	PATH-TO-CHECKOUT\Engine\Extras\clang-format\perforce-clang-format-diff.py FilePath --verbose
Working directory	FileDir

Known issue: formatting Slate code

Slate code uses an uncommon overload of operator[] to nest widgets declaratively. clang-format doesn't understand this and therefore cannot format such code nicely.

An example of this problem is that this code

AddSlot()
[
    MyWidget
];

is formatted into this

AddSlot()[MyWidget];

which is not what we want for our Slate code.

To work around this issue, we can filter out any Slate code from what we give to clang-format. This works well when using clang-format-diff, which is already diff based.

This technique has been implemented in the perforce-clang-format-diff.ps1 script as a filter on the output of p4 diff where any Slate-like code is removed from the diff before passed onto clang-format-diff.py. Enable this filter by passing -PerformSlateFiltering to perforce-clang-format-diff.ps1.

Note that in rare cases, clang-format-diff will format code surrounding a diff regardless if the surrounding code has been changed or not. This can effectively override -PerformSlateFiltering, causing Slate code to be filtered incorrectly despite using the flag.