git.s-ol.nu ~forks/DiligentCore / 66cbb7e
Added code_formatting.md Egor Yusov 1 year, 9 months ago
1 changed file(s) with 57 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
0 # Source Code Formatting
1
2 Diligent Engine uses [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to valdiate and enforce
3 consistent source code formatting style throught the code base. The format is validated by appveyor and travis
4 for each commit and pull request, and the build will fail if any code formatting issue is found. You can check the
5 logs to find the exact problem. It is, however, may be hard to strictly follow the formatting rules, so using
6 clang-format to automatically correct all issues when working with the source code is recommended.
7
8 :warning: The output of the clang-format tool may vary between versions even if the configuration file stays unchanged.
9 Diligent Engine uses clang-format 10.0.0, which must also be used by anyone to make sure formatting results are the same.
10 For convenience, clang-format executables for Windows, Linux and Mac are checked in into the codebase and can be found at
11 [DiligentCore/BuildTools/FormatValidation](https://github.com/DiligentGraphics/DiligentCore/tree/master/BuildTools/FormatValidation).
12
13 ## Validation
14
15 Diligent Engine provides script files that can be executed to validate the source code formatting of every module. These scripts
16 can be found under `BuildTools/FormatValidation` folder. Besides that, CMake generates build targets
17 (e.g. `DiligentCore-ValidateFormatting`) that run the same scripts. Building these targets has the effect of format validation,
18 so if All-build finishes without errors, the code should be properly formatted.
19
20 ## Using clang-format to format the source code
21
22 You can run clang-format to format files in place, for example:
23
24 ```
25 clang-format -i src/*.cpp include/*.h
26 ```
27
28 Please refer to [this page](https://clang.llvm.org/docs/ClangFormat.html) for more details.
29
30 If you have clang-format installed and python in your path, there will be a new git command
31 that will check if your currently modified files need to be formatted:
32
33 ```
34 git clang-format
35 ```
36
37 You can also set up a [git hook](https://git-scm.com/docs/githooks) to automatically check that every
38 commit complies with the formatting rules.
39
40 ## Using clang-format with the IDE
41
42 clang-format [supports integration](https://clang.llvm.org/docs/ClangFormat.html) with many popular IDEs.
43 Formatting the code directly from the editor is probably the most convenient way as it let's you see the
44 results right-away. In certain circumstances it may be preferrable to override automatic formatting using
45 special comments:
46
47 ```cpp
48 // clang-format off
49 ...
50 // clang-format on
51 ```
52
53 In particular, to configure Visual Studio 2017 or late to use clang-format, open `Tools -> Options` dialog and
54 go to `Text Editor -> C/C++ -> Formatting` tab. Mark `Enable ClangFormat` checkbox, and make sure to use custom clang-format
55 file either from the source tree, or, if you have the right version installed, from LLVM distribution.
56 In the same dialog you can also configure various formatting options.