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