English

clang-format

clang-format is a tool to format C/C++/... code according toa set of rules and heuristics. Like most tools, it is not perfectnor covers every single case, but it is good enough to be helpful.

clang-format can be used for several purposes:

  • Quickly reformat a block of code to the kernel style. Specially usefulwhen moving code around and aligning/sorting. Seeclangformatreformat.

  • Spot style mistakes, typos and possible improvements in filesyou maintain, patches you review, diffs, etc. Seeclangformatreview.

  • Help you follow the coding style rules, specially useful for thosenew to kernel development or working at the same time in severalprojects with different coding styles.

Its configuration file is.clang-format in the root of the kernel tree.The rules contained there try to approximate the most common kernelcoding style. They also try to followDocumentation/process/coding-style.rstas much as possible. Since not all the kernel follows the same style,it is possible that you may want to tweak the defaults for a particularsubsystem or folder. To do so, you can override the defaults by writinganother.clang-format file in a subfolder.

The tool itself has already been included in the repositories of popularLinux distributions for a long time. Search forclang-format inyour repositories. Otherwise, you can either download pre-builtLLVM/clang binaries or build the source code from:

See more information about the tool at:

Review files and patches for coding style

By running the tool in its inline mode, you can review full subsystems,folders or individual files for code style mistakes, typos or improvements.

To do so, you can run something like:

# Make sure your working directory is clean!clang-format -i kernel/*.[ch]

And then take a look at the git diff.

Counting the lines of such a diff is also useful for improving/tweakingthe style options in the configuration file; as well as testing newclang-format features/versions.

clang-format also supports reading unified diffs, so you can reviewpatches and git diffs easily. See the documentation at:

To avoidclang-format formatting some portion of a file, you can do:

int formatted_code;// clang-format off    void    unformatted_code  ;// clang-format onvoid formatted_code_again;

While it might be tempting to use this to keep a file always in sync withclang-format, specially if you are writing new files or if you area maintainer, please note that people might be running differentclang-format versions or not have it available at all. Therefore,you should probably refrain yourself from using this in kernel sources;at least until we see ifclang-format becomes commonplace.

Reformatting blocks of code

By using an integration with your text editor, you can reformat arbitraryblocks (selections) of code with a single keystroke. This is speciallyuseful when moving code around, for complex code that is deeply intended,for multi-line macros (and aligning their backslashes), etc.

Remember that you can always tweak the changes afterwards in those caseswhere the tool did not do an optimal job. But as a first approximation,it can be very useful.

There are integrations for many popular text editors. For some of them,like vim, emacs, BBEdit and Visual Studio you can find support built-in.For instructions, read the appropriate section at:

For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and othereditors and IDEs you should be able to find ready-to-use plugins.

For this use case, consider using a secondary.clang-formatso that you can tweak a few options. Seeclangformatextra.

Missing support

clang-format is missing support for some things that are commonin kernel code. They are easy to remember, so if you use the toolregularly, you will quickly learn to avoid/ignore those.

In particular, some very common ones you will notice are:

  • Aligned blocks of one-line#defines, e.g.:

    #define TRACING_MAP_BITS_DEFAULT       11#define TRACING_MAP_BITS_MAX           17#define TRACING_MAP_BITS_MIN           7

    vs.:

    #define TRACING_MAP_BITS_DEFAULT 11#define TRACING_MAP_BITS_MAX 17#define TRACING_MAP_BITS_MIN 7

  • Aligned designated initializers, e.g.:

    static const struct file_operations uprobe_events_ops = {        .owner          = THIS_MODULE,        .open           = probes_open,        .read           = seq_read,        .llseek         = seq_lseek,        .release        = seq_release,        .write          = probes_write,};

    vs.:

    static const struct file_operations uprobe_events_ops = {        .owner = THIS_MODULE,        .open = probes_open,        .read = seq_read,        .llseek = seq_lseek,        .release = seq_release,        .write = probes_write,};

Extra features/options

Some features/style options are not enabled by default in the configurationfile in order to minimize the differences between the output and the currentcode. In other words, to make the difference as small as possible,which makes reviewing full-file style, as well diffs and patches as easyas possible.

In other cases (e.g. particular subsystems/folders/files), the kernel stylemight be different and enabling some of these options may approximatebetter the style there.

For instance:

  • Aligning assignments (AlignConsecutiveAssignments).

  • Aligning declarations (AlignConsecutiveDeclarations).

  • Reflowing text in comments (ReflowComments).

  • Sorting#includes (SortIncludes).

They are typically useful for block re-formatting, rather than full-file.You might want to create another.clang-format file and use that onefrom your editor/IDE instead.