X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/e83582ddbc62ff2bf8dc35cf64612df0713ac690..91715e2f198242d378e33453014dd004fcf9f47e:/README.coding diff --git a/README.coding b/README.coding index dd18e227d5..2a8302a1d7 100644 --- a/README.coding +++ b/README.coding @@ -1,12 +1,196 @@ +** +** Source tree organization +** +****************************************************** + +There is at least 5 sub-projects in the tree: + + - 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) + - 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 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/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. + + Since all object.o files are placed here, you should + choose the name of c files carfully to avoid + conflict. + + src/gras/DataDesc -> typical project module + src/gras/DataDesc/datadesc_interface.h -> visible to any GRAS modules; + masked to the user and GROS/AMOK/SURF + src/gras/DataDesc/datadesc_private.h -> visible only from this module + + 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. + All tests should be listed in run_test.in so that they get + run on 'make check'. + They are not listed directly in the check_PROGRAMS part of + the makefile because run_test knows about the gras logging + features and relaunch with full details the failed tests. + + 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: + +indent -kr -br -brs -ce -bbo --dont-break-procedure-type --no-tabs +--cuddle-do-while --cuddle-else --indent-level2 --leave-preprocessor-space +--no-space-after-function-call-names + +FIXME: this list of arguments is still to be discussed, maybe + +** +** Type naming standard +** +***************************************************** + +It may sound strange, but the type naming convention was source of intense +discution between da GRAS posse members. The convention we came to may not +be the best solution, but it has the merit to exist and leave everyone work. +So please stick to it. + + - ???_t is a valid type (builded with typedef) + - s_toto_t is a structure (access to fields with .) + - s_toto is a structure needing 'struct' keyword to be used + - e_toto_t is an enum + - u_toto_t is an union + - u_toto is an union needing 'union' keyword to be used + - toto_t is an 'object' (struct*) + +Please to not call toto_t something else than an 'object' (ie, something you +have to call _new and _free on it). + +Exemple: + typedef struct s_toto {} s_toto_t, *toto_t; + typedef enum {} e_toto_t; + +Moreover, only toto_t (and e_toto_t) are public. The rest (mainly s_toto_t) +is private. + +If you see any part of the code not following this convention, this is a +bug. Please report it (or fix it yourself if you can). + ** ** Random bits about coding standards and portability +** +***************************************************** 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) +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. + + +* +* SimGrid Hacker Survival Guide (FIXME: should be betterly placed) +******************************** + +* If you break the logs (for example while hacking in the dynars), you + want to define XBT_LOG_MAYDAY at the beginning of log.h. It will + desactivate the whole logging mecanism, switching to printfs + instead. SimGrid becomes incredibly verbose when doing so, but it + you let you fixing the dynars. \ No newline at end of file