doc/doxygen/install_yours.doc

   1 /*! @page install_yours Setup your own project
   2
   3 @tableofcontents
   4
   5 It is not advised to modify the simgrid source code directly, as it
   6 will make it difficult to upgrade to the next version of SimGrid.
   7 Instead, you should create your own working directory somewhere on
   8 your disk (say `/home/joe/MyFirstScheduler/`), and write your code in
   9 there.
  10
  11 Then, you should find a solution to get your code compiled and linked
  12 to the SimGrid library as needed. This page helps you to do so with
  13 several tools:
  14 @ref install_yours_cmake "CMake" and
  15 @ref install_yours_makefile "Makefile."
  16 If you configure your project with a tool that is not listed here,
  17 we'd be glad to hear how you've done that to extend this
  18 documentation.
  19
  20 @section install_yours_cmake Building your project with CMake
  21
  22 Here is a `CMakeLists.txt` that you can use as a starting point for
  23 your project. It builds two simulators from a given set of source files.
  24
  25 @verbatim
  26 project(MyFirstScheduler)
  27
  28 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
  29
  30 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake/Modules/")
  31 find_package(SimGrid REQUIRED)
  32 include_directories(${SimGrid_INCLUDE_DIR})
  33
  34 set(SIMULATOR_SOURCES main.c other.c util.c)
  35 add_executable(my_simulator ${SIMULATOR_SOURCES})
  36 target_link_libraries(my_simulator ${SimGrid_LIBRARY})
  37
  38 set(OTHER_SOURCES blah.c bar.c foo.h)
  39 add_executable(other_xp ${OTHER_SOURCES})
  40 target_link_libraries(other_xp ${SimGrid_LIBRARY})
  41 @endverbatim
  42
  43 For that, you need <a href="https://github.com/simgrid/simgrid/blob/master/FindSimGrid.cmake">FindSimGrid.cmake</a>,
  44 that is located at the root of the SimGrid tree. You can either copy
  45 this file into the `cmake/Modules` directory of your project, or use
  46 the version installed on the disk. Both solutions present advantages
  47 and drawback: if you copy the file, you have to keep it in sync
  48 manually but your project will produce relevant error messages when
  49 trying to compile on a machine where SimGrid is not installed. Please
  50 also refer to the file header for more information.
  51
  52 @section install_yours_makefile Building your project with Makefile
  53
  54 Here is a Makefile that will work if your project is composed of three
  55 C files named @c util.h, @c util.c and @c mysimulator.c. You should
  56 take it as a starting point, and adapt it to your code. There is a
  57 plenty of documentation and tutorial on Makefile if the file's
  58 comments are not enough for you.
  59
  60 @verbatim
  61 # The first rule of a Makefile is the default target. It will be built when make is called with no parameter
  62 # Here, we want to build the binary 'mysimulator'
  63 all: mysimulator
  64
  65 # This second rule lists the dependencies of the mysimulator binary
  66 # How this dependencies are linked is described in an implicit rule below
  67 mysimulator: mysimulator.o util.o
  68
  69 # These third give the dependencies of the each source file
  70 mysimulator.o: mysimulator.c util.h # list every .h that you use
  71 util.o: util.c util.h
  72
  73 # Some configuration
  74 SIMGRID_INSTALL_PATH = /opt/simgrid # Where you installed simgrid
  75 CC = gcc                            # Your compiler
  76 WARNING = -Wshadow -Wcast-align -Waggregate-return -Wmissing-prototypes \
  77           -Wmissing-declarations -Wstrict-prototypes -Wmissing-prototypes \
  78           -Wmissing-declarations -Wmissing-noreturn -Wredundant-decls \
  79           -Wnested-externs -Wpointer-arith -Wwrite-strings -finline-functions
  80
  81 # CFLAGS = -g -O0 $(WARNINGS) # Use this line to make debugging easier
  82 CFLAGS = -g -O2 $(WARNINGS) # Use this line to get better performance
  83
  84 # No change should be mandated past that line
  85 #############################################
  86 # The following are implicit rules, used by default to actually build
  87 # the targets for which you listed the dependencies above.
  88
  89 # The blanks before the $(CC) must be a Tab char, not spaces
  90 %: %.o
  91         $(CC) -L$(SIMGRID_INSTALL_PATH)/lib/    $(CFLAGS) $^ -lsimgrid -o $@
  92 %.o: %.c
  93         $(CC) -I$(SIMGRID_INSTALL_PATH)/include $(CFLAGS) -c -o $@ $<
  94
  95 clean:
  96         rm -f *.o *~
  97 .PHONY: clean
  98 @endverbatim
  99
 100 @section install_yours_cppeclipsedevenv Develop in C++ with SimGrid with Eclipse
 101
 102 If you wish to develop your plugin or modify SimGrid using Eclipse. You have to run cmake and import it as a Makefile project.
 103
 104 Next you have to activate C++11 in your build settings, add -std=c++11 in the CDT GCC Built-in compiler settings.
 105
 106 ![Eclipse preference page.](eclipseScreenShot.png)
 107
 108 @section install_yours_javaexample  Building the Java examples in Eclipse
 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 \c 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 @section install_yours_trouble Troubleshooting your project setup
 128
 129 @subsection install_yours_trouble_libpath error while loading shared libraries: libsimgrid.so
 130
 131 Sometimes, the following error message (or similar) will be produced:
 132 @verbatim
 133 ./masterworker1: error while loading shared libraries: libsimgrid.so:
 134 cannot open shared object file: No such file or directory
 135 @endverbatim
 136
 137 The same problem can make the execution of your programs spit pages
 138 and pages of errors similar to the following. If there is only a few
 139 undefined references, then you want to read the next section.
 140 @verbatim
 141 masterworker.c:209: undefined reference to `sg_version_check'
 142 masterworker.c:209: undefined reference to `MSG_init_nocheck'
 143 (and many other undefined references)
 144 @endverbatim
 145
 146 In both cases, it means that the system does not manage to find the
 147 simgrid library when it tries to execute your programs. Under Linux,
 148 specify where to search with the <tt>LD_LIBRARY_PATH</tt> variable.
 149 Try running the following command before executing your code. If it
 150 helps, you should add this line to your ~/.bashrc so that it gets
 151 executed each time you log into your computer.
 152
 153 @verbatim
 154 export LD_LIBRARY_PATH=/opt/simgrid/lib
 155 @endverbatim
 156
 157 @subsection install_yours_trouble_oldlib Only a few undefined references
 158
 159 Sometimes, the compilation only spits very few "undefined reference"
 160 errors. A possible cause is that the system selected an old version of
 161 the SimGrid library somewhere on your disk.
 162
 163 Under Linux, you can find which version was used with the following
 164 command that will display the full path to every used dynamic library.
 165 Once you've found the obsolete copy of SimGrid, just erase it, and
 166 recompile and relaunch your program.
 167 @verbatim ldd yoursimulator
 168 @endverbatim
 169
 170
 171 */