From e3b10a02ca2fe1e27ee008e9fcd8cf7076f7f776 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Mon, 24 Jun 2024 11:53:09 -0700 Subject: Docs: Move clang-format from process/ to dev-tools/ 'clang-format' is on 'Other material' section of 'process/index', but it may fit more under 'dev-tools/' directory. Move it. Signed-off-by: SeongJae Park Acked-by: Miguel Ojeda Acked-by: Federico Vaga Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240624185312.94537-5-sj@kernel.org --- .clang-format | 2 +- Documentation/dev-tools/clang-format.rst | 184 +++++++++++++++++++++ Documentation/dev-tools/index.rst | 1 + Documentation/process/4.Coding.rst | 2 +- Documentation/process/clang-format.rst | 184 --------------------- Documentation/process/coding-style.rst | 2 +- Documentation/process/index.rst | 1 - .../translations/it_IT/process/clang-format.rst | 2 +- .../translations/sp_SP/process/coding-style.rst | 2 +- .../translations/zh_CN/process/4.Coding.rst | 2 +- .../translations/zh_CN/process/coding-style.rst | 2 +- .../translations/zh_TW/process/4.Coding.rst | 2 +- .../translations/zh_TW/process/coding-style.rst | 2 +- 13 files changed, 194 insertions(+), 194 deletions(-) create mode 100644 Documentation/dev-tools/clang-format.rst delete mode 100644 Documentation/process/clang-format.rst diff --git a/.clang-format b/.clang-format index ccc9b93972a9..252820d9c80a 100644 --- a/.clang-format +++ b/.clang-format @@ -4,7 +4,7 @@ # # For more information, see: # -# Documentation/process/clang-format.rst +# Documentation/dev-tools/clang-format.rst # https://clang.llvm.org/docs/ClangFormat.html # https://clang.llvm.org/docs/ClangFormatStyleOptions.html # diff --git a/Documentation/dev-tools/clang-format.rst b/Documentation/dev-tools/clang-format.rst new file mode 100644 index 000000000000..1d089a847c1b --- /dev/null +++ b/Documentation/dev-tools/clang-format.rst @@ -0,0 +1,184 @@ +.. _clangformat: + +clang-format +============ + +``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. + +``clang-format`` can be used for several purposes: + + - Quickly reformat a block of code to the kernel style. Specially useful + when moving code around and aligning/sorting. See clangformatreformat_. + + - Spot style mistakes, typos and possible improvements in files + you maintain, patches you review, diffs, etc. See clangformatreview_. + + - Help you follow the coding style rules, specially useful for those + new to kernel development or working at the same time in several + projects 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 kernel +coding style. They also try to follow :ref:`Documentation/process/coding-style.rst ` +as 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 particular +subsystem or folder. To do so, you can override the defaults by writing +another ``.clang-format`` file in a subfolder. + +The tool itself has already been included in the repositories of popular +Linux distributions for a long time. Search for ``clang-format`` in +your repositories. Otherwise, you can either download pre-built +LLVM/clang binaries or build the source code from: + + https://releases.llvm.org/download.html + +See more information about the tool at: + + https://clang.llvm.org/docs/ClangFormat.html + + https://clang.llvm.org/docs/ClangFormatStyleOptions.html + + +.. _clangformatreview: + +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/tweaking +the style options in the configuration file; as well as testing new +``clang-format`` features/versions. + +``clang-format`` also supports reading unified diffs, so you can review +patches and git diffs easily. See the documentation at: + + https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting + +To avoid ``clang-format`` formatting some portion of a file, you can do:: + + int formatted_code; + // clang-format off + void unformatted_code ; + // clang-format on + void formatted_code_again; + +While it might be tempting to use this to keep a file always in sync with +``clang-format``, specially if you are writing new files or if you are +a maintainer, please note that people might be running different +``clang-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 if ``clang-format`` becomes commonplace. + + +.. _clangformatreformat: + +Reformatting blocks of code +--------------------------- + +By using an integration with your text editor, you can reformat arbitrary +blocks (selections) of code with a single keystroke. This is specially +useful 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 cases +where 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: + + https://clang.llvm.org/docs/ClangFormat.html + +For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other +editors and IDEs you should be able to find ready-to-use plugins. + +For this use case, consider using a secondary ``.clang-format`` +so that you can tweak a few options. See clangformatextra_. + + +.. _clangformatmissing: + +Missing support +--------------- + +``clang-format`` is missing support for some things that are common +in kernel code. They are easy to remember, so if you use the tool +regularly, 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, + }; + + +.. _clangformatextra: + +Extra features/options +---------------------- + +Some features/style options are not enabled by default in the configuration +file in order to minimize the differences between the output and the current +code. In other words, to make the difference as small as possible, +which makes reviewing full-file style, as well diffs and patches as easy +as possible. + +In other cases (e.g. particular subsystems/folders/files), the kernel style +might be different and enabling some of these options may approximate +better 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 one +from your editor/IDE instead. diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index efa49cdc8e2e..a5f241cf0c02 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -16,6 +16,7 @@ Documentation/dev-tools/testing-overview.rst testing-overview checkpatch + clang-format coccinelle sparse kcov diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index c2046dec0c2f..80bcc1cabc23 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -63,7 +63,7 @@ these rules, to quickly re-format parts of your code automatically, and to review full files in order to spot coding style mistakes, typos and possible improvements. It is also handy for sorting ``#includes``, for aligning variables/macros, for reflowing text and other similar tasks. -See the file :ref:`Documentation/process/clang-format.rst ` +See the file :ref:`Documentation/dev-tools/clang-format.rst ` for more details. Some basic editor settings, such as indentation and line endings, will be diff --git a/Documentation/process/clang-format.rst b/Documentation/process/clang-format.rst deleted file mode 100644 index 1d089a847c1b..000000000000 --- a/Documentation/process/clang-format.rst +++ /dev/null @@ -1,184 +0,0 @@ -.. _clangformat: - -clang-format -============ - -``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. - -``clang-format`` can be used for several purposes: - - - Quickly reformat a block of code to the kernel style. Specially useful - when moving code around and aligning/sorting. See clangformatreformat_. - - - Spot style mistakes, typos and possible improvements in files - you maintain, patches you review, diffs, etc. See clangformatreview_. - - - Help you follow the coding style rules, specially useful for those - new to kernel development or working at the same time in several - projects 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 kernel -coding style. They also try to follow :ref:`Documentation/process/coding-style.rst ` -as 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 particular -subsystem or folder. To do so, you can override the defaults by writing -another ``.clang-format`` file in a subfolder. - -The tool itself has already been included in the repositories of popular -Linux distributions for a long time. Search for ``clang-format`` in -your repositories. Otherwise, you can either download pre-built -LLVM/clang binaries or build the source code from: - - https://releases.llvm.org/download.html - -See more information about the tool at: - - https://clang.llvm.org/docs/ClangFormat.html - - https://clang.llvm.org/docs/ClangFormatStyleOptions.html - - -.. _clangformatreview: - -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/tweaking -the style options in the configuration file; as well as testing new -``clang-format`` features/versions. - -``clang-format`` also supports reading unified diffs, so you can review -patches and git diffs easily. See the documentation at: - - https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting - -To avoid ``clang-format`` formatting some portion of a file, you can do:: - - int formatted_code; - // clang-format off - void unformatted_code ; - // clang-format on - void formatted_code_again; - -While it might be tempting to use this to keep a file always in sync with -``clang-format``, specially if you are writing new files or if you are -a maintainer, please note that people might be running different -``clang-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 if ``clang-format`` becomes commonplace. - - -.. _clangformatreformat: - -Reformatting blocks of code ---------------------------- - -By using an integration with your text editor, you can reformat arbitrary -blocks (selections) of code with a single keystroke. This is specially -useful 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 cases -where 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: - - https://clang.llvm.org/docs/ClangFormat.html - -For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other -editors and IDEs you should be able to find ready-to-use plugins. - -For this use case, consider using a secondary ``.clang-format`` -so that you can tweak a few options. See clangformatextra_. - - -.. _clangformatmissing: - -Missing support ---------------- - -``clang-format`` is missing support for some things that are common -in kernel code. They are easy to remember, so if you use the tool -regularly, 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, - }; - - -.. _clangformatextra: - -Extra features/options ----------------------- - -Some features/style options are not enabled by default in the configuration -file in order to minimize the differences between the output and the current -code. In other words, to make the difference as small as possible, -which makes reviewing full-file style, as well diffs and patches as easy -as possible. - -In other cases (e.g. particular subsystems/folders/files), the kernel style -might be different and enabling some of these options may approximate -better 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 one -from your editor/IDE instead. diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 7e768c65aa92..04f6aa377a5d 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -732,7 +732,7 @@ these rules, to quickly re-format parts of your code automatically, and to review full files in order to spot coding style mistakes, typos and possible improvements. It is also handy for sorting ``#includes``, for aligning variables/macros, for reflowing text and other similar tasks. -See the file :ref:`Documentation/process/clang-format.rst ` +See the file :ref:`Documentation/dev-tools/clang-format.rst ` for more details. Some basic editor settings, such as indentation and line endings, will be diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index fb089bf9d6a8..1827e73f6376 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -113,7 +113,6 @@ lack of a better place. .. toctree:: :maxdepth: 1 - clang-format .. only:: subproject and html diff --git a/Documentation/translations/it_IT/process/clang-format.rst b/Documentation/translations/it_IT/process/clang-format.rst index 29f83c198025..6fab07772da0 100644 --- a/Documentation/translations/it_IT/process/clang-format.rst +++ b/Documentation/translations/it_IT/process/clang-format.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-ita.rst -:Original: :ref:`Documentation/process/clang-format.rst ` +:Original: :ref:`Documentation/dev-tools/clang-format.rst ` :Translator: Federico Vaga .. _it_clangformat: diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst index b5a84df44cea..025223be9706 100644 --- a/Documentation/translations/sp_SP/process/coding-style.rst +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -754,7 +754,7 @@ código automáticamente, y revisar archivos completos para detectar errores de estilo del código, errores tipográficos y posibles mejoras. También es útil para ordenar ``#includes``, para alinear variables/macros, para redistribuir texto y otras tareas similares. Vea el archivo -:ref:`Documentation/process/clang-format.rst ` para más +:ref:`Documentation/dev-tools/clang-format.rst ` para más detalles. 10) Archivos de configuración de Kconfig diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst index 7cac9424f5d5..4cc35d410dbc 100644 --- a/Documentation/translations/zh_CN/process/4.Coding.rst +++ b/Documentation/translations/zh_CN/process/4.Coding.rst @@ -54,7 +54,7 @@ 注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式 化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还 可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细 -信息，请参阅文档 :ref:`Documentation/process/clang-format.rst ` +信息，请参阅文档 :ref:`Documentation/dev-tools/clang-format.rst ` 抽象层 ****** diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 3bc2810b151d..10b9cb4f6a65 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -654,7 +654,7 @@ Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 请注意，您还可以使用 ``clang-format`` 工具帮助您处理这些规则，快速自动重新格 式化部分代码，并审阅整个文件以发现代码风格错误、打字错误和可能的改进。它还可 以方便地排序 ``#include`` ，对齐变量/宏，重排文本和其他类似任务。 -详见 Documentation/process/clang-format.rst 。 +详见 Documentation/dev-tools/clang-format.rst 。 10) Kconfig 配置文件 diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst index bdd2abe4daf4..e90a6b51fb98 100644 --- a/Documentation/translations/zh_TW/process/4.Coding.rst +++ b/Documentation/translations/zh_TW/process/4.Coding.rst @@ -57,7 +57,7 @@ 注意您還可以使用 ``clang-format`` 工具來幫助您處理這些規則，快速自動重新格式 化部分代碼，和審閱完整的文件以發現代碼樣式錯誤、拼寫錯誤和可能的改進。它還 可以方便地排序 ``#includes`` 、對齊變量/宏、重排文本和其他類似任務。有關詳細 -信息，請參閱文檔 :ref:`Documentation/process/clang-format.rst ` +信息，請參閱文檔 :ref:`Documentation/dev-tools/clang-format.rst ` 抽象層 ****** diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index c7ac504f6f40..311c6f6bad0b 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -657,7 +657,7 @@ Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 請注意，您還可以使用 ``clang-format`` 工具幫助您處理這些規則，快速自動重新格 式化部分代碼，並審閱整個文件以發現代碼風格錯誤、打字錯誤和可能的改進。它還可 以方便地排序 ``#include`` ，對齊變量/宏，重排文本和其他類似任務。 -詳見 Documentation/process/clang-format.rst 。 +詳見 Documentation/dev-tools/clang-format.rst 。 10) Kconfig 配置文件 -- cgit