\section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start?
-You are at the right place... Having a look to these
+You are at the right place... Having a look to these
<a href="http://www.loria.fr/~quinson/articles/simgrid-tutorial.pdf">the tutorial slides</a>
(or to these <a href="http://graal.ens-lyon.fr/~alegrand/articles/slides_g5k_simul.pdf">old slides</a>,
or to these
\li ccmake for graphical used of CMake
\li cmake <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
-\subsubsection faq_intro4 Cmake vs Autotools...
-
-TODO
-
+For windows only :
+ \li Visual C++ 2010 Express <a href="http://www.microsoft.com/express/Downloads/#2010-Visual-CPP">(download page)</a>
+ \li cmake <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
+ \li Set CC, CXX, INCLUDE, LIB and RC to environment variables.
+\verbatim
+SET --> CC TO --> C:\MicrosoftVisualStudio10\VC\bin\cl
+ --> CXX --> C:\MicrosoftVisualStudio10\VC\bin\cl
+ --> INCLUDE --> C:\MicrosoftVisualStudio10\VC\include;C:\Program Files\Microsoft SDKs\Windows\v7.OA\Include
+ --> LIB --> C:\MicrosoftVisualStudio10\VC\lib;C:\Program Files\Microsoft SDKs\Windows\v7.OA\Lib
+ --> RC --> C:\Program Files\Microsoft SDKs\Windows\v7.OA\bin\RC
+\endverbatim
+ \li Add to environment variable "Path" the path where to find nmake executable and some needed files.
+\verbatim
+......
+;C\MicrosoftVisualStudio10\VC\bin
+;C\MicrosoftVisualStudio10\Common7\IDE
+;C:\Program Files\Microsoft SDKs\Windows\v7.OA\bin
+;C:\Program Files\Microsoft SDKs\Windows\v7.OA\Lib
+;C:\Program Files\Microsoft SDKs\Windows\v7.OA\bInclude
+\endverbatim
\subsection faq_cmakeoption Cmake options
\subsubsection faq_cmakeoption1 Liste of options
enable_tracing ON/OFF or TRUE/FALSE or 1/0
enable_coverage ON/OFF or TRUE/FALSE or 1/0
enable_memcheck ON/OFF or TRUE/FALSE or 1/0
- enable_print_message ON/OFF or TRUE/FALSE or 1/0
+ enable_model-checking ON/OFF or TRUE/FALSE or 1/0
gtnets_path <path_to_gtnets_directory>
prefix <path_to_install_directory>
\li enable_smpi : Set to true if you want to use smpi lib. Actually on simgrid v3.4.1 Mac doesn't support lib smpi.
- \li enable_maintainer_mode : set to true it remakes some files.
+ \li enable_maintainer_mode : set to true it remakes some files.
\verbatim
include/surf/simgrid_dtd.h
include/xbt/graphxml.h
\li enable_memcheck : When set to true this option enable tests for memcheck.
- \li enable_print_message : This option when enable permits to see variables from gras_config.h
+ \li enable_model-checking : Enable the model checking when set to true.
\li gtnets_path : Path to gtnets install directory (ex /usr)
\subsubsection faq_cmakeoption3 Initialisation
-Those options are initialized the first time you launch \"cmake ./\" whithout specified option.
+Those options are initialized the first time you launch "cmake ." whithout specified option.
\verbatim
enable_gtnets on
enable_tracing off
enable_coverage off
enable_memcheck off
-enable_print_message off
+enable_model-checking off
gtnets_path null
prefix null
\subsubsection faq_cmakeoption4 Option's cache and how to reset?
-When options have been set they are keep into a cache file named \"CMakeCache.txt\". So if you want
+When options have been set they are keep into a cache file named "CMakeCache.txt". So if you want
reset values you just delete this file located to the project directory.
\subsection faq_cmakecompilation Cmake compilation
\endverbatim
Then follow instructions.
+\subsubsection faq_cmakecompilation2bis Build out of source.
+
+As cmake generate many files used for compilation, we recommand to make a build directory.
+For examples you can make :
+
+\verbatim
+"navarrop@caraja:~/Developments$ cd simgrid/"
+"navarrop@caraja:~/Developments/simgrid$ mkdir build_directory"
+"navarrop@caraja:~/Developments/simgrid$ cd build_directory/"
+"navarrop@caraja:~/Developments/simgrid/build_directory$ cmake ../"
+"navarrop@caraja:~/Developments/simgrid/build_directory$ make"
+\endverbatim
+
+Or complety out of sources :
+
+\verbatim
+"navarrop@caraja:~/Developments$ mkdir build_dir"
+"navarrop@caraja:~/Developments$ cd build_dir/"
+"navarrop@caraja:~/Developments/build_dir$ cmake ../simgrid/"
+"navarrop@caraja:~/Developments/build_dir$ make"
+\endverbatim
+
+Those two kind of compilation permit to delete files created by compilation easier.
+
\subsubsection faq_cmakecompilation3 Resume of command line
\li CMake
\verbatim
-cmake ./ configure the project
+cmake <path> configure the project
make build all targets
make VERBOSE=1 build all targets and print build command lines
-make check execute command make test
-make test test all targets and summarize
+make check test all targets and summarize
make dist make the distrib
-make distcheck check the dist (make + make dist + make test)
-make install-simgrid install the project (doc/ lib/ include/)
+make distcheck check the dist (make + make dist + make check)
+make install install the project (doc/ lib/ include/)
make uninstall uninstall the project (doc/ lib/ include/)
make clean clean all targets
make java-clean clean files created by java option
make maintainer-clean clean maintainer files
make all-clean execute the 5 upper clean command
make html Create simgrid documentation
-make maintainer-clean Remove all files generated by mainainer mode
\endverbatim
When the project have been succesfully compiling and build you can make tests.
\verbatim
cmake -Denable_maintainer_mode=on -Dprefix=/home/navarrop/Bureau/install_simgrid ./
make
-make install-simgrid
+make install
\endverbatim
\subsubsection faq_cmakeinstall2 From a distrib
\verbatim
cmake -Dprefix=/home/navarrop/Bureau/install_simgrid ./
make
-make install-simgrid
+make install
\endverbatim
\subsection faq_cmakehowto How to modified sources files for developers
target_link_libraries(get_sender simgrid m pthread -fprofile-arcs) #target_link_libraries(<name_of_targe> <dependencies>)
\endverbatim
-Then you have to modified <project/directory>/buildtools/Cmake/src/CMakeMakeExeLib.txt and add
+Then you have to modified <project/directory>/buildtools/Cmake/CMakeMakeExeLib.txt and add
this line :
\verbatim
add_subdirectory(${PROJECT_DIRECTORY}/<path_where_is_CMakeList.txt>)
\subsubsection faq_cmakehowto2 Delete/add sources to lib.
-If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/src/CMakeDefinePackages.txt
+If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/CMakeDefinePackages.txt
\verbatim
set(JMSG_JAVA_SRC
\subsubsection faq_cmakehowto3 Add test
-If you want modified, add or delete tests you have to edit <project/directory>/buildtools/Cmake/src/CMakeTest.txt
+If you want modified, add or delete tests you have to edit <project/directory>/buildtools/Cmake/CMakeTest.txt
with this function : ADD_TEST(<name> <bin> <ARGS>)
\verbatim
Cmake sources:
./doc/CMakeLists.txt
- ./buildtools/Cmake/src/CMakeCompleteInFiles.txt
- ./buildtools/Cmake/src/CMakeDocs.txt
- ./buildtools/Cmake/src/CMakeMakeExeLib.txt
- ./buildtools/Cmake/src/CMakePrintArgs.txt
- ./buildtools/Cmake/src/CMakeDefinePackages.txt
- ./buildtools/Cmake/src/CMakeFlags.txt
- ./buildtools/Cmake/src/CMakeSupernovae.txt
- ./buildtools/Cmake/src/CMakeDistrib.txt
- ./buildtools/Cmake/src/CMakeMaintainerMode.txt
- ./buildtools/Cmake/src/CMakeOption.txt
- ./buildtools/Cmake/src/CMakeTest.txt
- ./buildtools/Cmake/src/CTestConfig.cmake
-
-Test files for define properties :
- ./buildtools/Cmake/prog_test/prog_GRAS_ARCH.c
- ./buildtools/Cmake/prog_test/prog_max_size.c
- ./buildtools/Cmake/prog_test/prog_sem_init.c
- ./buildtools/Cmake/prog_test/prog_stackgrowth.c
- ./buildtools/Cmake/prog_test/prog_vsnprintf.c
- ./buildtools/Cmake/prog_test/prog_AC_CHECK_MCSC.c
- ./buildtools/Cmake/prog_test/prog_GRAS_CHECK_STRUCT_COMPACTION.c
- ./buildtools/Cmake/prog_test/prog_mutex_timedlock.c
- ./buildtools/Cmake/prog_test/prog_sem_timedwait.c
- ./buildtools/Cmake/prog_test/prog_stacksetup.c
- ./buildtools/Cmake/prog_test/prog_getline.c
- ./buildtools/Cmake/prog_test/prog_gtnets.cpp
- ./buildtools/Cmake/prog_test/prog_printf_null.c
- ./buildtools/Cmake/prog_test/prog_snprintf.c
- ./buildtools/Cmake/prog_test/prog_va_copy.c
-
+ ./buildtools/Cmake/AddTests.cmake
+ ./buildtools/Cmake/CompleteInFiles.cmake
+ ./buildtools/Cmake/CTestConfig.cmake
+ ./buildtools/Cmake/DefinePackages.cmake
+ ./buildtools/Cmake/Distrib.cmake
+ ./buildtools/Cmake/Flags.cmake
+ ./buildtools/Cmake/GenerateDocs.cmake
+ ./buildtools/Cmake/MaintainerMode.cmake
+ ./buildtools/Cmake/MakeExeLib.cmake
+ ./buildtools/Cmake/MakeJava.cmake
+ ./buildtools/Cmake/Option.cmake
+ ./buildtools/Cmake/PrintArgs.cmake
+ ./buildtools/Cmake/Supernovae.cmake
+
CMakeLists for each binaries or examples:
./CMakeLists.txt
./src/CMakeLists.txt
void MC_assert(int prop);
\endverbatim
+\subsection faq_binding_lua Lua Binding
+Most of Simgrid modules require a good level in C programming ,
+ since simgrid is used to be as standard C library .
+ Sometime ( for some reason or another ) developers prefer using some kind of « easy scripts »
+ (something like … lua ? Ruby ? ...?) or a language easier to code with ( Java ? ) for their works ,
+ which avoid dealing with C errors , and sometime an important gain of time (coding-time?) .
+Besides Java Binding , Lua and Ruby bindings are available now( since version 3.4 of Simgrid )
+for MSG Module , and we are currenlty working on bindings for other modules .
+
+
+\subsubsection faq_binding_lua_about What is lua ?
+Lua (Moon for portuguese !) is a lightweight, reflective, imperative and functional programming language,
+ designed as a scripting language with extensible semantics as a primary goal.(see official web site <a href="http://www.lua.org">here</a>)
+\subsubsection faq_binding_lua_why Why lua ?
+Lua is a fast,portable and powerful script language , quite simple to use for developpers .
+it combines procedural features with powerful data description facilities,
+ by using a simple, yet powerful, mechanism of tables.
+Lua has a relatively simple C API compared to other scripting languages,
+and accordingly it provides a robust, easy to use it.
+\subsubsection faq_binding_lua_simgrid How to use lua in Simgrid ?
+Actually , the use of lua in Simgrid is quite simple , you have just to follow the same steps as coding with C in Simgird ,
+ but this time , code with Lua ;) :
+ - Coding functions coresponding to each process
+ - loading the platforme/deployment XML file that describe the environment of simulation
+ - and … Running the Simulation !!!
+
+\subsubsection faq_binding_lua_example_master_slave Master/Slave Example
+ \li Master Code
+\verbatim
+function Master(...)
+ nb_task = arg[1];
+ comp_size = arg[2];
+ comm_size = arg[3];
+ slave_count = arg[4]
+ -- Dispatch the tasks
+ for i=1,nb_task do
+ tk = simgrid.Task.new("Task "..i,comp_size,comm_size);
+ alias = "slave "..(i%slave_count);
+ simgrid.info("Master sending ’" .. simgrid.Task.name(tk) .."’ To ’" .. alias .."’");
+ simgrid.Task.send(tk,alias);
+ simgrid.info("Master done sending ’".. simgrid.Task.name(tk) .."’ To ’" .. alias .."’");
+ end
+ -- Sending Finalize Message To Others
+ for i=0,slave_count-1 do
+ alias = "slave "..i;
+ simgrid.info("Master: sending finalize to "..alias);
+ finalize = simgrid.Task.new("finalize",comp_size,comm_size);
+ simgrid.Task.send(finalize,alias)
+ end
+end
+\endverbatim
+we mainly use simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task ,
+ then simgrid.Task.send(task,alias) to send it .
+we use also simgrid.Task.name(task), to get the task's name .
+
+\li Slave Code
+\verbatim
+function Slave(...)
+ local my_mailbox="slave "..arg[1]
+ while true do
+ local tk = simgrid.Task.recv(my_mailbox);
+ if (simgrid.Task.name(tk) == "finalize") then
+ simgrid.info("Slave ’" ..my_mailbox.."’ got finalize msg");
+ break
+ end
+ simgrid.Task.execute(tk)
+ end
+ simgrid.info("Slave ’" ..my_mailbox.."’: I’m Done . See You !!");
+end
+\endverbatim
+Here , we could see how we use simgrid.Task.recv(alias) to receive a task with a specific alias ,
+this function return directly the task recevied .
+
+\li Set Environmenet and run application
+\verbatim
+require "simgrid"
+simgrid.platform("my_platform.xml")
+simgrid.application("my_deployment.xml")
+simgrid.run()
+simgrid.info("Simulation’s over.See you.")
+simgrid.clean()
+\endverbatim
+
+\subsubsection faq_binding_lua_example_data Exchanging Data
+You can also exchange data between Process using lua .for that , you have to deal with lua task as a table ,
+since lua is based itself on a mechanism of tables ,
+so you can exchange any kind of data ( tables, matrix , strings … ) between process via tasks.
+
+\li Sender process
+\verbatim
+ task = simgrid.Task.new("data_task",task_comp,task_comm);
+ task['matrix'] = my_matrix;
+ task['table'] = my_table;
+ task['message'] = "Hello from (Lua || Simgrid ) !! "
+ …
+ simgrid.Task.send(task,alias)
+\endverbatim
+ After creating task , we associate to it various kind of data with a specific key , ( string in this case)
+ to distinguish between data variables . Via this key the receiver could access easily to datas .
+
+
+\li Receiver processe
+\verbatim
+ task = simgrid.Task.recv(alias);
+ sender_matrix = task['matrix'];
+ sender_table = task['table'];
+ sender_message = task['message']
+ ...
+\endverbatim
+ Note that in lua , both sender and receiver share the same lua task !
+ So that the receiver could joint data directly on the received task without sending it back .
+ You can find a complet example ( matrix multiplication case ) in the file example/lua/mult_matrix.lua
+
+
+\subsubsection faq_binding_lua_example_bypass Bypass XML
+ maybe you wonder if there is a way to bypass the XML files ,
+ and describe your platform directly from the code , with lua bindings it's Possible !! how ?
+ We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files
+ ( this can be useful for large platforms , so a simple for loop will avoid you to deal with an annoying XML File ;) )
+
+
+\li set Hosts
+\verbatim
+ simgrid.Host.new("Tremblay",98095000);
+ simgrid.Host.new("Jupiter",76296000);
+ simgrid.Host.new("Fafard",76296000);
+ simgrid.Host.new("Ginette",48492000);
+ simgrid.Host.new("Bourassa",48492000);
+\endverbatim
+ we use simgrid.Host.new(host_id,power) to instanciate our hosts.
+
+\li set Links
+\verbatim
+ for i=0,11 do
+ simgrid.Link.new(i,252750+ i*768,0.000270544+i*0.087); -- some crazy values ;)
+ end
+\endverbatim
+ we used simgrid.Link.new(link_id,bandwidth,latency) with a simple for loop to create all links we need ( much easier than XML hein ? )
+
+\li set Routes
+\verbatim
+-- simgrid.Route.new(src_id,des_id,links_nb,links_list)
+ simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
+ simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
+ simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
+ simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});
+
+ simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
+ simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
+ simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
+ simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
+ ...
+\endverbatim
+ for each host you have to specify which route to choose to access to the rest of hosts connected in the grid .
+
+\li Save platform
+\verbatim
+ simgrid.register_platform();
+\endverbatim
+Don't forget to register your platform , that SURF callbacks starts their work ;)
+
+\li set application
+\verbatim
+ simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
+ simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
+ simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
+ simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
+ simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
+\endverbatim
+ you don't need to use a deployment XML file , thanks to simgrid.Host.setFunction(host_id,function,args_number,args_list)
+ you can associate functions for each host with arguments if needed .
+
+\li
+\verbatim
+ simgrid.register_application();
+\endverbatim
+Yes , Here too you have to resgiter your application before running the simulation .
+
+the full example is distributed in the file examples/lua/master_slave_bypass.lua
+
+\subsection faq_binding_ruby Ruby Binding
+
+\subsubsection faq_binding_ruby_about What is Ruby ?
+Ruby is a dynamic, reflective, general purpose object-oriented programming language that combines syntax inspired by Perl with Smalltalk-like features.
+Ruby supports multiple programming paradigms, including functional, object oriented, imperative and reflective. It also has a dynamic type system and automatic memory management;
+it is therefore similar in varying respects to Python, Perl, Lisp, Dylan, Pike, and CLU.(see official web site <a href="http://ruby-lang.org">here</a>)
+
+\subsubsection faq_binding_ruby_simgrid Use Ruby in Simgrid
+Since v3.4 , the use of ruby in simgrid is available for the MSG Module .
+you can find almost all MSG functionalities in Ruby code , that allows you to set up your environment , manage tasks between hosts and run the simulation.
+
+\subsubsection faq_binding_ruby_example Master/Slave Ruby Application
+for each process method(master and slave in this example), you have to associate a ruby class , that should inherit from <i>MSG::Process</i> ruby class,
+ with a 'main' function that describe the behaviour of the process during the simulation.
+\li required stuff
+\verbatim
+require 'simgrid'
+include MSG
+\endverbatim
+
+\li Master code
+\verbatim
+#################################################
+# Class Master
+#################################################
+class Master < MSG::Process
+ # main : that function that will be executed when running simulation
+
+ def main(args) # args is an array containing arguments for function master
+ size = args.size
+ for i in 0..size-1
+ MSG::info("args["+String(i)+"]="+args[i])
+ end
+
+ raise "Master needs 3 arguments" if size < 3
+ numberOfTask = Integer(args[0])
+ taskComputeSize = Float(args[1])
+ taskCommunicationSize = Float(args[2])
+ slaveCount = Integer(args[3])
+
+ # Creates and sends the tasks
+ for i in 0..numberOfTask-1
+ task = Task.new("Task_"+ i.to_s, taskComputeSize , taskCommunicationSize);
+ mailbox = "slave " + (i%slaveCount).to_s
+ MSG::info("Master Sending "+ task.name + " to " + mailbox + " with Comput Size " +
+ task.compSize.to_s)
+ task.send(mailbox)
+ MSG::info("Master Done Sending " + task.name + " to " + mailbox)
+ end
+
+ # Sending Finalize MSG::Tasks
+ MSG::info("Master: All tasks have been dispatched. Let's tell everybody the computation is over.")
+ for i in 0..slaveCount-1
+ mailbox = "slave " + i.to_s
+ finalize_task = Task.new("finalize",0,0)
+ finalize_task.send(mailbox)
+ end
+ MSG::info("Master : Everything's Done")
+ end
+end
+\endverbatim
+the class MSG::Task contains methods that allows the management of the native MSG tasks.
+in master ruby code we used :
+ - <i>MSG::Task.new(task_name,compute_size,communication_size)</i> : to instanciate a new task.
+ - <i>MSG::Task.send(mailbox)</i> : to send the task via a mailbox alias.
+ - <i>MSG::Task.name</i> : to get the task's name.
+
+\li Slave code
+\verbatim
+#################################################
+# Class Slave
+#################################################
+class Slave < MSG::Process
+
+ def main(args)
+ mailbox = "slave " + args[0]
+ for i in 0..args.size-1
+ MSG::debug("args["+String(i)+"]="+args[i])
+ end
+
+ while true
+ task = Task.receive(mailbox)
+ if (task.name == "finalize")
+ break
+ end
+ task.execute
+ MSG::debug("Slave '" + mailbox + "' done executing task "+ task.name + ".")
+ end
+ MSG::info("I'm done, see you")
+ end
+end
+\endverbatim
+to receive a task , we use the method <i>MSG::Task.receive(mailbox)</i> that return a MSG:Task object (received task).
+
+\li Main chunk
+\verbatim
+if (ARGV.length == 2)
+ MSG.createEnvironment(ARGV[0])
+ MSG.deployApplication(ARGV[1])
+else
+ MSG.createEnvironment("platform.xml")
+ MSG.deployApplication("deploy.xml")
+end
+MSG.run
+puts "Simulation time : " + MSG.getClock .to_s
+MSG.exit
+\endverbatim
+- <i>MSG.createEnvironment(platform_file)</i> : set up the environment
+- <i>MSG.deployApplication(deployment_file)</i> : load the deployment file description.
+- <i>MSG.run</i> : run the simulation
+
+\subsubsection faq_binding_ruby_data Exchanging data
+ruby bindings provides two ways to exchange data between ruby processes.
+\li MSG::Task.join & MSG::Task.data \br
+
+ the MSG::Task class contains 2 methods that allows a data exchange between 2 process.
+
+ -<i>MSG::Task.join</i> : makes possible to join any kind of ruby data within a task.
+ \verbatim
+ ...
+ myTable = Array.new
+ myTable <<1<<-2<<45<<67<<87<<76<<89<<56<<78<<3<<-4<<99
+ # Creates and send Task With the Table inside
+ task = MSG::Task.new("quicksort_task",taskComputeSize, taskCommunicationSize);
+ task.join(myTable);
+ ...
+ task.send(mailbox);
+ \endverbatim
+ -<i>MSG::Task.data</i> : to access to the data contained into the task.
+ \verbatim
+ ...
+ task = MSG::Task.receive(recv_mailbox.to_s)
+ table = task.data
+ quicksort(table,0,table.size-1)
+ ...
+ \endverbatim
+you can find a complet example illustrating the use of those methods in file /example/ruby/Quicksort.rb
+
+\li inheritence
+
+ another 'object-oriented' way to do it , is to make your own 'task' class that inherit from MSG::Task ,
+ and contains data you want to deal with , the only 'tricky' thing is that "the initializer" method has no effect !
+
+ the use of some getter/setter methods would be the simple way to manage your data :)
+ \verbatim
+class PingPongTask < MSG::Task
+ # The initialize method has no effect
+ @time
+ def setTime(t)
+ @time = t
+ end
+ def getTime()
+ return @time
+ end
+end
+ \endverbatim
+ you can find an example of use in file example/ruby/PingPong.rb
+
\section faq_troubleshooting Troubleshooting
\subsection faq_trouble_lib_compil SimGrid compilation and installation problems
