docs/source/intro_yours.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 in
  10 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 Building your project with Makefile
  61 -----------------------------------
  62
  63 Here is a Makefile that will work if your project is composed of three
  64 C files named ``util.h``, ``util.c`` and ``mysimulator.c``. You should
  65 take it as a starting point, and adapt it to your code. There are
  66 plenty of documentation and tutorials on Makefile if the file's
  67 comments are not enough for you.
  68
  69 .. code-block:: makefile
  70
  71    # The first rule of a Makefile is the default target. It will be built when make is called with no parameter
  72    # Here, we want to build the binary 'mysimulator'
  73    all: mysimulator
  74
  75    # This second rule lists the dependencies of the mysimulator binary
  76    # How this dependencies are linked is described in an implicit rule below
  77    mysimulator: mysimulator.o util.o
  78
  79    # These third give the dependencies of the each source file
  80    mysimulator.o: mysimulator.c util.h # list every .h that you use
  81    util.o: util.c util.h
  82
  83    # Some configuration
  84    SIMGRID_INSTALL_PATH = /opt/simgrid # Where you installed simgrid
  85    CC = gcc                            # Your compiler
  86    WARNING = -Wshadow -Wcast-align -Waggregate-return -Wmissing-prototypes \
  87              -Wmissing-declarations -Wstrict-prototypes -Wmissing-prototypes \
  88              -Wmissing-declarations -Wmissing-noreturn -Wredundant-decls \
  89              -Wnested-externs -Wpointer-arith -Wwrite-strings -finline-functions
  90
  91    # CFLAGS = -g -O0 $(WARNINGS) # Use this line to make debugging easier
  92    CFLAGS = -g -O2 $(WARNINGS) # Use this line to get better performance
  93
  94    # No change should be mandated past that line
  95    #############################################
  96    # The following are implicit rules, used by default to actually build
  97    # the targets for which you listed the dependencies above.
  98
  99    # The blanks before the $(CC) must be a Tab char, not spaces
 100    %: %.o
 101         $(CC) -L$(SIMGRID_INSTALL_PATH)/lib/    $(CFLAGS) $^ -lsimgrid -o $@
 102    %.o: %.c
 103         $(CC) -I$(SIMGRID_INSTALL_PATH)/include $(CFLAGS) -c -o $@ $<
 104
 105    clean:
 106         rm -f *.o *~
 107    .PHONY: clean
 108
 109 Develop in C++ with Eclipse
 110 ----------------------------------------
 111
 112 If you wish to develop your plugin or modify SimGrid using
 113 Eclipse. You have to run cmake and import it as a Makefile project.
 114
 115 Next you have to activate C++11 in your build settings, add -std=c++11
 116 in the CDT GCC Built-in compiler settings.
 117
 118 .. image:: /img/eclipseScreenShot.png
 119    :align: center
 120
 121
 122 Building the Java examples in Eclipse
 123 -------------------------------------
 124
 125 If you want to build our Java examples in Eclipse, get the whole
 126 source code and open the archive on your disk. In Eclipse, select
 127 the menu "File / Import", and then in the wizard "General / Existing
 128 Project into Workspace". On the Next page, select the directory
 129 "examples/java" that you can find in the SimGrid source tree as a root
 130 directory and finish the creation.
 131
 132 The file ``simgrid.jar`` must be in the root directory of the SimGrid
 133 tree. That's where it is built by default, but if you don't want to
 134 compile it yourself, just grab that file from the SimGrid website and
 135 copy it in here.
 136
 137 Please note that once you better understand SimGrid, you should not
 138 modify the examples directly but instead create your own project in
 139 eclipse. This will make it easier to upgrade to another version of
 140 SimGrid.
 141
 142 .. _install_yours_troubleshooting:
 143
 144 Troubleshooting your Project Setup
 145 ----------------------------------
 146
 147 Library not found
 148 ^^^^^^^^^^^^^^^^^
 149
 150 When the library cannot be found, you will get such an error message similar to:
 151
 152 .. code-block:: shell
 153
 154   ./masterworker1: error while loading shared libraries: libsimgrid.so: cannot open shared object file: No such file or directory
 155
 156 To fix this, add the path to where you installed the library to the
 157 ``LD_LIBRARY_PATH`` variable. You can add the following line to your
 158 ``~/.bashrc`` so that it gets executed each time you log into your
 159 computer.
 160
 161 .. code-block:: shell
 162
 163   export LD_LIBRARY_PATH=/opt/simgrid/lib
 164
 165
 166 Many undefined references
 167 ^^^^^^^^^^^^^^^^^^^^^^^^^
 168
 169 .. code-block:: shell
 170
 171   masterworker.c:209: undefined reference to `sg_version_check'
 172   masterworker.c:209: undefined reference to `MSG_init_nocheck'
 173   (and many other undefined references)
 174
 175 This happens when the linker tries to use the wrong library. Use
 176 ``LD_LIBRARY_PATH`` as in the previous item to provide the path to the
 177 right library.
 178
 179 Only a few undefined references
 180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 181
 182 Sometimes, the compilation only spits very few "undefined reference"
 183 errors. A possible cause is that the system selected an old version of
 184 the SimGrid library somewhere on your disk.
 185
 186 Dicover which version is used with ``ldd name-of-yoursimulator``.
 187 Once you've found the obsolete copy of SimGrid, just erase it, and
 188 recompile and relaunch your program.