[U-Boot] [RFC] Proposal to change include search model

[U-Boot] [RFC] Proposal to change include search model

[Vasili Galka]

Hi,

Currently U-Boot has a long list of include search paths. This makes
it hard to understand the location of each header. Moreover, it opens
an easy opportunity for breaking build by including the wrong header.
This is especially easy when compiling the tools directory. I found
numerous commits dealing with such problems over the years.

What I propose is changing the way of how #include directives are
written. For example instead of:

#include <stdlib.h>             /* From toolchain */
#include <api_public.h>         /* include/api_public.h */
#include <linux/mii.h>          /* include/linux/mii.h */
#include <config.h>             /* Auto-generated somewhere */
#include <bmp_logo.h>           /* Auto-generated somewhere */
#include <asm/arcregs.h>        /* arch/arc/include/asm/arcregs.h */
#include <asm/arch/emac_defs.h> /* arch/arm/include/asm/
                                     arch-davinci/emac_defs.h */
#include "../../../../../drivers/net/davinci_emac.h"

and let the developer guess the locations... I propose writing:

#include <stdlib.h>             /* <> means from toolchain */
#include "inc/api_public.h"     /* From u-boot/include/ dir */
#include "inc/linux/mii.h"
#include "config/config.h"      /* From dedicated config dir */
#include "generated/bmp_logo.h"
#include "arch/asm/arcregs.h"   /* From configured architecture */
#include "soc/emac_defs.h"      /* From configured SoC */
#include "u-boot/drivers/net/davinci_emac.h"

This way the developer will instantly know the exact header locations.
Moreover, the chance for ambiguities is very small which makes build
breakages less likely.

The proposal may seem strange to you at first, as most of you are
probably used to a different approach. But please consider its
advantages. I've been working on projects that used similar scheme
and it significantly simplifies the developer life.

The above can be implemented by creating
inc/ arch/ soc/ u-boot/
filesystem links in ${objtree}/include. Then, the only compiler flag
required will be "-iquote ${objtree}/include". No ugly -idirafter flags,
no long search list. Keep it simple.

I'll be glad for your opinions!

P.S. I've already mentioned this proposal when discussing Cygwin/FreeBSD
build breakages. But it deserves a separate thread.

Best,
Vasili

[U-Boot] [RFC] Proposal to change include search model

[Jeroen Hofstee]

On di, 2014-06-10 at 18:53 +0300, Vasili Galka wrote:
> Hi,
> 
> Currently U-Boot has a long list of include search paths. This makes
> it hard to understand the location of each header. Moreover, it opens
> an easy opportunity for breaking build by including the wrong header.
> This is especially easy when compiling the tools directory. I found
> numerous commits dealing with such problems over the years.
> 
> What I propose is changing the way of how #include directives are
> written. For example instead of:
> 
> #include <stdlib.h>             /* From toolchain */
> #include <api_public.h>         /* include/api_public.h */
> #include <linux/mii.h>          /* include/linux/mii.h */
> #include <config.h>             /* Auto-generated somewhere */
> #include <bmp_logo.h>           /* Auto-generated somewhere */
> #include <asm/arcregs.h>        /* arch/arc/include/asm/arcregs.h */
> #include <asm/arch/emac_defs.h> /* arch/arm/include/asm/
>                                      arch-davinci/emac_defs.h */
> #include "../../../../../drivers/net/davinci_emac.h"
> 
> and let the developer guess the locations... I propose writing:
> 
> #include <stdlib.h>             /* <> means from toolchain */
> #include "inc/api_public.h"     /* From u-boot/include/ dir */
> #include "inc/linux/mii.h"
> #include "config/config.h"      /* From dedicated config dir */
> #include "generated/bmp_logo.h"
> #include "arch/asm/arcregs.h"   /* From configured architecture */
> #include "soc/emac_defs.h"      /* From configured SoC */
> #include "u-boot/drivers/net/davinci_emac.h"
> 
> This way the developer will instantly know the exact header locations.
> Moreover, the chance for ambiguities is very small which makes build
> breakages less likely.
> 
> The proposal may seem strange to you at first, as most of you are
> probably used to a different approach. But please consider its
> advantages. I've been working on projects that used similar scheme
> and it significantly simplifies the developer life.
> 
> The above can be implemented by creating
> inc/ arch/ soc/ u-boot/
> filesystem links in ${objtree}/include. Then, the only compiler flag
> required will be "-iquote ${objtree}/include". No ugly -idirafter flags,
> no long search list. Keep it simple.
> 
> I'll be glad for your opinions!
> 
This sounds way too complex if you ask me for what your are trying to
fix. For one thing #include<> versus include "" is compiler specific and
not defined in general. If I find some time I will see if I can find
another solution for it. But you're warned heads up that it might
include one additional -I for standard c libraries for the target (which
is only errno.h at the moment, afaik) ;)

Regards,
Jeroen

[U-Boot] [RFC] Proposal to change include search model

[Vasili Galka]

Hi Jeroen,

On Tue, Jun 10, 2014 at 11:40 PM, Jeroen Hofstee <dasuboot@myspectrum.nl>
wrote:
> This sounds way too complex if you ask me for what your are trying to
> fix. For one thing #include<> versus include "" is compiler specific and
> not defined in general. If I find some time I will see if I can find
> another solution for it. But you're warned heads up that it might
> include one additional -I for standard c libraries for the target (which
> is only errno.h at the moment, afaik) ;)

1. What do you mean by "complex"? Do you think this change will make the
life of the developers more difficult? Or do you mean the amount of work
required to implement this proposal? If the later, I tried it and already
have an almost working version.

2. Regarding <> versus "" - it's a very good point. Although I doubt that
someone builds U-Boot on a different compiler than gcc (maybe clang - which
claims to be compatible). So I don't see a reason to strictly stick to
the C standard. Besides, all compilers I see behave the same on this point.
But in any case, you can see the rule <> vs "" just as an emphasis for
readability.
If this poses a problem with a different compiler in the future (which I
strongly doubt), the -iquote can be replaced by -I and everything shall
continue to build. Because the key idea here is that most of the headers
are specified with path prefixes (u-boot/ inc/ arch/ soc/) which prevents
possible clash with headers provided by environment.

3. When I think about it, maybe it's a good idea to simplify further and
use "u-boot/include/xxx.h" form instead of "inc/xxx.h". A little more
lengthy but much more explicit. One less link to create.

4. Regarding the standard C libraries, I don't really understand why
   -nostdinc -isystem $(shell $(CC) -print-file-name=include)
is used at all. How does it differ from the standard paths that are
searched if these flags are dropped?

Many thanks for the feedback!

Best regards,
Vasili