[PATCH] doc/develop/codingstyle.rst: Clarify include section

[Heinrich Schuchardt]

On 12.02.24 17:19, Tom Rini wrote:
> On Sun, Feb 11, 2024 at 06:53:47PM +0100, Igor Opaniuk wrote:
>> Hi Tom,
>>
>> On Fri, Feb 9, 2024 at 3:52 PM Tom Rini <trini at konsulko.com> wrote:
>>>
>>> Rework the section about includes slightly. We should not be using
>>> common.h anywhere, so remove that from examples and ask people to send
>>> patches removing it when found. Doing this also means we need to reword
>>> other parts of this section. Be clearer about using alphabetical
>>> ordering.
>>>
>>> Signed-off-by: Tom Rini <trini at konsulko.com>
>>> ---
>>>   doc/develop/codingstyle.rst | 23 +++++++++++------------
>>>   1 file changed, 11 insertions(+), 12 deletions(-)
>>>
>>> diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
>>> index b25bfbd271f0..cdf5aedfcbb0 100644
>>> --- a/doc/develop/codingstyle.rst
>>> +++ b/doc/develop/codingstyle.rst
>>> @@ -108,30 +108,29 @@ expected size, or that particular members appear at the right offset.
>>>   Include files
>>>   -------------
>>>
>>> -You should follow this ordering in U-Boot. The common.h header (which is going
>>> -away at some point) should always be first, followed by other headers in order,
>>> -then headers with directories, then local files:
>>> +You should follow this ordering in U-Boot. In all cases, they should be listed
>>> +in alphabetical order. First comes headers which are located directly in our
>>> +top-level include diretory. This excludes the common.h header file which is to
>>> +be removed. Second are headers within subdirectories, Finally directory-local
>>> +includes should be listed. See this example:
>>>
>>>   .. code-block:: C
>>>
>>> -   #include <common.h>
>>>      #include <bootstage.h>
>>>      #include <dm.h>
>>>      #include <others.h>
>>>      #include <asm/...>
>>> -   #include <arm/arch/...>
>>> +   #include <asm/arch/...>
>>>      #include <dm/device_compat.h>
>>>      #include <linux/...>
>>>      #include "local.h"
>>>
>>> -Within that order, sort your includes.
>>> -
>>> -It is important to include common.h first since it provides basic features used
>>> -by most files, e.g. CONFIG options.
>>> -
>>>   For files that need to be compiled for the host (e.g. tools), you need to use
>>> -``#ifndef USE_HOSTCC`` to avoid including common.h since it includes a lot of
>>> -internal U-Boot things. See common/image.c for an example.
>>> +``#ifndef USE_HOSTCC`` to avoid including U-Boot specific include files.  See
>>> +common/image.c for an example.
>>> +
>>> +If you encounter ccode which still uses <common.h> a patch to remove that and
>> nitpick: s/ccode/code/g
>
> Whoops, Heinrich can you please fix when applying?
>

Hello Tom,

I am missing here some text about the includes that are automatically
included, e.g.

linux/kconfig.h
include/generated/autoconf.h

Maybe you could describe this in a future patch.

We still have 4107 files including common.h. Should we have a Migration
warning in Makefile?

Best regards

Heinrich