doc/install.doc

   1 /*! \page install Java Binding
   2
   3 \section bindings_binding_java_install How to install Simgrid-java
   4
   5 To use java with Simgrid you have to install some dependencies:
   6  \li Simgrid (see <a href="http://simgrid.gforge.inria.fr/simgrid/latest/doc/install.html">install
   7      Simgrid</a>). You should set the SIMGRID_ROOT environment
   8      variable to the path where you installed SimGrid.
   9  \li Java JDK packages, such as openjdk7 or sun-java6-jdk (with
  10      libgcj10-dev or another version of gcj). For maximal performance
  11      and scalability, use a coroutine-enabled JVM (see
  12      \ref bindings_binding_java_coroutines).
  13
  14 Then Download and install package Simgrid-java:
  15 \verbatim
  16 git clone git://scm.gforge.inria.fr/simgrid/simgrid-java.git
  17 cd simgrid-java
  18 cmake -DCMAKE_INSTALL_PREFIX=$HOME/Install/simgrid-java/ .
  19 make install
  20 \endverbatim
  21
  22 Cmake output
  23 \verbatim
  24 -- SITE        : Linux_2.6.38-8-generic_x86_64
  25 -- BUILDNAME   : Simgrid-Java
  26 -- Looking for lib SimGrid
  27 -- Looking for lib SimGrid - found
  28 -- Simgrid version : 3.8.1
  29 -- Looking for gras.h
  30 -- Looking for gras.h - found
  31 -- Found Tesh: /home/user/Bureau/simgrid/git/bin/tesh
  32 -- Found gras_stub_generator: /home/user/Bureau/simgrid/git/bin/gras_stub_generator
  33 -- Java version 1.6.0.22 configured successfully!
  34 -- Looking for jni.h
  35 -- Looking for jni.h - found
  36 -- Add flags -I/usr/lib/jvm/java-6-openjdk/include
  37 -- Looking for jni_md.h
  38 -- Looking for jni_md.h - found
  39 -- Found javac: /usr/bin/javac
  40 -- Found jar: /usr/bin/jar
  41 -- Configuring done
  42 -- Generating done
  43 -- Build files have been written to: /home/user/workspace/simgrid-java/build
  44 \endverbatim
  45
  46 If cmake complains that <b>jni could not be found</b>, you need to
  47 tell it where JNI header files are located. the following command
  48 should tell you:
  49
  50 \verbatim
  51 $ locate jni.h
  52 /usr/lib/jvm/java-6-openjdk-amd64/include/jni.h
  53 /usr/lib/jvm/java-7-openjdk-amd64/include/jni.h
  54 \endverbatim
  55
  56 If you have several version of jni installed (as in the example
  57 above), you need to check the version of java that is used by default
  58 on your machine (using javac -version), and pick the right one. Then
  59 set the JAVA_INCLUDE_PATH environment variable to the right path (note
  60 that we remove the filename jni.h from that path), and relaunch cmake.
  61
  62 \verbatim
  63 $ export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-6-openjdk-amd64/include/
  64 $ cmake .
  65 \endverbatim
  66
  67 \section bindings_binding_java_use How to use Simgrid-java
  68
  69 To execute the examples you need to add the path where you installed
  70 the generated libSG_java library (<build_dir>/lib) and libsimgrid
  71 ($SIMGRID_ROOT/lib) into the LD_LIBRARY_PATH.
  72
  73 Be careful on Mac, this variable is called DYLD_LIBRARY_PATH and not
  74 LD_LIBRARY_PATH.
  75
  76 \verbatim
  77 $ export SIMGRID_ROOT="$HOME/Install/simgrid/" # change it to the path where you installed the SimGrid library
  78 $ export SIMGRID_JAVA_ROOT="$HOME/Install/simgrid-java" # change it to the path where you installed the java bindings of SimGrid
  79 $ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$SIMGRID_ROOT/lib:$SIMGRID_JAVA_ROOT/java
  80 $ cd examples
  81 $ java -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
  82 \endverbatim
  83
  84 If you want to make these settings permanent even after a reboot, you
  85 need to add the export lines into your ~/.bashrc file, or equivalent.
  86
  87
  88
  89
  90 \section bindings_binding_java_coroutines How to use the coroutines context factory
  91
  92 There is two main motivations to use the coroutine variant of SimGrid
  93 Java bindings: it's about 5 times faster than the default thread-based
  94 context factory, and the amount of runnable processes is then only
  95 limited by the amount of RAM that you have. The drawbacks are that it
  96 requires a specific and rather experimental JVM to run, and that this
  97 context factory itself remains a bit experimental so far.
  98
  99 \subsection  bindings_java_coro_install Getting a mlvm JVM
 100
 101 You need to get a patched JVM from <a href="http://ssw.jku.at/General/Staff/LS/coro/">here</a>
 102 (many thanks to Lukas Stadler for this work!).
 103
 104 You can either get a prebuilt binary, or recompile your own JVM. Make
 105 sure to get a coro-simple version, as we don't need to serialize nor
 106 migrate stacks in SimGrid. You should be able to follow the README.txt
 107 that you'll get in the repository, but here is how we did it, just in
 108 case. The instructions are given for a debian or Ubuntu box, but I
 109 think you should manage to convert it to your system quite easily.
 110 Finally, if you're really stuck, you can get the version compiled by
 111 Jonathan Rouzaud-Cornabas from his web page. This version is known to
 112 work with SimGrid for sure!
 113 http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz
 114
 115  -# Install mercurial and some dependencies
 116 \verbatim
 117 sudo apt-get install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev
 118 # Grab the forest extension: we need to source-install it
 119 hg clone https://bitbucket.org/gxti/hgforest hgforest \endverbatim
 120 \endverbatim
 121  -# Configure the mercurial extensions: Edit ~/.hgrc and paste the
 122     following lines. Don't forget to change the /path/to/forest.py to
 123     point to where you just downloaded the source.
 124
 125     Forest extension is needed to download the openjdk source code and
 126     patches while the mq line is needed to apply the patches. The
 127     username is needed at the step "preparing the sources", not sure why.
 128 \verbatim
 129 [ui]
 130 username = YouUserameWithoutSpaces
 131 [extensions]
 132 forest=/path/to/forest.py
 133 mq=
 134 \endverbatim
 135  -# Prepare the source code
 136 \verbatim
 137 # create a working directory, and enter it
 138 mkdir davinci; cd davinci
 139
 140 # Grab the sources
 141 hg fclone http://hg.openjdk.java.net/hsx/hotspot-comp sources
 142 # Grab the patches
 143 hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches
 144
 145 # Link the patch directories into the sources
 146 bash patches/make/link-patch-dirs.sh sources patches
 147 # Test wether the previous command worked with
 148 ls -i patches/hotspot/series sources/hotspot/.hg/patches/series
 149 # It should display something like the following.
 150 # (note that both file share the same inode number)
 151 #  9707849 patches/hotspot/series
 152 #  9707849 sources/hotspot/.hg/patches/series
 153
 154
 155 # Specify what to compile.
 156 export davinci=$(pwd) guards="buildable testable coro-simple"
 157 # Apply the patches
 158 sh patches/make/each-patch-repo.sh hg qselect --reapply $guards '$(sh $davinci/patches/make/current-release.sh)'
 159 # Check that it understood that you want the patch applied:
 160 grep GLOBAL_GUARDS patches/make/* -r
 161 # this should display something like the following (maybe amonst other unrelated lines)
 162 # GLOBAL_GUARDS=buildable testable coro-simple
 163 # If this does not work, edit patches/make/Makefile,
 164 #   manually coro-simple to GLOBAL_GUARDS and then
 165 #   rerun the patches/make/each-patch-repo.sh script as earlier
 166
 167
 168 # Finish the setup
 169 (cd patches/make; make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup")
 170 # If this last command failed, check your mercurial config within ~/.hgrc (see above)
 171 \endverbatim
 172  -# Compile it all
 173 \verbatim
 174 unset LD_LIBRARY_PATH
 175 export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/
 176 cd sources
 177 # Check that everything is fine
 178 make sanity
 179 # Go for it (it takes about half an hour on my machine)
 180 make all
 181
 182 # Check that the coroutine library got compiled in
 183 ls sources/build/linux-amd64/classes/java/dyn/
 184 # This should display a bunch of class files. If not, something went wrong, you need to investigate further
 185 \endverbatim
 186
 187 \subsection  bindings_java_coro_use Using coroutine contexts
 188
 189 SimGrid Java will automatically switch to the coroutine context
 190 factory if your JVM support it, so you will just need to execute your
 191 simulation with the correct JVM. The selected context factory gets
 192 displayed automatically.
 193 \verbatim
 194 export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libSG_java.so
 195 cd examples
 196 $PATH_TO_COROUTINE_JVM/java -cp .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml
 197 \endverbatim
 198
 199 Note that you may have to adjust the "coro.stacksPerThread"
 200 configuration option to run large simulations. The default is 100 and
 201 you want to increase it to run more processes.
 202 \verbatim
 203 $ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
 204 \endverbatim
 205
 206 If you reach the point where the creation of new simulated processes
 207 fail with the message "Can't create coroutine object", you may need to
 208 increase the relevant system limit with the following command.
 209 \verbatim
 210 sysctl -w vm.max_map_count = 131072
 211 \endverbatim
 212
 213 The full story is that each coroutine requires two memory maps, and
 214 that Linux puts a limit on the total amount of memory maps that each
 215 process can manage (by default, this limit is often at 65535). Since
 216 the JVM needs a few dozen of such maps on its own (three maps per
 217 dynamic library -- check /proc/the_pid/maps if you don't believe it),
 218 this is enough to create over 30,000 simulated processes. But to go
 219 futher, that limit must be modified.
 220
 221 If you want to make this change permanent on your machine, edit your
 222 /etc/sysctl.conf file. Otherwise, you have to redo it by calling
 223 sysctl after each reboot.
 224
 225  */