docs/source/Start_your_own_project.rst

   1 .. _setup_your_own:
   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 your S4U
  28 project (see below for MPI projects). It builds two simulators from a given set
  29 of source files.
  30
  31 .. code-block:: cmake
  32
  33    cmake_minimum_required(VERSION 2.8.12)
  34    project(MyFirstSimulator)
  35
  36    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")
  37
  38    set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake/Modules/")
  39    find_package(SimGrid REQUIRED)
  40    include_directories(${SimGrid_INCLUDE_DIR})
  41
  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})
  45
  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})
  49
  50
  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.
  60
  61 MPI projects should include ``find_package (MPI)`` in CMakeLists.txt. Then, the
  62 variables ``MPI_C_COMPILER``, ``MPI_CXX_COMPILER``, and ``MPI_Fortran_COMPILER`` should
  63 point to the full path of smpicc, smpicxx, and smpiff respectively.
  64 It is however not advised to set these variables from the CMakeLists.txt file directly.
  65 In addition, you may need to set ``SMPI_PRETEND_CC=1`` to please cmake when it tests the compiler.
  66
  67 .. code-block:: console
  68
  69    $ 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 .
  70
  71
  72 Building your project with Makefile
  73 -----------------------------------
  74
  75 Here is a Makefile that will work if your project is composed of three
  76 C files named ``util.h``, ``util.c`` and ``mysimulator.c``. You should
  77 take it as a starting point, and adapt it to your code. There is
  78 plenty of documentation and tutorials on Makefile if the file's
  79 comments are not enough for you.
  80
  81 .. code-block:: makefile
  82
  83    # The first rule of a Makefile is the default target. It will be built when make is called with no parameter
  84    # Here, we want to build the binary 'mysimulator'
  85    all: mysimulator
  86
  87    # This second rule lists the dependencies of the mysimulator binary
  88    # How this dependencies are linked is described in an implicit rule below
  89    mysimulator: mysimulator.o util.o
  90
  91    # These third give the dependencies of the each source file
  92    mysimulator.o: mysimulator.c util.h # list every .h that you use
  93    util.o: util.c util.h
  94
  95    # Some configuration
  96    SIMGRID_INSTALL_PATH = /opt/simgrid # Where you installed simgrid
  97    CC = gcc                            # Your compiler
  98    WARNING = -Wshadow -Wcast-align -Waggregate-return -Wmissing-prototypes \
  99              -Wmissing-declarations -Wstrict-prototypes -Wmissing-prototypes \
 100              -Wmissing-declarations -Wmissing-noreturn -Wredundant-decls \
 101              -Wnested-externs -Wpointer-arith -Wwrite-strings -finline-functions
 102
 103    # CFLAGS = -g -O0 $(WARNINGS) # Use this line to make debugging easier
 104    CFLAGS = -g -O2 $(WARNINGS) # Use this line to get better performance
 105
 106    # No change should be mandated past that line
 107    #############################################
 108    # The following are implicit rules, used by default to actually build
 109    # the targets for which you listed the dependencies above.
 110
 111    # The blanks before the $(CC) must be a Tab char, not spaces
 112    %: %.o
 113         $(CC) -L$(SIMGRID_INSTALL_PATH)/lib/    $(CFLAGS) $^ -lsimgrid -o $@
 114    %.o: %.c
 115         $(CC) -I$(SIMGRID_INSTALL_PATH)/include $(CFLAGS) -c -o $@ $<
 116
 117    clean:
 118         rm -f *.o *~
 119    .PHONY: clean
 120
 121 Develop in C++ with Eclipse
 122 ----------------------------------------
 123
 124 If you wish to develop your plugin or modify SimGrid using
 125 Eclipse. You have to run cmake and import it as a Makefile project.
 126
 127 Next, you have to activate C++17 in your build settings, add -std=c++17
 128 in the CDT GCC Built-in compiler settings.
 129
 130 .. image:: /img/eclipseScreenShot.png
 131    :align: center
 132
 133 .. _install_yours_troubleshooting:
 134
 135 Troubleshooting your Project Setup
 136 ----------------------------------
 137
 138 Library not found
 139 ^^^^^^^^^^^^^^^^^
 140
 141 When the library cannot be found, you will get such an error message similar to:
 142
 143 .. code-block:: console
 144
 145   $ ./masterworker1: error while loading shared libraries: libsimgrid.so: cannot open shared object file: No such file or directory
 146
 147 To fix this, add the path to where you installed the library to the
 148 ``LD_LIBRARY_PATH`` variable. You can add the following line to your
 149 ``~/.bashrc`` so that it gets executed each time you log into your
 150 computer.
 151
 152 .. code-block:: shell
 153
 154   export LD_LIBRARY_PATH=/opt/simgrid/lib
 155
 156
 157 Many undefined references
 158 ^^^^^^^^^^^^^^^^^^^^^^^^^
 159
 160 .. code-block:: console
 161
 162   masterworker.c:209: undefined reference to `sg_version_check'
 163   (and many other undefined references)
 164
 165 This happens when the linker tries to use the wrong library. Use
 166 ``LD_LIBRARY_PATH`` as in the previous item to provide the path to the
 167 right library.
 168
 169 Only a few undefined references
 170 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 171
 172 Sometimes, the compilation only spits very few "undefined reference"
 173 errors. A possible cause is that the system selected an old version of
 174 the SimGrid library somewhere on your disk.
 175
 176 Discover which version is used with ``ldd name-of-yoursimulator``.
 177 Once you've found the obsolete copy of SimGrid, just erase it, and
 178 recompile and relaunch your program.