New source layout.

Tue Mar 10 10:03:38 UTC 2015

Hello Amar and others,

I would like to express my weak objection to moving
all includes to single directory. This makes sources
much less modular is (according to me) backward move.

Linux kernel used that setup

 /include
 /include/linux
 /include/x86/asm
 ...

and it took developers may it be year to separate
includes to be placed along files they bolong to

├── arch
│   ├── arm
│   │   ├── boot
│   │   ├── common
│   │   ├── configs
│   │   ├── crypto
│   │   ├── firmware
│   │   ├── include
│   │   ├── kernel
│   │   ├── kvm
│   │   ├── lib
│   │   ├── mach-asm9260
│   │   ├── mach-at91
│   │   ├── mach-axxia
│   │   ├── mach-bcm

│   ├── x86
│   │   ├── boot
│   │   ├── configs
│   │   ├── crypto
│   │   ├── ia32
│   │   ├── include

├── include
│   ├── acpi
│   ├── asm-generic
│   │   ├── atomic.h

│   ├── linux

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.

I think that doing move which is against modularity due to problem
in build tool is not right decision.

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

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.

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.

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)

  http://rtime.felk.cvut.cz/omk/
  http://rtime.felk.cvut.cz/omk/omk-manual.html
  http://rtime.felk.cvut.cz/omk/omk-manual.html#Original-README

There is list of features which we want to solve with our make system:

 - Central Makefile.rules for most of components of a bigger project.

    FIXME (our CAN framework includes more libraries common with our
    other projects, we need to separate some utility libraries etc.)

 - The rules in more spread Makefiles are way to the hell (update for
    different kernel, RT-Linux etc would be nightmare in other case).

 - Make system should allow to freely move cross-dependant components
   in directory structure without need to update users of moved component
   (I hate something like -I../../sched/rtlshwq/include in CAN makefiles
   for example. If a component is renamed or version is added to then name,
   all Makefiles in CAN will require update).

 - Make system should be able to compile mutually cross-dependant
   libraries and should ensure, that change in one component sources
   or headers would result in relink or rebuild in components linked
   against that library or including modified header file.

 - Make system has to enable compilation out of OCERA full source tree
   (we would lost many users of particular components in other case).
   Compile should be able to do all above work without need to install
   any files before successful finish of build.

 - Because we use some libraries for RT-Linux build and user-space build,
   we need to solve how to compile from same sources to both targets.

 - The build system should allow to call make for particular source
   subdirectory. Time of recursive make through all subdirectories
   is unacceptable.

 - Make system should enable to build out of sources tree (else clean
   or working with CVS sandbox gets fussy and simultaneous multiple
   targets gets problematic).

 - It would be good, if there is a possibility to call make
   from read-only media sources. Make system should store results
   of build in some separate directory structure to simple install
   and testing. Makefiles in sources directories should be simple.

The example how to use it for RTEMS applications is there

http://rtime.felk.cvut.cz/gitweb/rtems-devel.git/tree/HEAD:/rtems-omk-template

  git clone git://rtime.felk.cvut.cz/rtems-devel.git
  cd rtems-devel/rtems-omk-template/
  echo >config.target \
     RTEMS_MAKEFILE_PATH=/opt/rtems4.11/arm-rtems4.11/lpc17xx_ea_ram 
  make

Libraries tracking is not fully functional for RTEMS version in the currenrt
OMK devel for some reason but rest works well.

I would be happy if you try to check again what is an optimal solution.

On the other hand I would be very happy if directory structure
of RTEMS is updated. Historical (ADA days based) hierarchy
 c/src/lib/libbsp, c/src/lib/libcpu for subtrees which belongs
to arch is quite confusing for new users/students from my experience.

Best wishes,

                Pavel

On Sunday 08 of March 2015 02:51:40 Amar Takhar wrote:
> I just noticed the layout I gave above was wrong!  Gedare sent me an
> email (he could not email the list directly from his device).  I had a typo
> in the original one and also didn't copy the new one I made.  Sigh.  I have
> reordered and fixed it below with some examples:
>
> The directories should be:
>
> include/rtems/       - Public API
> include/             - Private API
> include/arch/        - Private architecture specific
> include/bsp/         - Common BSP files
> include/bsp/<arch>   - Architecture specific
>
> This allows for:
>
> #include <rtems/header.h>    - Public API
> #include <header.h>          - Private API
> #include <arch/header.h>     - Private architecture specific
> #include <bsp/header.h>      - Common BSP file
> #include <bsp/arch/header.h> - BSP architecture specific
>
> Where 'arch' is replaceable by any architecture.
>
> RTEMS has 1,500 headers we will have no issues filling these directories
> up. There are 3,258 headers in the waf build.  1,700 of these will be
> removed after we fix the references in the source -- a project for down the
> road.
>
>
> Amar.
>
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel