New source layout.

[Amar Takhar]

On 2015-03-11 00:36 +0100, Pavel Pisa wrote:
> Hello Amar,
> 
> thanks for reply.
> 
> On Tuesday 10 of March 2015 19:00:03 Amar Takhar wrote:
> > On 2015-03-10 11:03 +0100, Pavel Pisa wrote:
> > > I think that includes really belong near to the implementation and that
> > > new architecture could be (in optimal case) introduced by adding single
> > > directory in "arch" subtree.
> >
> > The includes are near the implementation when they're local headers. 
> > Anything that is consumable by another part of RTEMS is moved.
> 
> OK, if you think about it from perspective of public API it has
> sense. But it is at some flexibility lost price. May it be it worth
> to be paid.

That's all relative and depends on what your definition of flexibility is.  I 
believe the method you are proposing is *less* flexible -- that is my opinion 
though.

We all have different workflows.  What we're trying to do is to have a layout 
that makes RTEMS easy to test and helps us keep our interface(s) clean 
design-wise by easily having an overview of what we're doing.


> The native system one should be strictly avoided, Linux kernel
> uses -nostdinc. Required cross-GCC headers and newlib can be reintroduced
> by adding explicitly directories reported by GCC as right multiarch and base
> includes.

We have an entirely different scenario from the Linux kernel:

 * Multiple compilers
 * Multiple platforms

The waf build system supports any compiler it has been 100% unhooked from GCC.  
Once a BSP compilers CLang can be dropped in and used to build some BSPs.

This solution also removes the possibility of RTEMS compiling under several 
compilers native to Windows.


> As for the mismatch/collision between same name of includes, the right
> solution is to put actual headers into right subdirectory even if
> path leads into multiple directories. This is solution, which Linux
> uses, i.e. there are no headers placed directly in include base directory
> bu only in subdirectories
> 
>   arch/arm/include/asm
>   include/asm
>   include/linux

This is being done already in the include/ directory there will be no 'base' 
headers that simply live in 'include/'.  All public headers will be under rtems/


> etc. to not clash (+/-) even with system ones. It is little more
> complicated in the fact, because these includes which are necessary
> to be used as system interface (are included in libc after some time)
> are placed under include/uapi, arch/arm/include/uapi but again not
> directly but into subdirs
> 
>   include/uapi/asm
>   include/uapi/linux
> 
> The other include bases 
> 
>  arch/arm/include/generated
>  include/generated/uapi
>  arch/arm/include/generated/uapi 
>   
> are there to not polute source tree by generated files.
> And again, there is minimum files directly in these bases
> directories. Actual files are in
> 
>   include/generated/uapi/linux
>   arch/arm/include/generated/asm
>   arch/arm/include/generated/uapi/asm
> 
> so the #include has to specify these with path, i.e. for
> 
>   include/generated/uapi/linux/version.h
> 
>   #include <linux/version.h>

The key difference between what is being done above and what I'm proposing is 
there is only one include on the compiler, ever -I/path/to/include and nothing 
more.  This is for *both* public API linkage and internal to RTEMS.  Software 
that links different whether it's building itself or being linked against is 
confusing.


> > These were included in two different BSPs.  The 'preinclude' step copied
> > these to the same location -- the contents were different!
> 
> Yes, collision is a problem, may it be some tool which receives
> list of include search paths and then builds list of files (with subdirs)
> and checks lists for duplicates and prints error during build would be nice
> feature. On the other hand there are some legitimate duplicates
> in C-library and GCC support which use include next mechanism.

This layout negates the requirement for any tool it also negates any issues with 
file case.  No tools or special considerations required.


> > What's more, this solution could have never worked on Windows or OS X as it
> > was case insensitive.  This bug had been in the repo over 7 years.  Copying
> > and symlinking open you up to transparent issues such as this.  RTEMS has
> > over 1,600 headers.
> 
> Yeas I agree that copying is a problem. If it is not symlink then
> you can end quite easily by editting copy which gets replaced in next
> build.

Symlinks won't work on Windows.


> I will look at it but cannot promise when.

OK.


> > Another benefit of having them all in the same place is it is far easier to
> > see what is going on when working on RTEMS.  The preinclude step hides far
> > too much, so do multiple -I lines.
> 
> Yes, removing automake and preinclude for RTEMS is usesfull goal.
> Automake does not play nice in RTEMS case, it takes horrible time
> to bootsrap tree. Much longer then actual build in my case.

Please see this page:

  https://devel.rtems.org/wiki/waf/Timing

>From 'git co' you can have RTEMS built in 12 seconds *including* all tests.  On 
the average machine it takes ~25s including all tests.  This is not an 
exaggeration please try it for yourself.


> > Having it all laid out in this way will 
> > help us make sound choices in the future for how we want interfaces to
> > work.  RTEMS is huge it's easy to forget to look at Doxygen the wiki or
> > source files themselves. When it's scattered all over the place the 'global
> > picture' is hidden from you.
> 
> On the other hand if you need to lookup header file or worse all
> related files in common include directory when you change some
> library implementation and you need to adjust some related inline
> then it is not perfect either. But I agree that movement are evil
> and Linux limits shared headers distribution to two places
> (arch/include and main include directory) as well.

We are planning to make all RTEMS source Doxygen clean this will help greatly in 
finding source.  I will also be adding LXR (http://lxr.linux.no/) support which 
will go a long way.

Our test suite will insulate us from making changes in this way.  I agree that 
it is a pain but the benefits of doing it this way are huge especially for RTEMS 
which is simply too complex to easily keep track of 1,600 headers.


> > The Linux kernel source has different requirements from us.
> > While their method may work for them it is not ideal for RTEMS.
> 
> Linux kernel headers and the mechanism of propagation
> of their public part to GLIBC distributions has evolved
> and revolved (changed) more times and actual state is result
> of many people thinking hard about the problem.
> And I see the situation and needs as very similar to RTEMS
> ones.

They may be similar but not under the same condition.  Linux relies on plenty of 
GCC hacks we cannot use to make things easier.


> Generally I agree with you that copying is evil and
> it is not possible to have include list containing
> each library directory.

Right now RTEMS is being limited by its size and complexity.  Doing this will 
reduce it greatly on both fronts.

In the end this layout is about making it easier to manage and easier to test.  
We can create workarounds for the rest especially when it comes to workflow 
however there is never a workaround for making software easily testable and 
maintaining a firm overview of what is going on.


> Thanks for your work,

No problem and thank you for your fantastic input it is always helpful to hear 
the opinions of others.

Thank you!


Amar.