X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/e83582ddbc62ff2bf8dc35cf64612df0713ac690..fde9407d1baff5065d23b005144b324a1407edbf:/README.coding diff --git a/README.coding b/README.coding index dd18e227d5..e48b67f5df 100644 --- a/README.coding +++ b/README.coding @@ -1,12 +1,193 @@ +** +** Source tree organization +** +****************************************************** + +There is at least 4 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. + - SMPI: Simulated MPI, to run MPI application using emulation technics. + +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 split on projects, but on file finality: + include/ -> all *public* headers + include/xbt/*.h -> one file per module + + 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'. + + 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 -l80 -nut -i2 -lps -npcs -br -brs -ce -cdw -bbo -npsl + +The script ./tools/indent runs indent with the appropriate options. + +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 +discussion between da SimGrid 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 (built 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). + +Example: + 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 +SIZE_T (FIXME: obsolete?) + 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) - - + do cast it to unsigned long before printing (and use %lu), + or use %zu. + +PRINTF pointer difference (FIXME: advertise %td instead?) + printf ("diff = %ld\n", (long) (pointer2 - pointer1)); + +INLINE functions + The definition of a inline function must be visible when it is used. + As such, an inline function should be defined (an not only declared) + in header file (.h) with attributes 'static XBT_INLINE'. It should + not be defined in source file (.c). + +** +** Commenting the source: doxygen +** +**************************************************** + +The global structure of the documentation is in doc/modules.doc + +The structure of each module (xbt, msg, 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 mechanism (FIXME: this section is deprecated) +** +**************************************************** + +There is some functionalities 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) +******************************** + +* Before pushing any change, don't forget to check if the compilation + passes with compiler optimizations and warnings turned on: + cmake -Denable_compile_optimizations=ON \ + -Denable_compile_warnings=ON + +* If you want to debug memory allocation problems, here are a few hints: + - disable compiler optimizations, to have better backtraces; + - disable the mallocators, or it will be hard to match malloc's with + free's; + - disable model checking, unless your problem lies in the model + checker part of SimGrid (MC brings its own malloc implementation, + which valgrind doesn't understand). + All this is configured with: + cmake -Denable_model-checking=OFF \ + -Denable_mallocators=OFF \ + -Denable_compile_optimizations=OFF + +* 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 + deactivate the whole logging mechanism, switching to printfs + instead. SimGrid becomes incredibly verbose when doing so, but it + you let you fixing the dynars.