README.coding

   1 **
   2 ** Source tree organization
   3 **
   4 ******************************************************
   5
   6 There is 4 projects in the tree:
   7
   8  - GROS: no fancy name yet (low-level toolbox: logging, datatypes).
   9  - GRAS: Grid Reality And Simulation (message passing API with two
  10          implementations allowing to compile programs on top of the
  11          simulator or for the real life without code modification)
  12  - SURF: Server for the Use of Resource Fictions (the simulator used
  13          in GRAS and more)
  14  - AMOK: Advanced Metacomputing Overlay Kit (high level toolbox; Grid
  15          application elements such as distributed database, topology
  16          discovery service, and so on)
  17
  18 They are all in the same tree because GRAS depends on SURF which depends on
  19 GRAS (that's the only cycle here, we're not *that* vicious).
  20
  21 The tree is not splited on projects, but on file finality:
  22  include/            -> all *public* headers
  23  include/gros/*.h    -> one file per module
  24  include/gros.h      -> file including all modules headers
  25   (same for gras, surf and amok instead of gros)
  26
  27  src/Makefile.am     -> main makefile. All projects should fit in only one
  28                         library (I mean 2, RL+SG), which is compiled here.
  29
  30                         Since all object.o files are placed here, you should
  31                         choose the name of c files carfully to avoid
  32                         conflict.
  33
  34  src/gras/DataDesc                      -> typical project module
  35  src/gras/DataDesc/datadesc_interface.h -> visible to any GRAS modules;
  36                                            masked to the user and GROS/AMOK/SURF
  37  src/gras/DataDesc/datadesc_private.h   -> visible only from this module
  38
  39    So, the modules have 3 levels of publicity for their interface.
  40    Private, internal to GRAS, public. Of course, I try to keep as much stuff
  41    private as possible.
  42
  43  testsuite/ -> The more test the better.
  44                Same organization than src/ and include/
  45                Tests are allowed to load some headers of the module they test.
  46                All tests should be listed in run_test.in so that they get
  47                   run on 'make check'.
  48                They are not listed directly in the check_PROGRAMS part of
  49                   the makefile because run_test knows about the gras logging
  50                   features and relaunch with full details the failed tests.
  51
  52  examples/ -> Supposed to be copy/pastable by the user, so keep it clear and
  53                 avoid any kind of trick. In particular, do only include the
  54                 public headers here.
  55
  56 **
  57 ** Type naming standard
  58 **
  59 *****************************************************
  60
  61 It may sound strange, but the type naming convention was source of intense
  62 discution between da GRAS posse members. The convention we came to may not
  63 be the best solution, but it has the merit to exist and leave everyone work.
  64 So please stick to it.
  65
  66   - ???_t is a valid type (builded with typedef)
  67   - s_toto_t is a structure (access to fields with .)
  68   - s_toto   is a structure needing 'struct' keyword to be used
  69   - e_toto_t is an enum
  70   - u_toto_t is an union
  71   - u_toto   is an union needing 'union' keyword to be used
  72   -   toto_t is an 'object' (struct*)
  73
  74 Please to not call toto_t something else than an 'object' (ie, something you
  75 have to call _new and _free on it).
  76
  77 Exemple:
  78   typedef struct s_toto {} s_toto_t, *toto_t;
  79   typedef enum {} e_toto_t;
  80
  81 Moreover, only toto_t (and e_toto_t) are public. The rest (mainly s_toto_t)
  82 is private.
  83
  84 If you see any part of the code not following this convention, this is a
  85 bug. Please report it (or fix it yourself if you can).
  86
  87 **
  88 ** Random bits about coding standards and portability
  89 **
  90 *****************************************************
  91
  92 MALLOC:
  93  You must cast the result of malloc on AIX.
  94  It's even better to use gras_new when possible.
  95
  96 SIZE_T
  97  If possible, avoid size_t and use unsigned long instead. If not,
  98
  99  #include <sys/types.h> in all files manipulating size_t
 100  do cast it to unsigned long before printing (and use %lu)
 101
 102 PRINTF pointer difference
 103  printf ("diff = %ld\n", (long) (pointer2 - pointer1));
 104
 105
 106