87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
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.
|