Commit | Line | Data |
---|---|---|
d4ef8d3f MO |
1 | .. _clangformat: |
2 | ||
3 | clang-format | |
4 | ============ | |
5 | ||
6 | ``clang-format`` is a tool to format C/C++/... code according to | |
7 | a set of rules and heuristics. Like most tools, it is not perfect | |
8 | nor covers every single case, but it is good enough to be helpful. | |
9 | ||
10 | ``clang-format`` can be used for several purposes: | |
11 | ||
12 | - Quickly reformat a block of code to the kernel style. Specially useful | |
13 | when moving code around and aligning/sorting. See clangformatreformat_. | |
14 | ||
15 | - Spot style mistakes, typos and possible improvements in files | |
16 | you maintain, patches you review, diffs, etc. See clangformatreview_. | |
17 | ||
18 | - Help you follow the coding style rules, specially useful for those | |
19 | new to kernel development or working at the same time in several | |
20 | projects with different coding styles. | |
21 | ||
22 | Its configuration file is ``.clang-format`` in the root of the kernel tree. | |
23 | The rules contained there try to approximate the most common kernel | |
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 follows the same style, | |
26 | it is possible that you may want to tweak the defaults for a particular | |
27 | subsystem or folder. To do so, you can override the defaults by writing | |
28 | another ``.clang-format`` file in a subfolder. | |
29 | ||
30 | The tool itself has already been included in the repositories of popular | |
31 | Linux distributions for a long time. Search for ``clang-format`` in | |
32 | your repositories. Otherwise, you can either download pre-built | |
33 | LLVM/clang binaries or build the source code from: | |
34 | ||
e7b4311e | 35 | https://releases.llvm.org/download.html |
d4ef8d3f MO |
36 | |
37 | See more information about the tool at: | |
38 | ||
39 | https://clang.llvm.org/docs/ClangFormat.html | |
40 | ||
41 | https://clang.llvm.org/docs/ClangFormatStyleOptions.html | |
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 can review full subsystems, | |
50 | folders or individual files for code style mistakes, typos or improvements. | |
51 | ||
52 | To do so, you can run something like:: | |
53 | ||
54 | # Make sure your working directory is clean! | |
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 useful for improving/tweaking | |
60 | the style options in the configuration file; as well as testing new | |
61 | ``clang-format`` features/versions. | |
62 | ||
63 | ``clang-format`` also supports reading unified diffs, so you can review | |
64 | patches and git diffs easily. See the documentation at: | |
65 | ||
66 | https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting | |
67 | ||
68 | To avoid ``clang-format`` formatting some portion of a file, you can do:: | |
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 a file always in sync with | |
77 | ``clang-format``, specially if you are writing new files or if you are | |
78 | a maintainer, please note that people might be running different | |
79 | ``clang-format`` versions or not have it available at all. Therefore, | |
80 | you should probably refrain yourself from using this in kernel sources; | |
81 | at least until we see if ``clang-format`` becomes commonplace. | |
82 | ||
83 | ||
84 | .. _clangformatreformat: | |
85 | ||
86 | Reformatting blocks of code | |
87 | --------------------------- | |
88 | ||
89 | By using an integration with your text editor, you can reformat arbitrary | |
90 | blocks (selections) of code with a single keystroke. This is specially | |
91 | useful when moving code around, for complex code that is deeply intended, | |
92 | for multi-line macros (and aligning their backslashes), etc. | |
93 | ||
94 | Remember that you can always tweak the changes afterwards in those cases | |
95 | where the tool did not do an optimal job. But as a first approximation, | |
96 | it can be very useful. | |
97 | ||
98 | There are integrations for many popular text editors. For some of them, | |
99 | like vim, emacs, BBEdit and Visual Studio you can find support built-in. | |
e0a45cda | 100 | For instructions, read the appropriate section at: |
d4ef8d3f MO |
101 | |
102 | https://clang.llvm.org/docs/ClangFormat.html | |
103 | ||
104 | For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other | |
105 | editors and IDEs you should be able to find ready-to-use plugins. | |
106 | ||
107 | For this use case, consider using a secondary ``.clang-format`` | |
108 | so that you can tweak a few options. See clangformatextra_. | |
109 | ||
110 | ||
111 | .. _clangformatmissing: | |
112 | ||
113 | Missing support | |
114 | --------------- | |
115 | ||
116 | ``clang-format`` is missing support for some things that are common | |
117 | in kernel code. They are easy to remember, so if you use the tool | |
118 | regularly, you will quickly learn to avoid/ignore those. | |
119 | ||
120 | In particular, some very common ones you will notice are: | |
121 | ||
122 | - Aligned blocks of one-line ``#defines``, e.g.:: | |
123 | ||
124 | #define TRACING_MAP_BITS_DEFAULT 11 | |
125 | #define TRACING_MAP_BITS_MAX 17 | |
126 | #define TRACING_MAP_BITS_MIN 7 | |
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 uprobe_events_ops = { | |
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 uprobe_events_ops = { | |
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 default in the configuration | |
163 | file in order to minimize the differences between the output and the current | |
164 | code. In other words, to make the difference as small as possible, | |
165 | which makes reviewing full-file style, as well diffs and patches as easy | |
166 | as possible. | |
167 | ||
168 | In other cases (e.g. particular subsystems/folders/files), the kernel style | |
169 | might be different and enabling some of these options may approximate | |
170 | better the style there. | |
171 | ||
172 | For instance: | |
173 | ||
174 | - Aligning assignments (``AlignConsecutiveAssignments``). | |
175 | ||
176 | - Aligning declarations (``AlignConsecutiveDeclarations``). | |
177 | ||
178 | - Reflowing text in comments (``ReflowComments``). | |
179 | ||
180 | - Sorting ``#includes`` (``SortIncludes``). | |
181 | ||
182 | They are typically useful for block re-formatting, rather than full-file. | |
183 | You might want to create another ``.clang-format`` file and use that one | |
184 | from your editor/IDE instead. |