+/** \defgroup GRAS_API GRAS
+ \ingroup SimGrid_API
+ \brief Realistic programming environment (Grid Reality And Simulation)
+
+ GRAS provide a complete API to implement distributed application on top
+ of heterogeneous plateforms. In addition to the SimGrid implementation
+ of this interface (allowing you to work on your application within the
+ comfort of the simulator), an implementation suited to real platforms is
+ also provided (allowing you to really use your application once you're
+ done with developing it).
+
+ GRAS thus constitute a complete grid application developement framework,
+ encompassing both developer helping tools (the simulator and associated
+ tools) and an efficient while portable execution runtime.
+
+ \section GRAS_who Who should use this (and who shouldn't)
+
+ You should use this programming environment if you want to develop real
+ applications, ie if the final result of your work is a program which
+ may eventually be distributed.
+ If you just want to study some heuristics for a given problem you don't
+ want to implement really (ie, if your result would be a theorem), have a
+ look at the \ref MSG_API one.
+ If you want to study an existing MPI program, have a look at the
+ \ref SMPI_API one.
+ If none of those programming environments fits your needs, you may
+ consider implementing your own directly on top of \ref SURF_API (but you
+ probably want to contact us before).
+
+ \section GRAS_funct Offered functionnalities
+ - <b>Communication facilities</b>: Exchanging messages between peers
+ - \ref GRAS_dd: any data which may transit on the network must be
+ described beforehand so that GRAS can handle the platform
+ heterogeneity and convert them if needed.
+ - \ref GRAS_sock: this is how to open a communication channel to
+ other processes, and retrive information about them.
+ - \ref GRAS_msg: communications are message oriented. You have to
+ describe all possible messages and their payload beforehand, and
+ can then attach callbacks to the arrival of a given kind of message.
+ - <b>Virtualization</b>: Running both on top of the simulator and on
+ top of real platforms, and portability support.
+ - \ref GRAS_globals: The use of globals is forbidden since the
+ "processes" are threads in simulation mode. \n
+ This is how to let GRAS handle your globals properly.
+ - \ref GRAS_cond: How to declare specific code for the simulation mode
+ or for the real mode.
+ - \ref GRAS_virtu: You naturally don't want to call the
+ gettimeofday(2) function in simulation mode since it would give
+ you the time on the host running the simulation, not the time in
+ the simulated world (you are belonging to).\n
+ This a system call virtualization layer, which also acts as a
+ portability layer.
+
+ \section GRAS_todo TODO
+ Documentation related:
+ - Add an example to the \ref GRAS_msg section, at least
+ - Document examples/gras/gras_stub_generator utility and how to deal
+ with the fact that programs must have a main in RL and not in SG.
+ - Document example/gras/ping as it uses almost all of the GRAS
+ features.
+
+ Code related: too long to be written here. See the TODO file
+
+ @{
+*/