6 It is not advised to modify the SimGrid source code directly, as it
7 will make it difficult to upgrade to the next version of SimGrid.
8 Instead, you should create your own working directory somewhere on
9 your disk (say ``/home/joe/MyFirstSimulator/``), and write your code
12 Cloning a Template Project for S4U
13 ----------------------------------
15 If you plan to use the modern S4U interface of SimGrid, the easiest way is
16 to clone the `Template Project
17 <https://framagit.org/simgrid/simgrid-template-s4u>`_ directly. It
18 contains the necessary configuration to use cmake and S4U together.
20 Once you forked the project on FramaGit, do not forget to remove the
21 fork relationship, as you won't need it unless you plan to contribute
22 to the template itself.
24 Building your project with CMake
25 --------------------------------
27 Here is a `CMakeLists.txt` that you can use as a starting point for your S4U
28 project (see below for MPI projects). It builds two simulators from a given set
33 cmake_minimum_required(VERSION 2.8.12)
34 project(MyFirstSimulator)
36 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")
38 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake/Modules/")
39 find_package(SimGrid REQUIRED)
40 include_directories(${SimGrid_INCLUDE_DIR})
42 set(SIMULATOR_SOURCES main.c other.c util.c)
43 add_executable(my_simulator ${SIMULATOR_SOURCES})
44 target_link_libraries(my_simulator ${SimGrid_LIBRARY})
46 set(OTHER_SOURCES blah.c bar.c foo.h)
47 add_executable(other_xp ${OTHER_SOURCES})
48 target_link_libraries(other_xp ${SimGrid_LIBRARY})
51 For that, you need `FindSimGrid.cmake
52 <https://framagit.org/simgrid/simgrid/raw/master/FindSimGrid.cmake>`_,
53 which is located at the root of the SimGrid tree. You can either copy
54 this file into the `cmake/Modules` directory of your project, or use
55 the version installed on the disk. Both solutions present advantages
56 and drawbacks: if you copy the file, you have to keep it in sync
57 manually but your project will produce relevant error messages when
58 trying to compile on a machine where SimGrid is not installed. Please
59 also refer to the file header for more information.
61 MPI projects should NOT search for MPI as usual in cmake, but instead use the ``smpi_c_target()`` macro
62 to declare that a given target is meant to be executed in ``smpirun`` (which path is set in ``${SMPIRUN}``).
63 This macro should work for C and C++ programs. Here is a small example:
67 # Search FindSimgrid in my sources
68 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}")
71 # Declare an executable, and specify that it's meant to run within smpirun
72 add_executable(roundtrip roundtrip.c)
73 smpi_c_target(roundtrip)
75 # Declare a test running our executable in ${SMPIRUN}
77 add_test(NAME RoundTrip
78 COMMAND ${SMPIRUN} -platform ${CMAKE_SOURCE_DIR}/../cluster_backbone.xml -np 2 ./roundtrip)
80 To compile Fortran code with cmake, you must override the ``MPI_Fortran_COMPILER`` variable as follows, but it will probably
81 break some configuration checks, so you should export ``SMPI_PRETEND_CC=1`` during the configuration (not during the compilation
84 .. code-block:: console
86 $ SMPI_PRETEND_CC=1 cmake -DMPI_C_COMPILER=/opt/simgrid/bin/smpicc -DMPI_CXX_COMPILER=/opt/simgrid/bin/smpicxx -DMPI_Fortran_COMPILER=/opt/simgrid/bin/smpiff .
89 Building your project with Makefile
90 -----------------------------------
92 Here is a Makefile that will work if your project is composed of three
93 C files named ``util.h``, ``util.c`` and ``mysimulator.c``. You should
94 take it as a starting point, and adapt it to your code. There is
95 plenty of documentation and tutorials on Makefile if the file's
96 comments are not enough for you.
98 .. code-block:: makefile
100 # The first rule of a Makefile is the default target. It will be built when make is called with no parameter
101 # Here, we want to build the binary 'mysimulator'
104 # This second rule lists the dependencies of the mysimulator binary
105 # How this dependencies are linked is described in an implicit rule below
106 mysimulator: mysimulator.o util.o
108 # These third give the dependencies of the each source file
109 mysimulator.o: mysimulator.c util.h # list every .h that you use
110 util.o: util.c util.h
113 SIMGRID_INSTALL_PATH = /opt/simgrid # Where you installed simgrid
114 CC = gcc # Your compiler
115 WARNING = -Wshadow -Wcast-align -Waggregate-return -Wmissing-prototypes \
116 -Wmissing-declarations -Wstrict-prototypes -Wmissing-prototypes \
117 -Wmissing-declarations -Wmissing-noreturn -Wredundant-decls \
118 -Wnested-externs -Wpointer-arith -Wwrite-strings -finline-functions
120 # CFLAGS = -g -O0 $(WARNINGS) # Use this line to make debugging easier
121 CFLAGS = -g -O2 $(WARNINGS) # Use this line to get better performance
123 # No change should be mandated past that line
124 #############################################
125 # The following are implicit rules, used by default to actually build
126 # the targets for which you listed the dependencies above.
128 # The blanks before the $(CC) must be a Tab char, not spaces
130 $(CC) -L$(SIMGRID_INSTALL_PATH)/lib/ $(CFLAGS) $^ -lsimgrid -o $@
132 $(CC) -I$(SIMGRID_INSTALL_PATH)/include $(CFLAGS) -c -o $@ $<
138 Develop in C++ with Eclipse
139 ----------------------------------------
141 If you wish to develop your plugin or modify SimGrid using
142 Eclipse. You have to run cmake and import it as a Makefile project.
144 Next, you have to activate C++17 in your build settings, add -std=c++17
145 in the CDT GCC Built-in compiler settings.
147 .. image:: /img/eclipseScreenShot.png
150 .. _install_yours_troubleshooting:
152 Troubleshooting your Project Setup
153 ----------------------------------
158 When the library cannot be found, you will get such an error message similar to:
160 .. code-block:: console
162 $ ./masterworker1: error while loading shared libraries: libsimgrid.so: cannot open shared object file: No such file or directory
164 To fix this, add the path to where you installed the library to the
165 ``LD_LIBRARY_PATH`` variable. You can add the following line to your
166 ``~/.bashrc`` so that it gets executed each time you log into your
169 .. code-block:: shell
171 export LD_LIBRARY_PATH=/opt/simgrid/lib
174 Many undefined references
175 ^^^^^^^^^^^^^^^^^^^^^^^^^
177 .. code-block:: console
179 masterworker.c:209: undefined reference to `sg_version_check'
180 (and many other undefined references)
182 This happens when the linker tries to use the wrong library. Use
183 ``LD_LIBRARY_PATH`` as in the previous item to provide the path to the
186 Only a few undefined references
187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
189 Sometimes, the compilation only spits very few "undefined reference"
190 errors. A possible cause is that the system selected an old version of
191 the SimGrid library somewhere on your disk.
193 Discover which version is used with ``ldd name-of-yoursimulator``.
194 Once you've found the obsolete copy of SimGrid, just erase it, and
195 recompile and relaunch your program.