README.coding

   1 **
   2 ** Source tree organization
   3 **
   4 ******************************************************
   5
   6 There is at least 4 projects in the tree:
   7
   8  - XBT: eXtended Bundle of Tools (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/xbt/*.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  src/include -> another location for protected headers. Used by SURF, and
  44                 other should be converted, since this is the Right Thing.
  45
  46  testsuite/ -> The more test the better.
  47                Same organization than src/ and include/
  48                Tests are allowed to load some headers of the module they test.
  49                All tests should be listed in run_test.in so that they get
  50                   run on 'make check'.
  51                They are not listed directly in the check_PROGRAMS part of
  52                   the makefile because run_test knows about the gras logging
  53                   features and relaunch with full details the failed tests.
  54
  55  examples/ -> Supposed to be copy/pastable by the user, so keep it clear and
  56                 avoid any kind of trick. In particular, do only include the
  57                 public headers here.
  58
  59 **
  60 ** Type naming standard
  61 **
  62 *****************************************************
  63
  64 It may sound strange, but the type naming convention was source of intense
  65 discution between da GRAS posse members. The convention we came to may not
  66 be the best solution, but it has the merit to exist and leave everyone work.
  67 So please stick to it.
  68
  69   - ???_t is a valid type (builded with typedef)
  70   - s_toto_t is a structure (access to fields with .)
  71   - s_toto   is a structure needing 'struct' keyword to be used
  72   - e_toto_t is an enum
  73   - u_toto_t is an union
  74   - u_toto   is an union needing 'union' keyword to be used
  75   -   toto_t is an 'object' (struct*)
  76
  77 Please to not call toto_t something else than an 'object' (ie, something you
  78 have to call _new and _free on it).
  79
  80 Exemple:
  81   typedef struct s_toto {} s_toto_t, *toto_t;
  82   typedef enum {} e_toto_t;
  83
  84 Moreover, only toto_t (and e_toto_t) are public. The rest (mainly s_toto_t)
  85 is private.
  86
  87 If you see any part of the code not following this convention, this is a
  88 bug. Please report it (or fix it yourself if you can).
  89
  90 **
  91 ** Random bits about coding standards and portability
  92 **
  93 *****************************************************
  94
  95 MALLOC:
  96  Don't use it, or you'll have to check the result (and do some dirty stuff
  97  on AIX). Use xbt_malloc (or even better, xbt_new) instead.
  98
  99 SIZE_T
 100  If possible, avoid size_t and use unsigned long instead. If not,
 101  #include <sys/types.h> in all files manipulating size_t
 102  do cast it to unsigned long before printing (and use %lu)
 103
 104 PRINTF pointer difference
 105  printf ("diff = %ld\n", (long) (pointer2 - pointer1));
 106
 107
 108 **
 109 ** Commenting the source: doxygen
 110 **
 111 ****************************************************
 112
 113 The global structure of the documentation is in doc/modules.doc
 114
 115 The structure of each module (xbt, gras, etc) is in doc/module-<module>.doc
 116
 117 The structure of a module is in its public header. This way, you're sure to
 118 see all the public interface (and only it). The different parts of the
 119 interface are grouped using the @name construct, even if it's buggy. Since
 120 parts often get reordered, it's better to add numbers to the parts (so that
 121 users can see the intended order).
 122
 123 The documentation of each type and macro are also in the public header since
 124 this is were they live.
 125
 126 The documentation of each function must be in the C file were it lives.
 127
 128 Any public element (function, type and macro) must have a @brief part.
 129
 130
 131 **
 132 ** Using the logs
 133 **
 134 ****************************************************
 135
 136 Dans gras, tu ne te contente pas d'écrire des choses à l'écran, mais tu
 137 écris sur un sujet particulier (notion de canal) des choses d'une gravité
 138 particulière. Il y a 7 niveaux de gravité.
 139  trace: tracer les entrées dans une fonction, retour de fonction
 140         (famille de macros XBT_IN/XBT_OUT)
 141  debug: pour t'aider à mettre au point le module, potentiellement tres bavard
 142  verbose: quelques infos succintes sur les internals du module
 143  info: niveau normal, ton de la conversation
 144  warning: problème potentiel, mais auquel on a su faire face
 145  error: problème qui t'as empêché de faire ton job
 146  critical: juste avant de mourir
 147
 148 Quand on compile avec -DNDEBUG (par défaut dans le paquet Debian), tout ce
 149 qui est '>= verbose' est supprimé au moment de la compilation. Retiré du
 150 binaire, killé.
 151
 152 Ensuite, tu écris dans un canal particulier. Tous les canaux sont rangés en
 153 arbre. Il faudrait faire un ptit script qui fouille les sources à la
 154 recherche des macros XBT_LOG_NEW_* utilisées pour créer des canaux. Le
 155 dernier argument de ces macros est ignoré dans le source. Il est destiné à
 156 être la documentation de la chose en une ligne. En gros, ca fait:
 157 root
 158  +--xbt
 159  |   +--config
 160  |   +--dict
 161  |   |   +--dict_cursor
 162  |   |   +--dict_elm
 163  |   |   ...
 164  |   +--dynar
 165  |   +--set
 166  |   +--log
 167  |   +--module
 168  +--gras
 169      +--datadesc
 170      |   +--ddt_cbps
 171      |   +--ddt_convert
 172      |   +--ddt_exchange
 173      |   +--ddt_parse
 174      |       +--lexer
 175      +--msg
 176      +--transport
 177          +--raw_trp (Je devrais tuer ce module, un jour)
 178          +--trp_buf
 179          +--trp_sg
 180          +--trp_file
 181          +--trp_tcp
 182
 183 Et ensuite les utilisateurs peuvent choisir le niveau de gravité qui les
 184 interresse sur tel ou tel sujet.
 185
 186 Toute la mécanique de logging repose sur des variables statiques dont le nom
 187 dépend du nom du canal.
 188  => attention aux conflits de nom de canal
 189  => il faut une macro XBT_LOG dans chaque fichier où tu fais des logs.
 190
 191 XBT_LOG_NEW_CATEGORY: nouveau canal sous "root". Rare, donc.
 192 XBT_LOG_NEW_SUBCATEGORY: nouveau canal dont on précise le père.
 193 XBT_LOG_DEFAULT_CATEGORY: indique quel est le canal par défaut dans ce fichier
 194 XBT_LOG_NEW_DEFAULT_CATEGORY: Crèe un canal et l'utilise par défaut
 195 XBT_LOG_NEW_DEFAULT_SUBCATEGORY: devine
 196 XBT_LOG_EXTERNAL_CATEGORY: quand tu veux utiliser par défaut un canal créé
 197                            dans un autre fichier.
 198
 199 Une fois que ton canal est créé, tu l'utilise avec les macros LOG, DEBUG,
 200 VERB, WARN, ERROR et CRITICAL. Il faut que tu donne le nombre d'arguments
 201 après le nom de macro. Exemple: LOG2("My name is %s %s","Martin","Quinson")
 202 Si tu veux préciser explicitement le canal où écrire, ajoute un C devant le
 203 nom de la macro. Exemple: CCRITICAL0(module, "Cannot initialize GRAS")
 204
 205 Toutes ces macros (enfin, ce en quoi elles se réécrivent) vérifient leurs
 206 arguments comme printf le fait lorsqu'on compile avec gcc.
 207 LOG1("name: %d","toto"); donne un warning, et donc une erreur en mode
 208 mainteneur.
 209
 210 Enfin, tu peux tester si un canal est ouvert à une priorité donnée (pour
 211 préparer plus de débug, par exemple. Dans le parseur, je fais du pretty
 212 printing sur ce qu'il faut parser dans ce cas).
 213 XBT_LOG_ISENABLED(catName, priority) Le second argument doit être une valeur
 214 de e_xbt_log_priority_t (log.h). Par exemple: xbt_log_priority_verbose
 215
 216 Voila sur comment mettre des logs dans ton code. N'hesite pas à faire pleins
 217 de canaux différents pour des aspects différents de ton code. En
 218 particulier, dans les dict, j'ai un canal pour l'ajout, le retrait, le
 219 netoyage du code après suppression et ainsi de suite. De cette façon, je
 220 peux choisir qui m'interresse.
 221
 222
 223 Pour utiliser les logs, tu déjà faire, non ? Tu colle sur la ligne de
 224 commande un ou plusieurs arguments de la forme
 225   --gras-log="<réglage> [<reglage>+]" (ou sans " si t'as pas d'espace)
 226 chaque réglage étant de la forme:
 227   <canal>.thres=<priorité>
 228 Les différents réglages sont lus de gauche à droite.
 229 "root.thres=debug root.thres=critical" ferme tout, normalement.