1
0
Fork 0
alistair23-linux/Documentation/process
Miguel Ojeda d4ef8d3ff0 clang-format: add configuration file
clang-format is a tool to format C/C++/...  code according to a set of
rules and heuristics.  Like most tools, it is not perfect nor covers
every single case, but it is good enough to be helpful.

In particular, it is useful for quickly re-formatting blocks of code
automatically, for reviewing full files in order to spot coding style
mistakes, typos and possible improvements.  It is also handy for sorting
``#includes``, for aligning variables and macros, for reflowing text and
other similar tasks.  It also serves as a teaching tool/guide for
newcomers.

The tool itself has been already included in the repositories of popular
Linux distributions for a long time.  The rules in this file are
intended for clang-format >= 4, which is easily available in most
distributions.

This commit adds the configuration file that contains the rules that the
tool uses to know how to format the code according to the kernel coding
style.  This gives us several advantages:

  * clang-format works out of the box with reasonable defaults;
    avoiding that everyone has to re-do the configuration.

  * Everyone agrees (eventually) on what is the most useful default
    configuration for most of the kernel.

  * If it becomes commonplace among kernel developers, clang-format
    may feel compelled to support us better. They already recognize
    the Linux kernel and its style in their documentation and in one
    of the style sub-options.

Some of clang-format's features relevant for the kernel are:

  * Uses clang's tooling support behind the scenes to parse and rewrite
    the code. It is not based on ad-hoc regexps.

  * Supports reasonably well the Linux kernel coding style.

  * Fast enough to be used at the press of a key.

  * There are already integrations (either built-in or third-party)
    for many common editors used by kernel developers (e.g. vim,
    emacs, Sublime, Atom...) that allow you to format an entire file
    or, more usefully, just your selection.

  * Able to parse unified diffs -- you can, for instance, reformat
    only the lines changed by a git commit.

  * Able to reflow text comments as well.

  * Widely supported and used by hundreds of developers in highly
    complex projects and organizations (e.g. the LLVM project itself,
    Chromium, WebKit, Google, Mozilla...). Therefore, it will be
    supported for a long time.

See more information about the tool at:

    https://clang.llvm.org/docs/ClangFormat.html
    https://clang.llvm.org/docs/ClangFormatStyleOptions.html

Link: http://lkml.kernel.org/r/20180318171632.qfkemw3mwbcukth6@gmail.com
Signed-off-by: Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andy Whitcroft <apw@canonical.com>
Cc: Joe Perches <joe@perches.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2018-04-11 10:28:35 -07:00
..
1.Intro.rst Doc: Correct typo, "Introdution" => "Introduction" 2016-12-01 10:44:08 -07:00
2.Process.rst
3.Early-stage.rst Documentation/process: phrasofix 2017-09-26 14:53:51 -06:00
4.Coding.rst clang-format: add configuration file 2018-04-11 10:28:35 -07:00
5.Posting.rst Documentation/process: Co-developed-by instead of Co-Developed-by 2018-02-13 14:20:38 -07:00
6.Followthrough.rst
7.AdvancedTopics.rst
8.Conclusion.rst docs: fix locations of several documents that got moved 2016-10-24 08:12:35 -02:00
adding-syscalls.rst kernel/sys_ni: remove {sys_,sys_compat} from cond_syscall definitions 2018-04-02 20:16:20 +02:00
applying-patches.rst docs: process: drop git snapshots from applying-patches.rst 2017-08-30 15:25:30 -06:00
changes.rst Kbuild updates for v4.17 2018-04-03 15:51:22 -07:00
clang-format.rst clang-format: add configuration file 2018-04-11 10:28:35 -07:00
code-of-conflict.rst docs-rst: add documents to development-process 2016-10-24 08:12:35 -02:00
coding-style.rst clang-format: add configuration file 2018-04-11 10:28:35 -07:00
conf.py
development-process.rst
email-clients.rst doc: Document suitability of IBM Verse for kernel development 2017-06-22 10:22:41 -06:00
howto.rst Documentation/process/howto: Remove outdated info about bugzilla mailing lists 2018-02-18 16:49:25 -07:00
index.rst Documentation/process: kernel maintainer PGP guide 2018-02-01 10:58:19 -07:00
kernel-docs.rst Fix broken link in Documentation/process/kernel-docs.rst 2018-02-01 12:08:18 -07:00
kernel-driver-statement.rst documentation: add my name to kernel driver statement 2018-03-07 10:16:41 -07:00
kernel-enforcement-statement.rst Documentation updates for 4.16. New stuff includes refcount_t 2018-01-31 19:25:25 -08:00
license-rules.rst COPYING: create a new file with points to the Kernel license files 2018-03-23 12:41:35 -06:00
magic-number.rst Documentation: magic-numbers: Fix typo 2018-03-26 08:42:05 -06:00
maintainer-pgp-guide.rst Documentation/process: tweak pgp maintainer guide 2018-02-06 16:31:56 -07:00
management-style.rst docs: fix locations of several documents that got moved 2016-10-24 08:12:35 -02:00
stable-api-nonsense.rst docs-rst: add documents to development-process 2016-10-24 08:12:35 -02:00
stable-kernel-rules.rst Documentation: stable-kernel-rules: fix broken git urls 2017-08-24 13:39:47 -06:00
submit-checklist.rst docs: fix process/submit-checklist.rst Sphinx warning 2017-12-21 13:39:32 -07:00
submitting-drivers.rst Documentation: fix driver-api doc refs 2017-10-12 11:12:29 -06:00
submitting-patches.rst docs: add Co-Developed-by docs 2018-03-07 10:14:46 -07:00
volatile-considered-harmful.rst Documentation/atomic_ops.txt: convert to ReST markup 2016-11-30 17:40:52 -07:00