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

[Igor Opaniuk]

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
> +replace it with any required include files directly is much appreciated.
>
>  If your file uses driver model, include <dm.h> in the C file. Do not include
>  dm.h in a header file. Try to use forward declarations (e.g. ``struct
> --
> 2.34.1
>

Reviewed-by: Igor Opaniuk <igor.opaniuk at gmail.com>

-- 
Best regards - Atentamente - Meilleures salutations

Igor Opaniuk

mailto: igor.opaniuk at gmail.com
skype: igor.opanyuk
http://ua.linkedin.com/in/iopaniuk