X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/fc4c9e6585b6a410714badd79c11aee90a298165..f786c09b12eb263982346069d7505bbc97af6eb7:/README.coding diff --git a/README.coding b/README.coding index b4f2b2f697..1faa329184 100644 --- a/README.coding +++ b/README.coding @@ -3,26 +3,29 @@ ** ****************************************************** -There is 4 projects in the tree: +There is at least 5 sub-projects in the tree: - - GROS: no fancy name yet (low-level toolbox: logging, datatypes). + - XBT: eXtended Bundle of Tools (low-level toolbox: logging, datatypes). + - SURF: a SimUlation aRtiFact. This is the simulation kernel. + - MSG: originally MetaSimGrid, MSG is a simple distributed application + simulator. - GRAS: Grid Reality And Simulation (message passing API with two implementations allowing to compile programs on top of the simulator or for the real life without code modification) - - SURF: Server for the Use of Resource Fictions (the simulator used - in GRAS and more) - AMOK: Advanced Metacomputing Overlay Kit (high level toolbox; Grid application elements such as distributed database, topology discovery service, and so on) -They are all in the same tree because GRAS depends on SURF which depends on -GRAS (that's the only cycle here, we're not *that* vicious). +They are all in the same tree because they are complementary tools and +having all of them in the same package makes the installation easier +for end-users. Moreover, it enables to share the compilation chain and +eases the development. The tree is not splited on projects, but on file finality: include/ -> all *public* headers - include/gros/*.h -> one file per module - include/gros.h -> file including all modules headers - (same for gras, surf and amok instead of gros) + include/xbt/*.h -> one file per module + include/gras.h -> file including all modules headers + (same for xbt instead of gras) src/Makefile.am -> main makefile. All projects should fit in only one library (I mean 2, RL+SG), which is compiled here. @@ -39,7 +42,10 @@ The tree is not splited on projects, but on file finality: So, the modules have 3 levels of publicity for their interface. Private, internal to GRAS, public. Of course, I try to keep as much stuff private as possible. - + + src/include -> another location for protected headers. Used by SURF, and + other should be converted, since this is the Right Thing. + testsuite/ -> The more test the better. Same organization than src/ and include/ Tests are allowed to load some headers of the module they test. @@ -52,6 +58,13 @@ The tree is not splited on projects, but on file finality: examples/ -> Supposed to be copy/pastable by the user, so keep it clear and avoid any kind of trick. In particular, do only include the public headers here. +** +** Indentation standard +** +***************************************************** + +Most files use the Kernighan & Ritchie coding style with 2 spaces of +indentation. The indent program can help you to stick to it. :) ** ** Type naming standard @@ -90,12 +103,11 @@ bug. Please report it (or fix it yourself if you can). ***************************************************** MALLOC: - You must cast the result of malloc on AIX. - It's even better to use gras_new when possible. + Don't use it, or you'll have to check the result (and do some dirty stuff + on AIX). Use xbt_malloc (or even better, xbt_new) instead. SIZE_T If possible, avoid size_t and use unsigned long instead. If not, - #include in all files manipulating size_t do cast it to unsigned long before printing (and use %lu) @@ -103,4 +115,65 @@ PRINTF pointer difference printf ("diff = %ld\n", (long) (pointer2 - pointer1)); - +** +** Commenting the source: doxygen +** +**************************************************** + +The global structure of the documentation is in doc/modules.doc + +The structure of each module (xbt, gras, etc) is in doc/module-.doc + +The structure of a module is in its public header. This way, you're sure to +see all the public interface (and only it). The different parts of the +interface are grouped using the @name construct, even if it's buggy. Since +parts often get reordered, it's better to add numbers to the parts (so that +users can see the intended order). + +The documentation of each type and macro are also in the public header since +this is were they live. + +The documentation of each function must be in the C file were it lives. + +Any public element (function, type and macro) must have a @brief part. + +** +** XBT virtualization mecanism +** +**************************************************** + +There is some functionnalities that we want to virtualize in XBT. We +want xbt_time to give the simulated clock when running on top of the +simulator, and the host clock when running on a real system. This +could be placed in GRAS (and was, historically), but there is some +reason to lower it down to XBT. + +Here is the used naming scheme: + + - xbt__(): functions working both in SG and RL + - xbt_os__(): RL functions usable even in simulator + + That way, in libsimgrid, we still can use native functions if we + want to. It may for example be useful to get the real time when + implementing the simulator. Think of the SIGINT handler, which + wants to see if the user pressed the key twice in a 5 seconds + interval. This is of little use to check the simulated time here. + +Here is the file layout: + + - xbt_rl_.c: native implementation (xbt__()). + Simply call the corresponding xbt_os__. + Part only of libgras.so + + - xbt_sg_.c: SIMIX implementation xbt__()). + Simply call the corresponding SIMIX implementation. + Part only of libsimgrid.so + + - xbt_os_.c: body of the functions implementing natively the + stuff (xbt_os__()). + Part of both libgras.so and libsimgrid.so + +Since there is almost nothing in xbt_rl_module.c and xbt_sg_module.c, +it'd be better to use symbol aliasing here (to declare in the object +code that the same function have two names), but I'm still +investigating the portability of the thing to windows.