[PATCH v3 4/4] doc: Update U-Boot coding style guide with clang-format usage
Javier Tia
javier.tia at linaro.org
Fri Sep 5 22:53:47 CEST 2025
The U-Boot coding style guide has been updated to include information
about using the `.clang-format` configuration file for automatic code
formatting. This ensures consistent formatting across the entire
codebase and aligns with Linux kernel coding standards. The goal with
introducing a predefined coding style is consistency rather than
personal preference.
The .clang-format file is copied directly from the Linux kernel without
any modifications, ensuring complete compatibility with kernel coding
standards.
Include comprehensive best practices for using clang-format,
specifically guidance on formatting only changed blocks versus entire
files, creating separate formatting-only commits for better code review,
and leveraging git clang-format for targeted formatting. Add examples of
editor integrations. This enhancement will help maintainers and
contributors to easily adhere to U-Boot coding standards.
Signed-off-by: Javier Tia <javier.tia at linaro.org>
---
doc/develop/codingstyle.rst | 81 ++++++++++++++++++++++++++++++++++++-
1 file changed, 79 insertions(+), 2 deletions(-)
diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
index bc18b2ebb7b..10bfa747c6c 100644
--- a/doc/develop/codingstyle.rst
+++ b/doc/develop/codingstyle.rst
@@ -12,8 +12,9 @@ or only minimal changes.
The following rules apply:
* All contributions to U-Boot should conform to the `Linux kernel
- coding style <https://www.kernel.org/doc/html/latest/process/coding-style.html>`_
- and the `Lindent script <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/Lindent>`_.
+ coding style <https://www.kernel.org/doc/html/latest/process/coding-style.html>`_.
+ U-Boot includes a `.clang-format` configuration file that can be used to
+ automatically format code according to these standards.
* The exception for net files to the `multi-line comment
<https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting>`_
applies only to Linux, not to U-Boot. Only large hunks which are copied
@@ -23,6 +24,82 @@ The following rules apply:
<https://peps.python.org/pep-0008/>`_. Use `pylint
<https://github.com/pylint-dev/pylint>`_ for checking the code.
+Code Formatting with clang-format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+U-Boot provides a `.clang-format` configuration file that was copied directly
+from the Linux kernel without any modifications, ensuring complete compatibility
+with kernel coding standards. Here are common ways to use clang-format:
+
+**Basic usage for single files:**
+
+.. code-block:: bash
+
+ clang-format -style=file -i <file>
+
+**Format multiple files:**
+
+.. code-block:: bash
+
+ find . -name '*.c' -o -name '*.h' | xargs clang-format -style=file -i
+
+**Integration with git (format only staged changes):**
+
+.. code-block:: bash
+
+ git clang-format
+
+**Editor integration examples:**
+
+* **Vim/Neovim:** Install vim-clang-format plugin
+* **Emacs:** Use clang-format.el
+* **VSCode:** Install "Clang-Format" extension
+* **Most IDEs:** Have built-in or plugin support for clang-format
+
+The `.clang-format` file in the repository root ensures consistent formatting
+across the entire codebase and aligns with Linux kernel coding standards.
+
+**Disabling clang-format for specific code blocks:**
+
+In some cases, you may want to disable automatic formatting for specific code
+sections, such as carefully formatted tables, assembly code, or imported code
+from other projects. Use the following comments to control formatting:
+
+.. code-block:: c
+
+ // clang-format off
+ static const struct register_config regs[] = {
+ { 0x1000, 0x12345678 }, // Base address register
+ { 0x1004, 0xabcdef00 }, // Control register
+ { 0x1008, 0x00000001 }, // Status register
+ };
+ // clang-format on
+
+**Controversial aspects of coding style enforcement:**
+
+Coding style enforcement can be controversial, and it's difficult to have one
+configuration that satisfies everyone's personal preferences. The goal of using
+clang-format is consistency across the codebase rather than accommodating
+individual preferences. While some developers may disagree with specific
+formatting choices, maintaining a uniform style throughout the project makes
+code more readable and maintainable for the entire development community.
+
+**Best practices for formatting:**
+
+When using clang-format to format code, consider these best practices:
+
+* **Format only changed blocks:** It's preferred to format only the blocks of
+ code that have been modified rather than entire files. This keeps diffs
+ focused on actual changes and makes code reviews easier.
+
+* **Separate formatting commits:** If you need to format entire files, create
+ a separate commit containing only formatting changes. This allows reviewers
+ to easily distinguish between functional changes and pure formatting updates.
+
+* **Use git clang-format:** The ``git clang-format`` command is particularly
+ useful as it formats only the lines that have been modified in your current
+ changes, avoiding unnecessary formatting of unchanged code.
+
* Use patman to send your patches (``tools/patman/patman -H`` for full
instructions). With a few tags in your commits this will check your patches
and take care of emailing them.
--
2.51.0
More information about the U-Boot
mailing list