/*! \page bindings Bindings
-
-\section bindings_binding_Java Java Binding
-Check online for our specific <a href="http://simgrid.gforge.inria.fr/documentation.html">Simgrid-Java documentation</a>.
-
-\section bindings_binding_Ruby Ruby Binding
-Check online for our specific <a href="http://simgrid.gforge.inria.fr/documentation.html">Simgrid-Ruby documentation</a>.
+\section MSG_Ruby Ruby Binding
+Check online for our specific [Simgrid-Ruby documentation](http://simgrid.gforge.inria.fr/documentation.html).
+
+\section MSG_Java Java Binding
+Simgrid-java is a java API that let you use [Simgrid](http://simgrid.gforge.inria.fr/)
+MSG API in your favorite language (java). Without it, you would be forced to
+use C or one of the other bindings provided.
+
+MSG was the first distributed programming environment provided within SimGrid.
+While almost realistic, it remains quite simple. This describes the Java
+bindings to this interface.
+
+The javadoc is accessible [here](javadoc/index.html)
+
+\subsection bindings_binding_Java_jMSG_who Who should use this (and who shouldn't)
+You should use MSG if you want to study some heuristics for a given problem you
+don't really want to implement. SimGrid-java let you use MSG while coding in
+Java. So if your need is MSG + Java, you're in the right section!
+
+\subsection SimGrid-java Usage overview
+
+To make a long story short, it's a JNI binding, so it implies that:
+- Most of the MSG and SimGrid documentation about behavioral aspects applies
+ directly to what you are programming.
+- MSG data structures are mapped to Java objects. So it means that from the
+ syntax point of view, you have to know how those objects are. Fortunately,
+ we have generated the Javadoc for those objects. So take a look at it
+
+Finally, it implies also that your program can crash for 3 main reasons:
+- Your Java part is not good: you'll have a good old java exception thrown,
+ and hence you should be able to correct it by yourself.
+- Our java part is not good: you'll also have a java exception thrown, but
+ we have real doubts this can happen, since the java part is only a JNI
+ binding. The other option is that it crashed because you used incorrectly
+ the MSG API, so this means also you should have an MSGException. It means
+ you should read carefully MSG samples and/or documentation.
+- Something has crashed in the C part. Okay, here comes the tricky thing.
+
+C crashes mainly for 2 reasons:
+- When something goes wrong in your simulation, sometimes the C part stops
+ because you used SimGrid incorrectly, and JNI bindings are not fond of that.
+ It means that you'll have something that looks ugly, but you should be able
+ to identify what's going wrong in your code by carefully reading the whole
+ error message
+- It may happen that the problem comes directly from SimGrid: in this case,
+ the error should be uglier. In that case, you may submit a bug directly to
+ SimGrid.
+
+\subsection bindings_binding_java_install How to install Simgrid-java
+
+To use java with Simgrid you have to install some dependencies:
+- Java JDK packages, such as `openjdk7` or `sun-java6-jdk` (with `libgcj10-dev` or another
+ version of gcj). For maximal performance and scalability, use a coroutine-enabled JVM (see
+ \ref bindings_binding_java_coroutines).
+
+Then build Simgrid with the Java bindings enabled:
+~~~~{.sh}
+cmake -Denable_java=ON .
+~~~~
+
+If cmake complains that **jni could not be found**, you need to tell it where
+JNI header files are located. the following command should tell you:
+
+~~~~{.sh}
+$ locate jni.h
+/usr/lib/jvm/java-6-openjdk-amd64/include/jni.h
+/usr/lib/jvm/java-7-openjdk-amd64/include/jni.h
+~~~~
+
+If you have several version of jni installed (as in the example
+above), you need to check the version of java that is used by default
+on your machine (using javac -version), and pick the right one. Then
+set the `JAVA_INCLUDE_PATH` environment variable to the right path (note
+that we remove the filename `jni.h` from that path), and relaunch cmake.
+
+~~~~{.sh}
+$ export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-6-openjdk-amd64/include/
+$ cmake .
+~~~~
+
+\subsubsection bindings_binding_java_use How to use Simgrid-java
+
+To execute the examples you need to add the path where you installed
+the generated `libsimgrid-java` and `libsimgrid` libraries
+into the `LD_LIBRARY_PATH`.
+
+Be careful on Mac, this variable is called `DYLD_LIBRARY_PATH` and not
+`LD_LIBRARY_PATH`.
+
+~~~~{.sh}
+$ export SIMGRID_ROOT="$HOME/Install/simgrid/" # change it to the path where you installed the SimGrid library
+$ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$SIMGRID_ROOT/lib
+$ cd examples
+$ java -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
+~~~~
+
+If you want to make these settings permanent even after a reboot, you
+need to add the export lines into your `~/.bashrc` file, or equivalent.
+
+\subsubsection bindings_binding_java_coroutines How to use the coroutines context factory
+
+There is two main motivations to use the coroutine variant of SimGrid
+Java bindings: it's about 5 times faster than the default thread-based
+context factory, and the amount of runnable processes is then only
+limited by the amount of RAM that you have. The drawbacks are that it
+requires a specific and rather experimental JVM to run, and that this
+context factory itself remains a bit experimental so far.
+
+\subsubsection bindings_java_coro_install Getting a mlvm JVM
+
+You need to get a patched JVM from [here](http://ssw.jku.at/General/Staff/LS/coro/)
+(many thanks to Lukas Stadler for this work!).
+
+You can either get a prebuilt binary, or recompile your own JVM. Make
+sure to get a coro-simple version, as we don't need to serialize nor
+migrate stacks in SimGrid. You should be able to follow the `README.txt`
+that you'll get in the repository, but here is how we did it, just in
+case. The instructions are given for a debian or Ubuntu box, but I
+think you should manage to convert it to your system quite easily.
+Finally, if you're really stuck, you can get the version compiled by
+Jonathan Rouzaud-Cornabas from his web page. This version is known to
+work with SimGrid for sure!
+http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz
+
+ -# Install mercurial and some dependencies
+~~~~{.sh}
+sudo apt-get install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev
+# Grab the forest extension: we need to source-install it
+hg clone https://bitbucket.org/gxti/hgforest hgforest \endverbatim
+~~~~
+ -# Configure the mercurial extensions: Edit ~/.hgrc and paste the
+ following lines. Don't forget to change the /path/to/forest.py to
+ point to where you just downloaded the source.
+
+ Forest extension is needed to download the openjdk source code and
+ patches while the mq line is needed to apply the patches. The
+ username is needed at the step "preparing the sources", not sure why.
+~~~~
+[ui]
+username = YouUserameWithoutSpaces
+[extensions]
+forest=/path/to/forest.py
+mq=
+~~~~
+ -# Prepare the source code
+~~~~{.sh}
+# create a working directory, and enter it
+mkdir davinci; cd davinci
+
+# Grab the sources
+hg fclone http://hg.openjdk.java.net/hsx/hotspot-comp sources
+# Grab the patches
+hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches
+
+# Link the patch directories into the sources
+bash patches/make/link-patch-dirs.sh sources patches
+# Test wether the previous command worked with
+ls -i patches/hotspot/series sources/hotspot/.hg/patches/series
+# It should display something like the following.
+# (note that both file share the same inode number)
+# 9707849 patches/hotspot/series
+# 9707849 sources/hotspot/.hg/patches/series
+
+
+# Specify what to compile.
+export davinci=$(pwd) guards="buildable testable coro-simple"
+# Apply the patches
+sh patches/make/each-patch-repo.sh hg qselect --reapply $guards '$(sh $davinci/patches/make/current-release.sh)'
+# Check that it understood that you want the patch applied:
+grep GLOBAL_GUARDS patches/make/* -r
+# this should display something like the following (maybe amonst other unrelated lines)
+# GLOBAL_GUARDS=buildable testable coro-simple
+# If this does not work, edit patches/make/Makefile,
+# manually coro-simple to GLOBAL_GUARDS and then
+# rerun the patches/make/each-patch-repo.sh script as earlier
+
+
+# Finish the setup
+(cd patches/make; make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup")
+# If this last command failed, check your mercurial config within ~/.hgrc (see above)
+~~~~
+ -# Compile it all
+~~~~{.sh}
+unset LD_LIBRARY_PATH
+export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/
+cd sources
+# Check that everything is fine
+make sanity
+# Go for it (it takes about half an hour on my machine)
+make all
+
+# Check that the coroutine library got compiled in
+ls sources/build/linux-amd64/classes/java/dyn/
+# This should display a bunch of class files. If not, something went wrong, you need to investigate further
+~~~~
+
+\subsubsection bindings_java_coro_use Using coroutine contexts
+
+SimGrid Java will automatically switch to the coroutine context
+factory if your JVM support it, so you will just need to execute your
+simulation with the correct JVM. The selected context factory gets
+displayed automatically.
+~~~~{.sh}
+export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libsimgrid-java.so
+cd examples
+$PATH_TO_COROUTINE_JVM/java -cp .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml
+~~~~
+
+Note that you may have to adjust the "coro.stacksPerThread"
+configuration option to run large simulations. The default is 100 and
+you want to increase it to run more processes.
+~~~~{.sh}
+$ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
+~~~~
+
+If you reach the point where the creation of new simulated processes
+fail with the message "Can't create coroutine object", you may need to
+increase the relevant system limit with the following command.
+~~~~{.sh}
+sysctl -w vm.max_map_count = 131072
+~~~~
+
+The full story is that each coroutine requires two memory maps, and
+that Linux puts a limit on the total amount of memory maps that each
+process can manage (by default, this limit is often at 65535). Since
+the JVM needs a few dozen of such maps on its own (three maps per
+dynamic library -- check `/proc/the_pid/maps` if you don't believe it),
+this is enough to create over 30,000 simulated processes. But to go
+futher, that limit must be modified.
+
+If you want to make this change permanent on your machine, edit your
+`/etc/sysctl.conf` file. Otherwise, you have to redo it by calling
+sysctl after each reboot.
\section bindings_binding_lua Lua Binding
Besides Java Binding, Lua and Ruby bindings are available since version 3.4 of Simgrid
for MSG Module, and we are currenlty working on bindings for other modules.
-
\subsection bindings_binding_lua_about What is lua ?
Lua is a lightweight, reflective, imperative and functional programming language,
designed as a scripting language with extensible semantics as a primary goal (see official web site <a href="http://www.lua.org">here</a>).
