New source layout.

Tue Mar 10 23:36:14 UTC 2015

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.

> > Linux directs INCLUDE_PATH to its common include and per arch include
> > directories + directory for generated files
> >
> > Linux make GCC call for build of kernel out of sources tree
> >
> > make -f /home/pi/projects/rpi/linux/scripts/Makefile.build obj=fs/aufs
> >
> > arm-rpi-linux-gnueabihf-gcc -Wp,-MD,fs/aufs/.cpup.o.d  -nostdinc \
> >   -isystem
> > /usr/arm-rpi-linux-gnueabihf/gcc/4.9.1/bin/../lib/gcc/arm-rpi-linux-gnuea
> >bihf/4.9.1/include -I/home/pi/projects/rpi/linux/arch/arm/include \
> >   -Iarch/arm/include/generated \
> >   -I/home/pi/projects/rpi/linux/include -Iinclude \
> >   -I/home/pi/projects/rpi/linux/arch/arm/include/uapi \
> >   -Iarch/arm/include/generated/uapi \
> >   -I/home/pi/projects/rpi/linux/include/uapi \
> >   -Iinclude/generated/uapi \
> >   -include /home/pi/projects/rpi/linux/include/linux/kconfig.h  \
> >   -I/home/pi/projects/rpi/linux/fs/aufs \
> >   -Ifs/aufs -D__KERNEL__ -mlittle-endian  \
> >   -I/home/pi/projects/rpi/linux/arch/arm/mach-bcm2708/include \
> >   ...
> >   ...
> >   -r -o fs/aufs/aufs.o fs/aufs/module.o fs/aufs/sbinfo.
>
> This is the exact situation we are trying to avoid.  It makes source far
> header to read.  You can also be easily tripped up by having an incorrect
> order of -I switches this is frail.
>
> For example RTEMS has a pthread.h.  In the old build system this was
> included as:
>
>   #include <pthread.h>
>
> When building with waf this gave me many errors because it was picking up
> the compiler <pthread.h>  Why?  Because I 'forgot' an include line
> (-Irtems/posix/).
>
> In waf, this line is now:
>
>   #include <rtems/posix/pthread.h>
>
> This offers resiliency on tripping yourself up with commandlines and it
> also tells you where this file is coming from.  #include <pthread.h> tells
> you absolutely nothing about this.  On my system I've got 3 possible
> pthread.h to include.  My system (FreeBSD), the sparc compiler *and* RTEMS.
>  Which one is it?

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.

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

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>

> > So for architectures it is my preference to separate includes
> > it helps to grep for corresponding function definition
> > and declaration and keep them in sync for single arch for example.
> > The functions repeats for each arch and if you grep whole tree
> > you are lost if you work on single architecture.
>
> OK.
>
> > I even prefer to place exported header files near to implementation
> > in the case of libraries because it makes system modular (i.e. if you
> > have two implementations for given purpose - small/big, old/new) then
> > single enable/disable of one of the libraries flavor directory
> > ensures consistent build. On the other hand I agree that headers
> > copying has some problems. On sensible systems it can be replaced
> > by symlinking and then works great.
>
> This does not solve the problem of fragility.  We tripped up in one BSP. 
> We had two headers:
>
>   HEADER.h
>   header.h
>
> 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.

> 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.

> The proposal I'm making will eliminate 100% of these issues and increase
> visibility when looking at the source file due to absolute includes.
>
> > I have declared some demands on build system when we have been
> > in integration phase of OCERA project many years ago and then
> > implemented our OMK system based on these rules. Even that we use
> > this system for allmost all of our code (Linux apps+driver, RTEMS,
> > bare metal, Windows etc), it is dated now and has some significant
> > drawbacks, multiple passes etc. But I hope that an requirements
> > analysis worth to be read. Keep in mid, that analysis is dated
> > (about 2003) on the other hand (i.e CVS -> GIT etc)
>
> <snip>
>
> We use waf as our make system now all the above requirements are very
> trivial to support.  The waf branch is public which you can see in a
> previous posting to this list.  If there is something not supported that
> you require please let me know.

> Yes it's confusing which is why I wanted to take this opportunity to move
> it with the introduction to the waf build.
>
> Please give it a try the beginning of the thread is here:
>
>   https://lists.rtems.org/pipermail/devel/2015-February/009837.html
>
> The header move I'm proposing has already been done in this repository. 
> The source layout has not changed.

I will look at it but cannot promise when.

> 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.

> 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.

> 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.

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

Thanks for your work,

                      Pavel