Waf branch - Tools [3/6]

[Amar Takhar]

This email explains the changes involved in making this work as well as the 
introduction of several tools that did not exist before.

There are two main components to this.  'RTEMS Config' and 'waf'.  The two are 
not connected.  RTEMS Config holds ALL configuration information for RTEMS.  It 
has absolutely nothing to do with the build system.

For instance, this is used to generate rtems-config.

verm at peach# ./rtems-config --list
List of Installed BSPs
~~~~~~~~~~~~~~~~~~~~~
sparc/sis         []

verm at peach# ./rtems-config --bsp sparc/sis --cflags
-I/mnt/devel/rtems/commit/include 
-I/mnt/devel/rtems/commit/build/sparc/sis/include 
-I/mnt/devel/rtems/commit/build/sparc/sis/include/rtems -DHAVE_CONFIG_H 
-D__rtems_sparc_sis__ -mcpu=cypress

verm at peach# ./rtems-config --bsp sparc/sis --libs  
-lrtemscpu -lrtemsbsp

verm at peach# ./rtems-config --bsp sparc/sis --ldflags
-specs /mnt/devel/rtems/commit/build/sparc/sis/gcc_spec 
-L/mnt/devel/rtems/commit/build/sparc/sis/cpukit/ 
-L/mnt/devel/rtems/commit/build/sparc/sis/c/ -Wl,-start-group -lrtemscpu 
-lrtemsbsp -lc -lgcc -Wl,-end-group


RTEMS can be used in-place or 'installed'.  A different rtems-config is 
generated in both instances.  You can also enable more than one BSP at a time 
using waf config.  I have had 100% of BSPS built with all tests in the same 
working directory with zero issues using rtems-config.  It's extremely robust.

Now, to configuration... The main way to configure rtems is using 'waf config'.  
This creates a config file called config.cfg.

The config is in Windows INI format.  Everyone knows the format, I did not 
want to make it a programming language or anything that is scriptable.

The config is automatically generated based on the BSPs you select.

All the python code is located in ./rtems_waf/ This is both the waf code and 
RTEMS Config.  This is in development and has been kept together for 
convenience.

A notable change from the old build system is *all* options are now global.  
This means you cannot have an option with the same name that has another 
meaning.  Yes, RTEMS currently has this.  We also have options that exist for 
the same purpose with 5 different names.  This happens over time with long 
projects such as RTEMS it is easy to forget what another did 10 years ago or 
what is going on in an architecture you never use.

If you look in the file rtems_waf/defaults/options.py you will see the master 
list of options.

The Options system is incomplete.  While it supports limits they are not 
implemented.  For instance if an option is an integer that has a value of 1-15 
then that is all the user can add.  We can also have list of integers, strings 
or longs -- anything we want.

A question I get often is "why does this need to be external? why not source?"

It's a great question and there are many reasons why.  There are enough that I'm 
sure I'll forget some in the list below:

1. It enforces values during the configure step with full documentation.  No 
   compiler required.
2. Documentation can be autogenerated for all options on a system/bsp basis.
3. Testing can be done on an option-level due to tracking of option 
   modification.
4. Users can be warned when an option is removed or changed.
   - RTEMS loves using #if ..  Which means if an option is renamed a user 
     may never know unless we 'poison' the old define.
5. Single-point configuration avoids duplication of similar options.  We will 
   have universal options that mean the same everywhere.
6. It allows for a full-featured, rich GUI configuration system.  Including full 
   integration with Eclipse in a 'preferences' pane taking advantage of the 
   hardwired limits.
7. Tests can be generated automatically using permutation of all options or 
   bounds checking.

I won't go any further because I can go on for at least another dozen or two.

FYI: Having limits in a library will let us have an impressive GUI configuration 
system.  We will be able to have spinners with limits -- full limitation within 
the GUI on a per-BSP and per-Arch basis.  This means if the GUI accepts it RTEMS 
*will* build.

There is another concept called 'features' that I won't get into here.  One 
feature is 'gcc' another is 'clang'.  Also 'debug'.  Some features won't combine 
with others eg gcc and clang.  Others can happily be defined at the same time.

There are three other tools that I will not get into within these emails as they 
both deserve their own focus:

rtems-cc
~~~~~~~~
This tool will allow for easy building of a test project for a BSP.  For 
example:

  # rtems-cc --bsp sparc/sis --compiler=clang file.c

The default compiler will be 'GCC'.  The result will be an image you can write 
to a board or launch in a simulator.

rtems-run
~~~~~~~~~
Allows for easily running your newly built image in the simulator or hardware of 
your choice.  RTEMS will be consuming this for running tests


rtems-test
~~~~~~~~~~
Run the test suite for a specific BSP and print a nice report.  It will also 
support testing subsets of RTEMS.  For example, networking or disk.


More emails to follow (4/6)


Amar.