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