1 /*! \page install Java Binding
3 \section bindings_binding_java_install How to install Simgrid-java
5 To use java with Simgrid you have to install some dependencies:
6 \li Simgrid (see <a href="http://simgrid.gforge.inria.fr/simgrid/3.7/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 sun-java6-jdk (with libgcj10-dev or
10 another version of gcj) or openjdk6. For maximal performance and
11 scalability, use a coroutine-enabled JVM (see
12 \ref bindings_binding_java_coroutines).
14 Then Download and install package Simgrid-java:
16 git clone git://scm.gforge.inria.fr/simgrid/simgrid-java.git
18 cmake -DCMAKE_INSTALL_PREFIX=$HOME/Install/simgrid-java/ .
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.6
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!
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
43 -- Build files have been written to: /home/user/workspace/simgrid-java/build
46 \section bindings_binding_java_use How to use Simgrid-java
48 To execute the examples you need to add the path where you installed
49 the generated libSG_java library (<build_dir>/lib) and libsimgrid
50 ($SIMGRID_ROOT/lib) into the LD_LIBRARY_PATH.
52 Be careful on Mac, this variable is called DYLD_LIBRARY_PATH and not
56 $ export SIMGRID_ROOT="$HOME/Install/simgrid/" # change it to the path where you installed the SimGrid library
57 $ export SIMGRID_JAVA_ROOT="$HOME/Install/simgrid-java" # change it to the path where you installed the java bindings of SimGrid
58 $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SIMGRID_ROOT/lib:$SIMGRID_JAVA_ROOT/java
60 $ java -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
63 If you want to make these settings permanent even after a reboot, you
64 need to add the export lines into your ~/.bashrc file, or equivalent.
69 \section bindings_binding_java_coroutines How to use the coroutines context factory
71 There is two main motivations to use the coroutine variant of SimGrid
72 Java bindings: it's about 5 times faster than the default thread-based
73 context factory, and the amount of runnable processes is then only
74 limited by the amount of RAM that you have. The drawbacks are that it
75 requires a specific and rather experimental JVM to run, and that this
76 context factory itself remains a bit experimental so far.
78 \subsection bindings_java_coro_install Getting a mlvm JVM
80 You need to get a patched JVM from <a href="http://ssw.jku.at/General/Staff/LS/coro/">here</a>
81 (many thanks to Lukas Stadler for this work!).
83 You can either get a prebuilt binary, or recompile your own JVM. Make
84 sure to get a coro-simple version, as we don't need to serialize nor
85 migrate stacks in SimGrid. You should be able to follow the README.txt
86 that you'll get in the repository, but here is how we did it, just in
87 case. The instructions are given for a debian or Ubuntu box, but I
88 think you should manage to convert it to your system quite easily.
89 Finally, if you're really stuck, you can get the version compiled by
90 Jonathan Rouzaud-Cornabas from his web page. This version is known to
91 work with SimGrid for sure!
92 http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz
94 -# Install mercurial and some dependencies
96 sudo apt-get install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev
97 # Grab the forest extension: we need to source-install it
98 hg clone https://bitbucket.org/gxti/hgforest hgforest \endverbatim
100 -# Configure the mercurial extensions: Edit ~/.hgrc and paste the
101 following lines. Don't forget to change the /path/to/forest.py to
102 point to where you just downloaded the source.
104 Forest extension is needed to download the openjdk source code and
105 patches while the mq line is needed to apply the patches. The
106 username is needed at the step "preparing the sources", not sure why.
109 username = YouUserameWithoutSpaces
111 forest=/path/to/forest.py
114 -# Prepare the source code
116 # create a working directory, and enter it
117 mkdir davinci; cd davinci
120 hg fclone http://hg.openjdk.java.net/hsx/hotspot-comp sources
122 hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches
124 # Link the patch directories into the sources
125 bash patches/make/link-patch-dirs.sh sources patches
126 # Test wether the previous command worked with
127 ls -i patches/hotspot/series sources/hotspot/.hg/patches/series
128 # It should display something like the following.
129 # (note that both file share the same inode number)
130 # 9707849 patches/hotspot/series
131 # 9707849 sources/hotspot/.hg/patches/series
134 # Specify what to compile.
135 export davinci=$(pwd) guards="buildable testable coro-simple"
137 sh patches/make/each-patch-repo.sh hg qselect --reapply $guards '$(sh $davinci/patches/make/current-release.sh)'
138 # Check that it understood that you want the patch applied:
139 grep GLOBAL_GUARDS patches/make/* -r
140 # this should display something like the following (maybe amonst other unrelated lines)
141 # GLOBAL_GUARDS=buildable testable coro-simple
142 # If this does not work, edit patches/make/Makefile,
143 # manually coro-simple to GLOBAL_GUARDS and then
144 # rerun the patches/make/each-patch-repo.sh script as earlier
148 (cd patches/make; make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup")
149 # If this last command failed, check your mercurial config within ~/.hgrc (see above)
153 unset LD_LIBRARY_PATH
154 export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/
156 # Check that everything is fine
158 # Go for it (it takes about half an hour on my machine)
161 # Check that the coroutine library got compiled in
162 ls sources/build/linux-amd64/classes/java/dyn/
163 # This should display a bunch of class files. If not, something went wrong, you need to investigate further
166 \subsection bindings_java_coro_use Using coroutine contexts
168 SimGrid Java will automatically switch to the coroutine context
169 factory if your JVM support it, so you will just need to execute your
170 simulation with the correct JVM. The selected context factory gets
171 displayed automatically.
173 export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libSG_java.so
175 $PATH_TO_COROUTINE_JVM/java -cp .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml
178 Note that you may have to adjust the "coro.stacksPerThread"
179 configuration option to run large simulations. The default is 100 and
180 you want to increase it to run more processes.
182 $ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
185 If you reach the point where the creation of new simulated processes
186 fail with the message "Can't create coroutine object", you may need to
187 increase the relevant system limit with the following command.
189 sysctl -w vm.max_map_count = 131072
192 The full story is that each coroutine requires two memory maps, and
193 that Linux puts a limit on the total amount of memory maps that each
194 process can manage (by default, this limit is often at 65535). Since
195 the JVM needs a few dozen of such maps on its own (three maps per
196 dynamic library -- check /proc/the_pid/maps if you don't believe it),
197 this is enough to create over 30,000 simulated processes. But to go
198 futher, that limit must be modified.
200 If you want to make this change permanent on your machine, edit your
201 /etc/sysctl.conf file. Otherwise, you have to redo it by calling
202 sysctl after each reboot.