X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/e9f0018b823e34405847177b25a85d3facc30ae1..251b0d76ec452c40978a1176bfa53818279f6492:/doc/doxygen/FAQ.doc diff --git a/doc/doxygen/FAQ.doc b/doc/doxygen/FAQ.doc index f70f833be5..2a8a74dae0 100644 --- a/doc/doxygen/FAQ.doc +++ b/doc/doxygen/FAQ.doc @@ -49,19 +49,16 @@ We also have a more graphical output. Have a look at section \ref options_tracin \subsection faq_C Argh! Do I really have to code in C? -Currently bindings on top of MSG are supported for Java, Ruby and Lua. You can find a few -documentation about them on the doc page. Note that bindings are released separately from the main dist -and so have their own version numbers. +We provide Java bindings of the MSG interface, which is the main +SimGrid user API. -Moreover If you use C++, -you should be able to use the SimGrid library as a standard C library -and everything should work fine (simply link against this -library; recompiling SimGrid with a C++ compiler won't work and it -wouldn't help if you could). +Moreover If you use C++, you should be able to use the SimGrid library +as a standard C library and everything should work fine (simply +link against this library; recompiling SimGrid with a C++ +compiler won't work and it wouldn't help if you could). -For now, -we do not feel a real demand for any other language. But if you think there is one, - please speak up! +For now, we do not feel a real demand for any other language. But if +you think there is one, please speak up! \section faq_howto Feature related questions @@ -193,7 +190,7 @@ would have to do out of the simulator, and thus gives you information that you could also get in real settings to not hinder the realism of your simulation. -\verbatim +\code double get_host_load() { m_task_t task = MSG_task_create("test", 0.001, 0, NULL); double date = MSG_get_clock(); @@ -203,7 +200,7 @@ double get_host_load() { MSG_task_destroy(task); return (0.001/date); } -\endverbatim +\endcode Of course, it may not match your personal definition of "host load". In this case, please detail what you mean on the mailing list, and we will extend @@ -218,7 +215,7 @@ account the time spent waiting for the other party to be ready). However, getting the *real* communication time is not really hard either. The following solution is a good starting point. -\verbatim +\code int sender() { m_task_t task = MSG_task_create("Task", task_comp_size, task_comm_size, @@ -243,7 +240,7 @@ int receiver() MSG_task_destroy(task); return 0; } -\endverbatim +\endcode \subsection faq_MIA_SimDag SimDag related questions @@ -256,10 +253,10 @@ model a data dependency between two DAG tasks t1 and t2, you have to create 3 SD_tasks: t1, t2 and c and add dependencies in the following way: -\verbatim +\code SD_task_dependency_add(NULL, NULL, t1, c); SD_task_dependency_add(NULL, NULL, c, t2); -\endverbatim +\endcode This way task t2 cannot start before the termination of communication c which in turn cannot start before t1 ends. @@ -281,7 +278,7 @@ communicating process to make the whole scheduling process distributed. Here is an example of how you could do that. Assume T1 has to be done before T2. -\verbatim +\code int your_agent(int argc, char *argv[] { ... T1 = MSG_task_create(...); @@ -298,7 +295,7 @@ has to be done before T2. } } } -\endverbatim +\endcode If you decide that the distributed part is not that much important and that DAG is really the level of abstraction you want to work with, then you should @@ -442,18 +439,12 @@ upgrade. Actually, you may want to read it (alongside with the NEWS file that highlights the most important changes) even before you upgrade your copy of SimGrid, too. -Backward compatibility is very important to us, as we want to provide -a scientific tool allowing to evaluate the code you write in several -years, too. That being said, we sometimes change the interface to make -them more usable to the users. When we do so, we always keep the old -interface as DEPRECATED. If you still want to use them, you want to -define the SIMGRID_DEPRECATED preprocessor symbol before loading the -SimGrid files: - -@verbatim -#define SIMGRID_DEPRECATED -#include -@endverbatim +We do our best to maintain the backward compatibility, but we +sometimes have to fix the things that are too broken. If we happen to +kill a feature that you were using, we are sorry. We think that you +should update to the new way of doing things, but if you can't afford +it, that's ok. Just stick to the last version that were working for +you, and have a pleasant day. \subsection faq_trouble_lib_compil SimGrid compilation and installation problems @@ -462,8 +453,9 @@ SimGrid files: We know only one reason for the configure to fail: - You are using a broken build environment\n - If symptom is that the configury magic complains about gcc not being able to build - executables, you are probably missing the libc6-dev package. Damn Ubuntu. + Try updating your cmake version. If symptom is that the configury + magic complains about gcc not being able to build executables, you + are probably missing the libc6-dev package. Damn Ubuntu. If you experience other kind of issue, please get in touch with us. We are always interested in improving our portability to new systems. @@ -485,7 +477,7 @@ do so. \subsubsection faq_trouble_err_logcat "gcc: _simgrid_this_log_category_does_not_exist__??? undeclared (first use in this function)" -This is because you are using the log mecanism, but you didn't created +This is because you are using the log mechanism, but you didn't created any default category in this file. You should refer to \ref XBT_log for all the details, but you simply forgot to call one of XBT_LOG_NEW_DEFAULT_CATEGORY() or XBT_LOG_NEW_DEFAULT_SUBCATEGORY(). @@ -502,95 +494,8 @@ of SimGrid), you must absolutely specify -lpthread on the linker command line. As usual, this should come after -lsimgrid on this command line. -\subsubsection faq_trouble_lib_msg_deprecated "gcc: undefined reference to MSG_*" - -Since version 3.7 all the m_channel_t mecanism is deprecated. So functions -about this mecanism may get removed in future releases. - -List of functions: - -\li XBT_PUBLIC(int) MSG_get_host_number(void); - -\li XBT_PUBLIC(m_host_t *) MSG_get_host_table(void); - -\li XBT_PUBLIC(MSG_error_t) MSG_get_errno(void); - -\li XBT_PUBLIC(MSG_error_t) MSG_task_get(m_task_t * task, m_channel_t channel); - -\li XBT_PUBLIC(MSG_error_t) MSG_task_get_with_timeout(m_task_t * task, m_channel_t channel, double max_duration); - -\li XBT_PUBLIC(MSG_error_t) MSG_task_get_from_host(m_task_t * task, int channel, m_host_t host); - -\li XBT_PUBLIC(MSG_error_t) MSG_task_get_ext(m_task_t * task, int channel, double max_duration, m_host_t host); - -\li XBT_PUBLIC(MSG_error_t) MSG_task_put(m_task_t task, m_host_t dest, m_channel_t channel); - -\li XBT_PUBLIC(MSG_error_t) MSG_task_put_bounded(m_task_t task, m_host_t dest, m_channel_t channel, double max_rate); - -\li XBT_PUBLIC(MSG_error_t) MSG_task_put_with_timeout(m_task_t task, m_host_t dest, m_channel_t channel, double max_duration); - -\li XBT_PUBLIC(int) MSG_task_Iprobe(m_channel_t channel); - -\li XBT_PUBLIC(int) MSG_task_probe_from(m_channel_t channel); - -\li XBT_PUBLIC(int) MSG_task_probe_from_host(int channel, m_host_t host); - -\li XBT_PUBLIC(MSG_error_t) MSG_set_channel_number(int number); - -\li XBT_PUBLIC(int) MSG_get_channel_number(void); - -If you want them you have to compile Simgrid v3.7 with option "-Denable_msg_deprecated=ON". -Using them should print warning to inform what new function you have to use. - \subsection faq_trouble_errors Runtime error messages -\subsubsection faq_flexml_limit "surf_parse_lex: Assertion `next limit' failed." - -This is because your platform file is too big for the parser. - -Actually, the message comes directly from FleXML, the technology on top of -which the parser is built. FleXML has the bad idea of fetching the whole -document in memory before parsing it. And moreover, the memory buffer size -must be determined at compilation time. - -We use a value which seems big enough for our need without bloating the -simulators footprints. But of course your mileage may vary. In this case, -just edit src/surf/surfxml.l modify the definition of -FLEXML_BUFFERSTACKSIZE. E.g. - -\verbatim -#define FLEXML_BUFFERSTACKSIZE 1000000000 -\endverbatim - -Then recompile and everything should be fine, provided that your version of -Flex is recent enough (>= 2.5.31). If not the compilation process should -warn you. - -A while ago, we worked on FleXML to reduce a bit its memory consumption, but -these issues remain. There is two things we should do: - - - use a dynamic buffer instead of a static one so that the only limit - becomes your memory, not a stupid constant fixed at compilation time - (maybe not so difficult). - - change the parser so that it does not need to get the whole file in - memory before parsing - (seems quite difficult, but I'm a complete newbe wrt flex stuff). - -These are changes to FleXML itself, not SimGrid. But since we kinda hijacked -the development of FleXML, I can grant you that any patches would be really -welcome and quickly integrated. - -Update: A new version of FleXML (1.7) was released. Most of the work -was done by William Dowling, who use it in his own work. The good point is -that it now use a dynamic buffer, and that the memory usage was greatly -improved. The downside is that William also changed some things internally, -and it breaks the hack we devised to bypass the parser, as explained in -\ref pf_flexml_bypassing. Indeed, this is not a classical usage of the -parser, and Will didn't imagine that we may have used (and even documented) -such a crude usage of FleXML. So, we now have to repair the bypassing -functionality to use the latest FleXML version and fix the memory usage in -SimGrid. - \subsubsection faq_trouble_errors_big_fat_warning I'm told that my XML files are too old. The format of the XML platform description files is sometimes @@ -601,9 +506,9 @@ descriptions to allow more compact descriptions. That is why the XML files are versionned using the 'version' attribute of the root tag. Currently, it should read: -\verbatim - -\endverbatim +@verbatim + +@endverbatim If your files are too old, you can use the simgrid_update_xml.pl script which can be found in the tools directory of the archive. @@ -637,7 +542,7 @@ This is when valgrind starts complaining about longjmp things, just like: ==21434== at 0x420DC3A: __longjmp (__longjmp.S:48) \endverbatim -This is the sign that you didn't used the exception mecanism well. Most +This is the sign that you didn't used the exception mechanism well. Most probably, you have a return; somewhere within a TRY{} block. This is evil, and you must not do this. Did you read the section about \ref XBT_ex?? @@ -701,7 +606,7 @@ will run only one half of the true SimGrid potential. Unfortunately, we cannot debug every code written in SimGrid. We furthermore believe that the framework provides ways enough -information to debug such informations yourself. If the textual output +information to debug such information yourself. If the textual output is not enough, Make sure to check the \ref faq_visualization FAQ entry to see how to get a graphical one. @@ -776,106 +681,3 @@ specific at all, but it's full of good advices). \author Da SimGrid team */ - -****************************************************************** -* OLD CRUFT NOT USED ANYMORE * -****************************************************************** - - -subsection faq_crosscompile Cross-compiling a Windows DLL of SimGrid from linux - -At the moment, we do not distribute Windows pre-compiled version of SimGrid -because the support for this platform is still experimental. We know that -some parts of the GRAS environment do not work, and we think that the others -environments (MSG and SD) have good chances to work, but we didn't test -ourselves. This section explains how we generate the SimGrid DLL so that you -can build it for yourself. First of all, you need to have a version more -recent than 3.1 (ie, a SVN version as time of writting). - -In order to cross-compile the package to windows from linux, you need to -install mingw32 (minimalist gnu win32). On Debian, you can do so by -installing the packages mingw32 (compiler), mingw32-binutils (linker and -so), mingw32-runtime. - -You can use the VPATH support of configure to compile at the same time for -linux and windows without dupplicating the source nor cleaning the tree -between each. Just run bootstrap (if you use the SVN) to run the autotools. -Then, create a linux and a win directories. Then, type: -\verbatim cd linux; ../configure --srcdir=.. ; make; cd .. -cd win; ../configure --srcdir=.. --host=i586-mingw32msvc ; make; cd .. -\endverbatim -The trick to VPATH builds is to call configure from another directory, -passing it an extra --srcdir argument to tell it where all the sources are. -It will understand you want to use VPATH. Then, the trick to cross-compile -is simply to add a --host argument specifying the target you want to build -for. The i586-mingw32msvc string is what you have to pass to use the mingw32 -environment as distributed in Debian. - -After that, you can run all make targets from both directories, and test -easily that what you change for one arch does not break the other one. - -It is possible that this VPATH build thing breaks from time to time in the -SVN since it's quite fragile, but it's granted to work in any released -version. If you experience problems, drop us a mail. - -Another possible source of issue is that at the moment, building the -examples request to use the gras_stub_generator tool, which is a compiled -program, not a script. In cross-compilation, you need to cross-execute with -wine for example, which is not really pleasant. We are working on this, but -in the meanwhile, simply don't build the examples in cross-compilation -(cd src before running make). - -Program (cross-)compiled with mingw32 do request an extra DLL at run-time to be -usable. For example, if you want to test your build with wine, you should do -the following to put this library where wine looks for DLLs. -\verbatim -cp /usr/share/doc/mingw32-runtime/mingwm10.dll.gz ~/.wine/c/windows/system/ -gunzip ~/.wine/c/windows/system/mingwm10.dll.gz -\endverbatim - -The DLL is built in src/.libs, and installed in the prefix/bin directory -when you run make install. - -If you want to use it in a native project on windows, you need to use -simgrid.dll and mingwm10.dll. For each DLL, you need to build .def file -under linux (listing the defined symbols), and convert it into a .lib file -under windows (specifying this in a way that windows compilers like). To -generate the def files, run (under linux): -\verbatim echo "LIBRARY libsimgrid-0.dll" > simgrid.def -echo EXPORTS >> simgrid.def -nm libsimgrid-0.dll | grep ' T _' | sed 's/.* T _//' >> simgrid.def -nm libsimgrid-0.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> simgrid.def - -echo "LIBRARY mingwm10.dll" > mingwm10.def -echo EXPORTS >> mingwm10.def -nm mingwm10.dll | grep ' T _' | sed 's/.* T _//' >> mingwm10.def -nm mingwm10.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> mingwm10.def -\endverbatim - -To create the import .lib files, use the lib windows tool (from -MSVC) the following way to produce simgrid.lib and mingwm10.lib -\verbatim lib /def:simgrid.def -lib /def:mingwm10.def -\endverbatim - -If you happen to use Borland C Builder, the right command line is the -following (note that you don't need any file.def to get this working). -\verbatim implib simgrid.lib libsimgrid-0.dll -implib mingwm10.lib mingwm10.dll -\endverbatim - -Then, set the following parameters in Visual C++ 2005: -Linker -> Input -> Additional dependencies = simgrid.lib mingwm10.lib - -Just in case you wonder how to generate a DLL from libtool in another -project, we added -no-undefined to any lib*_la_LDFLAGS variables so that -libtool accepts to generate a dynamic library under windows. Then, to make -it true, we pass any dependencies (such as -lws2 under windows or -lpthread -on need) on the linking line. Passing such deps is a good idea anyway so -that they get noted in the library itself, avoiding the users to know about -our dependencies and put them manually on their compilation line. Then we -added the AC_LIBTOOL_WIN32_DLL macro just before AC_PROG_LIBTOOL in the -configure.ac. It means that we exported any symbols which need to be. -Nowadays, functions get automatically exported, so we don't need to load our -header files with tons of __declspec(dllexport) cruft. We only need to do so -for data, but there is no public data in SimGrid so we are good.