Documentation/process/clang-format.rst

   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
  35     https://releases.llvm.org/download.html
  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.
 100 For instructions, read the appropriate section at:
 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.