1 .. _clangformat:
2
3 clang-format
4 ============
5
6 ``clang-format`` is a tool to format C/C++/...
7 a set of rules and heuristics. Like most tools
8 nor covers every single case, but it is good e
9
10 ``clang-format`` can be used for several purpo
11
12 - Quickly reformat a block of code to the ke
13 when moving code around and aligning/sorti
14
15 - Spot style mistakes, typos and possible im
16 you maintain, patches you review, diffs, e
17
18 - Help you follow the coding style rules, sp
19 new to kernel development or working at th
20 projects with different coding styles.
21
22 Its configuration file is ``.clang-format`` in
23 The rules contained there try to approximate t
24 coding style. They also try to follow :ref:`Do
25 as much as possible. Since not all the kernel
26 it is possible that you may want to tweak the
27 subsystem or folder. To do so, you can overrid
28 another ``.clang-format`` file in a subfolder.
29
30 The tool itself has already been included in t
31 Linux distributions for a long time. Search fo
32 your repositories. Otherwise, you can either d
33 LLVM/clang binaries or build the source code f
34
35 https://releases.llvm.org/download.html
36
37 See more information about the tool at:
38
39 https://clang.llvm.org/docs/ClangFormat.ht
40
41 https://clang.llvm.org/docs/ClangFormatSty
42
43
44 .. _clangformatreview:
45
46 Review files and patches for coding style
47 -----------------------------------------
48
49 By running the tool in its inline mode, you ca
50 folders or individual files for code style mis
51
52 To do so, you can run something like::
53
54 # Make sure your working directory is clea
55 clang-format -i kernel/*.[ch]
56
57 And then take a look at the git diff.
58
59 Counting the lines of such a diff is also usef
60 the style options in the configuration file; a
61 ``clang-format`` features/versions.
62
63 ``clang-format`` also supports reading unified
64 patches and git diffs easily. See the document
65
66 https://clang.llvm.org/docs/ClangFormat.ht
67
68 To avoid ``clang-format`` formatting some port
69
70 int formatted_code;
71 // clang-format off
72 void unformatted_code ;
73 // clang-format on
74 void formatted_code_again;
75
76 While it might be tempting to use this to keep
77 ``clang-format``, specially if you are writing
78 a maintainer, please note that people might be
79 ``clang-format`` versions or not have it avail
80 you should probably refrain yourself from usin
81 at least until we see if ``clang-format`` beco
82
83
84 .. _clangformatreformat:
85
86 Reformatting blocks of code
87 ---------------------------
88
89 By using an integration with your text editor,
90 blocks (selections) of code with a single keys
91 useful when moving code around, for complex co
92 for multi-line macros (and aligning their back
93
94 Remember that you can always tweak the changes
95 where the tool did not do an optimal job. But
96 it can be very useful.
97
98 There are integrations for many popular text e
99 like vim, emacs, BBEdit and Visual Studio you
100 For instructions, read the appropriate section
101
102 https://clang.llvm.org/docs/ClangFormat.ht
103
104 For Atom, Eclipse, Sublime Text, Visual Studio
105 editors and IDEs you should be able to find re
106
107 For this use case, consider using a secondary
108 so that you can tweak a few options. See clang
109
110
111 .. _clangformatmissing:
112
113 Missing support
114 ---------------
115
116 ``clang-format`` is missing support for some t
117 in kernel code. They are easy to remember, so
118 regularly, you will quickly learn to avoid/ign
119
120 In particular, some very common ones you will
121
122 - Aligned blocks of one-line ``#defines``, e
123
124 #define TRACING_MAP_BITS_DEFAULT
125 #define TRACING_MAP_BITS_MAX
126 #define TRACING_MAP_BITS_MIN
127
128 vs.::
129
130 #define TRACING_MAP_BITS_DEFAULT 11
131 #define TRACING_MAP_BITS_MAX 17
132 #define TRACING_MAP_BITS_MIN 7
133
134 - Aligned designated initializers, e.g.::
135
136 static const struct file_operations up
137 .owner = THIS_MODULE,
138 .open = probes_open,
139 .read = seq_read,
140 .llseek = seq_lseek,
141 .release = seq_release,
142 .write = probes_write
143 };
144
145 vs.::
146
147 static const struct file_operations up
148 .owner = THIS_MODULE,
149 .open = probes_open,
150 .read = seq_read,
151 .llseek = seq_lseek,
152 .release = seq_release,
153 .write = probes_write,
154 };
155
156
157 .. _clangformatextra:
158
159 Extra features/options
160 ----------------------
161
162 Some features/style options are not enabled by
163 file in order to minimize the differences betw
164 code. In other words, to make the difference a
165 which makes reviewing full-file style, as well
166 as possible.
167
168 In other cases (e.g. particular subsystems/fol
169 might be different and enabling some of these
170 better the style there.
171
172 For instance:
173
174 - Aligning assignments (``AlignConsecutiveAs
175
176 - Aligning declarations (``AlignConsecutiveD
177
178 - Reflowing text in comments (``ReflowCommen
179
180 - Sorting ``#includes`` (``SortIncludes``).
181
182 They are typically useful for block re-formatt
183 You might want to create another ``.clang-form
184 from your editor/IDE instead.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.