Debian Codegraph @

subprojects/meson-docs/docs/markdown/Code-formatting.md

raw
1 ---
2 short-description: Code formatting
3 ...
4
5 # clang-format
6
7 *Since 0.50.0*
8
9 When `clang-format` is installed and a `.clang-format` file is found at the main
10 project's root source directory, Meson automatically adds a `clang-format` target
11 that reformat all C and C++ files (currently only with Ninja backend).
12
13 ```sh
14 ninja -C builddir clang-format
15 ```
16
17 *Since 0.58.0*
18
19 It is possible to restrict files to be reformatted with optional
20 `.clang-format-include` and `.clang-format-ignore` files.
21
22 The file `.clang-format-include` contains a list of patterns matching the files
23 that will be reformatted. The `**` pattern matches this directory and all
24 subdirectories recursively. Empty lines and lines starting with `#` are ignored.
25 If `.clang-format-include` is not found, the pattern defaults to `**/*` which
26 means all files recursively in the source directory but has the disadvantage to
27 walk the whole source tree which could be slow in the case it contains lots of
28 files.
29
30 Example of `.clang-format-include` file:
31 ```
32 # All files in src/ and its subdirectories
33 src/**/*
34
35 # All files in include/ but not its subdirectories
36 include/*
37 ```
38
39 The file `.clang-format-ignore` contains a list of patterns matching the files
40 that will be excluded. Files matching the include list (see above) that match
41 one of the ignore pattern will not be reformatted. Unlike include patterns, ignore
42 patterns does not support `**` and a single `*` match any characters including
43 path separators. Empty lines and lines starting with `#` are ignored.
44
45 The build directory and file without a well known C or C++ suffix are always
46 ignored.
47
48 Example of `.clang-format-ignore` file:
49 ```
50 # Skip C++ files in src/ directory
51 src/*.cpp
52 ```
53
54 Note that `.clang-format-ignore` has the same format as used by
55 [`run-clang-format.py`](https://github.com/Sarcasm/run-clang-format).
56
57 A new target `clang-format-check` has been added. It returns an error code if
58 any file needs to be reformatted. This is intended to be used by CI.
59
60 *Since 0.60.0*
61
62 If `.clang-format-include` file is missing and source files are in a git
63 repository, only files tracked by git will be included.