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(SIMULATOR_SOURCES main.c other.c util.c)
  31 add_executable(my_simulator ${SIMULATOR_SOURCES})
  32 target_link_libraries(my_simulator simgrid)
  33
  34 set(OTHER_SOURCES blah.c bar.c foo.h)
  35 add_executable(other_xp ${OTHER_SOURCES})
  36 target_link_libraries(other_xp simgrid)
  37 @endverbatim
  38
  39 @section install_yours_makefile Building your project with Makefile
  40
  41 Here is a Makefile that will work if your project is composed of three
  42 C files named @c util.h, @c util.c and @c mysimulator.c. You should
  43 take it as a starting point, and adapt it to your code. There is a
  44 plenty of documentation and tutorial on Makefile if the file's
  45 comments are not enough for you.
  46
  47 @verbatim
  48 # The first rule of a Makefile is the default target. It will be built when make is called with no parameter
  49 # Here, we want to build the binary 'mysimulator'
  50 all: mysimulator
  51
  52 # This second rule lists the dependencies of the mysimulator binary
  53 # How this dependencies are linked is described in an implicit rule below
  54 mysimulator: mysimulator.o util.o
  55
  56 # These third give the dependencies of the each source file
  57 mysimulator.o: mysimulator.c util.h # list every .h that you use
  58 util.o: util.c util.h
  59
  60 # Some configuration
  61 SIMGRID_INSTALL_PATH = /opt/simgrid # Where you installed simgrid
  62 CC = gcc                            # Your compiler
  63 WARNING = -Wshadow -Wcast-align -Waggregate-return -Wmissing-prototypes \
  64           -Wmissing-declarations -Wstrict-prototypes -Wmissing-prototypes \
  65           -Wmissing-declarations -Wmissing-noreturn -Wredundant-decls \
  66           -Wnested-externs -Wpointer-arith -Wwrite-strings -finline-functions
  67
  68 # CFLAGS = -g -O0 $(WARNINGS) # Use this line to make debugging easier
  69 CFLAGS = -g -O2 $(WARNINGS) # Use this line to get better performance
  70
  71 # No change should be mandated past that line
  72 #############################################
  73 # The following are implicit rules, used by default to actually build
  74 # the targets for which you listed the dependencies above.
  75
  76 # The blanks before the $(CC) must be a Tab char, not spaces
  77 %: %.o
  78         $(CC) -L$(SIMGRID_INSTALL_PATH)/lib/    $(CFLAGS) $^ -lsimgrid -o $@
  79 %.o: %.c
  80         $(CC) -I$(SIMGRID_INSTALL_PATH)/include $(CFLAGS) -c -o $@ $<
  81
  82 clean:
  83         rm -f *.o *~
  84 .PHONY: clean
  85 @endverbatim
  86
  87 @section install_yours_trouble Troubleshooting your project setup
  88
  89 @subsection install_yours_trouble_libpath Many undefined references
  90
  91 Sometimes, the following error message (or similar) will be produced.
  92 @verbatim
  93 masterworker.c:209: undefined reference to `sg_version_check'
  94 masterworker.c:209: undefined reference to `MSG_init_nocheck'
  95 (and many other undefined references)
  96 @endverbatim
  97
  98 It means that the system does not manage to find simgrid when it tries
  99 to execute your programs. Specify where to search with the
 100 <tt>LD_LIBRARY_PATH</tt> variable. Try running the following command
 101 before executing your code. If it helps, you should add this line to
 102 your ~/.bashrc so that it gets executed each time you log into your
 103 computer.
 104
 105 @verbatim
 106 export LD_LIBRARY_PATH=/opt/simgrid/lib
 107 @endverbatim
 108
 109 @subsection install_yours_trouble_oldlib Only a few undefined references
 110
 111 Sometimes, the compilation only spits very few "undefined reference"
 112 errors. A possible cause is that the system selected an old version of
 113 the SimGrid library somewhere on your disk.
 114
 115 Under Linux, you can find which version was used with the following
 116 command that will display the full path to every used dynamic library.
 117 Once you've found the obsolete copy of SimGrid, just erase it and
 118 relaunch your program.
 119 @verbatim ldd yoursimulator
 120 @endverbatim
 121
 122
 123 */