From: Javier Tia Date: Fri, 5 Sep 2025 20:53:47 +0000 (-0600) Subject: doc: Update U-Boot coding style guide with clang-format usage X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a9d997685a400e1a08d60056177aefcd159bc2af;p=thirdparty%2Fu-boot.git doc: Update U-Boot coding style guide with clang-format usage 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 --- 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 `_ - and the `Lindent script `_. + coding style `_. + 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 `_ applies only to Linux, not to U-Boot. Only large hunks which are copied @@ -23,6 +24,82 @@ The following rules apply: `_. Use `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 + +**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.