1.. _clangformat: 2 3clang-format 4============ 5 6``clang-format`` is a tool to format C/C++/... code according to 7a set of rules and heuristics. Like most tools, it is not perfect 8nor 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 22Its configuration file is ``.clang-format`` in the root of the kernel tree. 23The rules contained there try to approximate the most common kernel 24coding style. They also try to follow :ref:`Documentation/process/coding-style.rst <codingstyle>` 25as much as possible. Since not all the kernel follows the same style, 26it is possible that you may want to tweak the defaults for a particular 27subsystem or folder. To do so, you can override the defaults by writing 28another ``.clang-format`` file in a subfolder. 29 30The tool itself has already been included in the repositories of popular 31Linux distributions for a long time. Search for ``clang-format`` in 32your repositories. Otherwise, you can either download pre-built 33LLVM/clang binaries or build the source code from: 34 35 https://releases.llvm.org/download.html 36 37See 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 46Review files and patches for coding style 47----------------------------------------- 48 49By running the tool in its inline mode, you can review full subsystems, 50folders or individual files for code style mistakes, typos or improvements. 51 52To do so, you can run something like:: 53 54 # Make sure your working directory is clean! 55 clang-format -i kernel/*.[ch] 56 57And then take a look at the git diff. 58 59Counting the lines of such a diff is also useful for improving/tweaking 60the 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 64patches and git diffs easily. See the documentation at: 65 66 https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting 67 68To 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 76While 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 78a maintainer, please note that people might be running different 79``clang-format`` versions or not have it available at all. Therefore, 80you should probably refrain yourself from using this in kernel sources; 81at least until we see if ``clang-format`` becomes commonplace. 82 83 84.. _clangformatreformat: 85 86Reformatting blocks of code 87--------------------------- 88 89By using an integration with your text editor, you can reformat arbitrary 90blocks (selections) of code with a single keystroke. This is specially 91useful when moving code around, for complex code that is deeply intended, 92for multi-line macros (and aligning their backslashes), etc. 93 94Remember that you can always tweak the changes afterwards in those cases 95where the tool did not do an optimal job. But as a first approximation, 96it can be very useful. 97 98There are integrations for many popular text editors. For some of them, 99like vim, emacs, BBEdit and Visual Studio you can find support built-in. 100For instructions, read the appropriate section at: 101 102 https://clang.llvm.org/docs/ClangFormat.html 103 104For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other 105editors and IDEs you should be able to find ready-to-use plugins. 106 107For this use case, consider using a secondary ``.clang-format`` 108so that you can tweak a few options. See clangformatextra_. 109 110 111.. _clangformatmissing: 112 113Missing support 114--------------- 115 116``clang-format`` is missing support for some things that are common 117in kernel code. They are easy to remember, so if you use the tool 118regularly, you will quickly learn to avoid/ignore those. 119 120In 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 159Extra features/options 160---------------------- 161 162Some features/style options are not enabled by default in the configuration 163file in order to minimize the differences between the output and the current 164code. In other words, to make the difference as small as possible, 165which makes reviewing full-file style, as well diffs and patches as easy 166as possible. 167 168In other cases (e.g. particular subsystems/folders/files), the kernel style 169might be different and enabling some of these options may approximate 170better the style there. 171 172For instance: 173 174 - Aligning assignments (``AlignConsecutiveAssignments``). 175 176 - Aligning declarations (``AlignConsecutiveDeclarations``). 177 178 - Reflowing text in comments (``ReflowComments``). 179 180 - Sorting ``#includes`` (``SortIncludes``). 181 182They are typically useful for block re-formatting, rather than full-file. 183You might want to create another ``.clang-format`` file and use that one 184from your editor/IDE instead. 185