Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
be compatible with the standard of cmake+MPI
[simgrid.git] / docs / source / Start_Your_Own_Project.rst
1 ..
2
3 Start your Own Project
4 ======================
5
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
10 in there.
11
12 Cloning a Template Project for S4U
13 ----------------------------------
14
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.
19
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.
23
24 Building your project with CMake
25 --------------------------------
26
27 Here is a `CMakeLists.txt` that you can use as a starting point for
28 your project. It builds two simulators from a given set of source files.
29
30 .. code-block:: cmake
31
32    cmake_minimum_required(VERSION 2.8.8)
33    project(MyFirstSimulator)
34
35    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
36
37    set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake/Modules/")
38    find_package(SimGrid REQUIRED)
39    include_directories(${SimGrid_INCLUDE_DIR})
40
41    set(SIMULATOR_SOURCES main.c other.c util.c)
42    add_executable(my_simulator ${SIMULATOR_SOURCES})
43    target_link_libraries(my_simulator ${SimGrid_LIBRARY})
44
45    set(OTHER_SOURCES blah.c bar.c foo.h)
46    add_executable(other_xp ${OTHER_SOURCES})
47    target_link_libraries(other_xp ${SimGrid_LIBRARY})
48
49
50 For that, you need `FindSimGrid.cmake
51 <https://framagit.org/simgrid/simgrid/raw/master/FindSimGrid.cmake>`_,
52 that is located at the root of the SimGrid tree. You can either copy
53 this file into the `cmake/Modules` directory of your project, or use
54 the version installed on the disk. Both solutions present advantages
55 and drawbacks: if you copy the file, you have to keep it in sync
56 manually but your project will produce relevant error messages when
57 trying to compile on a machine where SimGrid is not installed. Please
58 also refer to the file header for more information.
59
60 MPI projects should include ``find_package (MPI)`` in CMakeLists.txt. Then, the
61 variables ``MPI_C_COMPILER``, ``MPI_CXX_COMPILER`` and ``MPI_Fortran_COMPILER`` should
62 point to the full path of smpicc, smpicxx and smpiff respectively. Example:
63
64 .. code-block:: shell
65
66    cmake -DMPI_C_COMPILER=/opt/simgrid/bin/smpicc -DMPI_CXX_COMPILER=/opt/simgrid/bin/smpicxx -DMPI_Fortran_COMPILER=/opt/simgrid/bin/smpiff .
67
68
69 Building your project with Makefile
70 -----------------------------------
71
72 Here is a Makefile that will work if your project is composed of three
73 C files named ``util.h``, ``util.c`` and ``mysimulator.c``. You should
74 take it as a starting point, and adapt it to your code. There are
75 plenty of documentation and tutorials on Makefile if the file's
76 comments are not enough for you.
77
78 .. code-block:: makefile
79
80    # The first rule of a Makefile is the default target. It will be built when make is called with no parameter
81    # Here, we want to build the binary 'mysimulator'
82    all: mysimulator
83
84    # This second rule lists the dependencies of the mysimulator binary
85    # How this dependencies are linked is described in an implicit rule below
86    mysimulator: mysimulator.o util.o
87
88    # These third give the dependencies of the each source file
89    mysimulator.o: mysimulator.c util.h # list every .h that you use
90    util.o: util.c util.h
91
92    # Some configuration
93    SIMGRID_INSTALL_PATH = /opt/simgrid # Where you installed simgrid
94    CC = gcc                            # Your compiler
95    WARNING = -Wshadow -Wcast-align -Waggregate-return -Wmissing-prototypes \
96              -Wmissing-declarations -Wstrict-prototypes -Wmissing-prototypes \
97              -Wmissing-declarations -Wmissing-noreturn -Wredundant-decls \
98              -Wnested-externs -Wpointer-arith -Wwrite-strings -finline-functions
99
100    # CFLAGS = -g -O0 $(WARNINGS) # Use this line to make debugging easier
101    CFLAGS = -g -O2 $(WARNINGS) # Use this line to get better performance
102
103    # No change should be mandated past that line
104    #############################################
105    # The following are implicit rules, used by default to actually build
106    # the targets for which you listed the dependencies above.
107
108    # The blanks before the $(CC) must be a Tab char, not spaces
109    %: %.o
110         $(CC) -L$(SIMGRID_INSTALL_PATH)/lib/    $(CFLAGS) $^ -lsimgrid -o $@
111    %.o: %.c
112         $(CC) -I$(SIMGRID_INSTALL_PATH)/include $(CFLAGS) -c -o $@ $<
113
114    clean:
115         rm -f *.o *~
116    .PHONY: clean
117
118 Develop in C++ with Eclipse
119 ----------------------------------------
120
121 If you wish to develop your plugin or modify SimGrid using
122 Eclipse. You have to run cmake and import it as a Makefile project.
123
124 Next you have to activate C++11 in your build settings, add -std=c++11
125 in the CDT GCC Built-in compiler settings.
126
127 .. image:: /img/eclipseScreenShot.png
128    :align: center
129
130
131 Building the Java examples in Eclipse
132 -------------------------------------
133
134 If you want to build our Java examples in Eclipse, get the whole
135 source code and open the archive on your disk. In Eclipse, select
136 the menu "File / Import", and then in the wizard "General / Existing
137 Project into Workspace". On the Next page, select the directory
138 "examples/deprecated/java" that you can find in the SimGrid source tree as a root
139 directory and finish the creation.
140
141 The file ``simgrid.jar`` must be in the root directory of the SimGrid
142 tree. That's where it is built by default, but if you don't want to
143 compile it yourself, just grab that file from the SimGrid website and
144 copy it in here.
145
146 Please note that once you better understand SimGrid, you should not
147 modify the examples directly but instead create your own project in
148 eclipse. This will make it easier to upgrade to another version of
149 SimGrid.
150
151 .. _install_yours_troubleshooting:
152
153 Troubleshooting your Project Setup
154 ----------------------------------
155
156 Library not found
157 ^^^^^^^^^^^^^^^^^
158
159 When the library cannot be found, you will get such an error message similar to:
160
161 .. code-block:: shell
162
163   ./masterworker1: error while loading shared libraries: libsimgrid.so: cannot open shared object file: No such file or directory
164
165 To fix this, add the path to where you installed the library to the
166 ``LD_LIBRARY_PATH`` variable. You can add the following line to your
167 ``~/.bashrc`` so that it gets executed each time you log into your
168 computer.
169
170 .. code-block:: shell
171
172   export LD_LIBRARY_PATH=/opt/simgrid/lib
173
174
175 Many undefined references
176 ^^^^^^^^^^^^^^^^^^^^^^^^^
177
178 .. code-block:: shell
179
180   masterworker.c:209: undefined reference to `sg_version_check'
181   masterworker.c:209: undefined reference to `MSG_init_nocheck'
182   (and many other undefined references)
183
184 This happens when the linker tries to use the wrong library. Use
185 ``LD_LIBRARY_PATH`` as in the previous item to provide the path to the
186 right library.
187
188 Only a few undefined references
189 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
190
191 Sometimes, the compilation only spits very few "undefined reference"
192 errors. A possible cause is that the system selected an old version of
193 the SimGrid library somewhere on your disk.
194
195 Dicover which version is used with ``ldd name-of-yoursimulator``.
196 Once you've found the obsolete copy of SimGrid, just erase it, and
197 recompile and relaunch your program.