/**

\page tutorial-install-java Tutorial: Installing ViSP for Java
\tableofcontents

\section java_intro Introduction

At this point we suppose that you succeed to build ViSP from source following one \ref tutorial_install_src tutorials.

This tutorial will help you to build ViSP from source for Java on your desktop. It shows how to proceed if your desktop is running Linux, OSX or Windows.

\section java_ws Create a workspace

First create a workspace in `$HOME/visp-ws` that will contain ViSP sources, build and dataset.
\verbatim
$ export VISP_WS=$HOME/visp-ws
$ mkdir -p $VISP_WS
\endverbatim

\section java_install_jdk Install Java Development Kit (JDK)

\note At the time this tutorial was updated, the lastest Java SE Development Kit (JDK) is version 17. There is also JDK 15 LTS that could be used. Here we recall \ref java_install_tips_uninstall_jdk if you need to upgrade or downgrade JDK version.

\subsection java_install_jdk_unix On Ubuntu or Debian platform

From the [Oracle](http://www.oracle.com/technetwork/java/javase/downloads/index.html) website, download `jdk-17_linux-x64_bin.tar.gz`. After JDK download and extraction of the files from the archive, you may set `JAVA_HOME` environment var to help `cmake` to detect JDK.
\verbatim
$ cd Downloads
$ tar xvzf jdk-17_linux-x64_bin.tar.gz -C $VISP_WS
$ echo 'export JAVA_HOME=$VISP_VS/jdk-17.0.2' >> ~/.bashrc
$ echo 'export PATH=${JAVA_HOME}/bin:${PATH}' >> ~/.bashrc
$ source ~/.bashrc
\endverbatim

After installation check JDK version:
\verbatim
$ java --version
java 17.0.2 2022-01-18 LTS
\endverbatim

\subsection java_install_jdk_osx On Mac OSX platform

\warning On macOS Catalina 10.15.7 with Xcode 12.4, the installation of JDK 11 or 15 from the [Oracle](http://www.oracle.com/technetwork/java/javase/downloads/index.html) website by downloading and installing `jdk-11.0.10_osx-x64_bin.dmg` or `jdk-15.0.2_osx-x64_bin.dmg` doesn't allow the detection of JNI necessary to build `visp_java.jar`. That's why we recommend to install JDK using brew.
\verbatim
$ more ViSP-third-party.txt
  ...
  Java:
    ant:                         /usr/local/bin/ant (ver 1.10.9)
    JNI:                         no
\endverbatim

\note If you already have an old JDK version you may remove it before installing OpenJDK:
\verbatim
$ ls /Library/Java/JavaVirtualMachines/
jdk-11.0.10.jdk
\endverbatim
Here it shows that `jdk-11.0.10` is installed. To remove this version, see \ref java_install_tips_uninstall_jdk.

To install OpenJDK with brew:

- run:
\verbatim
$ brew install openjdk
\endverbatim

- To know which version is installed:
\verbatim
$ brew info openjdk
openjdk: stable 17.0.1 (bottled) [keg-only]
\endverbatim

- Now for the system Java wrappers to find this JDK, symlink it with:
\verbatim
$ sudo ln -sfn /usr/local/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
\endverbatim

- Set `JAVA_HOME` env var to help JNI headers and libraries detection
\verbatim
$ echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.bashrc
$ source ~/.bashrc
\endverbatim

- After installation check JDK version:
\verbatim
$ java --version
openjdk 17.0.1 2021-10-19
\endverbatim

\subsection java_install_jdk_win On Windows platform

From the [Oracle](http://www.oracle.com/technetwork/java/javase/downloads/index.html) website, download `jdk-17_windows-x64_bin.exe` and run the binary. In order to make `java.exe` available, we had also to add its location `C:\Program Files\Java\jdk-17.0.2\bin` to the `%%PATH%` environment variable.

After installation check JDK version:
\verbatim
C:\> java -version
java version 17.0.2 2022-01-18
\endverbatim

\section java_eclipse Install the latest Eclipse version

Download the latest Eclipse version at the [Eclipse Download page](https://www.eclipse.org/downloads/eclipse-packages/) choosing the <b> Eclipse IDE for Java Developers </b> version. You don’t need to install anything. Extract the downloaded compressed file and put the resulting folder wherever you want to, for example in `$VISP_WS/eclipse`.

\section java_prereq Install Prerequisites

To build ViSP for java you have also to install [CMake](http://www.cmake.org/download/), [Apache Ant](http://ant.apache.org/), and [Python 3](https://www.python.org/downloads/). If you don’t have any of these do the following:

- On Ubuntu/Debian you may run:
\verbatim
$ sudo apt-get install cmake-curses-gui ant python3
\endverbatim

- On Fedora/CentOS you may run:
\verbatim
$ sudo dnf install gcc-c++ cmake ant python3
\endverbatim

- On MacOS/OSX you may run:
\verbatim
$ brew install cmake ant python3
\endverbatim

- On Windows,
  - Download the latest CMake release for Windows win64-x64 platform from http://www.cmake.org. At the time this tutorial was written it was the file cmake-3.22.1-windows-x86_64.msi. To install just double click on the msi file.
  - Download the latest Python 3 release for Windows from https://www.python.org/downloads/. At the time this tutorial was written, it was Python 3.10.2.
  - There is also Apache Ant that is needed. It comes with Eclipse installation, thus here we need to set `ANT_DIR` environment variable to help `ant.bat` file detection by ViSP. You can determine the location easely entering Eclipse installation folder:
  \verbatim
  C:\> cd %VISP_WS%\eclipse
  C:\> dir /s /b | findstr /i ant.bat
  C:\visp-ws\eclipse\plugins\org.apache.ant_1.10.12.v20211102-1452\bin\ant.bat
  \endverbatim
  and then set `ANT_DIR` accordingly like:
  \verbatim
  C:\> setx ANT_DIR "%VISP_WS%\eclipse\plugins\org.apache.ant_1.10.12.v20211102-1452\bin"
  \endverbatim

\section install_java_visp Build ViSP from source code

\subsection install_java_visp_get_source Getting ViSP source code

There are different ways to get ViSP source code:

- You can download the <a href="https://visp.inria.fr/download">latest release</a> as a zip or a tarball. Once downloaded, uncompress the file using either
\verbatim
$ tar xvzf visp-x.y.z.tar.gz -C $VISP_WS
\endverbatim
or
\verbatim
$ unzip visp-x.y.z.zip -d $VISP_WS
\endverbatim

- You can also download a <a href="https://visp.inria.fr/download#snapshot">daily snapshot</a>. Once downloaded, uncompress the file using
\verbatim
$ tar xvzf visp-snapshot-yyyy-mm-dd.tar.gz -C $VISP_WS
\endverbatim

- Or you get the cutting-edge ViSP from <a href="https://github.com/lagadic/visp">GitHub repository</a> using the following command
\verbatim
$ cd $VISP_WS
$ git clone https://github.com/lagadic/visp.git
\endverbatim

We suppose now that ViSP source is in the directory `$VISP_WS/visp`. The following should be adapted if you downloaded ViSP from a zip or tarball. In that case, the source is rather in something like `$VISP_WS/visp-x.y.z`.

\subsection install_java_visp_config Configuring ViSP from source

- In the workspace, create first a directory named `visp-build` that will contain all the build material; generated Makefiles or Visual Studio Solution files, object files, output libraries and binaries once build is done, and in a second stage configure ViSP using CMake.
  - **On Ubuntu/Debian like and on macOS**
\verbatim
$ mkdir $VISP_WS/visp-build
$ cd $VISP_WS/visp-build
$ cmake ../visp
\endverbatim
  - **On Windows**
\verbatim
C:\> mkdir %VISP_WS%\visp-build
C:\> cd %VISP_WS%\visp-build
C:\> cmake -G "Visual Studio 17 2022" -A "x64" %VISP_WS%\visp
\endverbatim

- At this point, in `$VISP_WS/visp-build/ViSP-third-party.txt` you should find something similar to the following snapshot that shows that `python`, `ant` and `JNI` are found:
  - **On Ubuntu/Debian like**
\verbatim
$ more ViSP-third-party.txt
==========================================================
General configuration information for ViSP 3.4.1

  Version control:               v3.4.0-327-g4f1a80bfa-dirty

  Platform:
    Timestamp:                   2022-01-27T17:32:54Z
    Host:                        Linux 5.4.0-96-generic x86_64
    CMake:                       3.16.3
    CMake generator:             Unix Makefiles
    CMake build tool:            /usr/bin/make
    Configuration:               Release

  C/C++:
    Built as dynamic libs?:      yes
    C++ Compiler:                /usr/bin/c++  (ver 9.3.0)
    C++ flags (Release):         -Wall -Wextra -fopenmp -std=c++14 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O3 -DNDEBUG
    C++ flags (Debug):           -Wall -Wextra -fopenmp -std=c++14 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
    C Compiler:                  /usr/bin/cc
    C flags (Release):           -Wall -Wextra -fopenmp -std=c++14 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O3 -DNDEBUG
    C flags (Debug):             -Wall -Wextra -fopenmp -std=c++14 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
    Linker flags (Release):
    Linker flags (Debug):

  ViSP modules:
    To be built:                 core gui imgproc io java_bindings_generator klt me sensor ar blob robot visual_features vs vision detection mbt tt tt_mi java
    Disabled:                    -
    Disabled by dependency:      -
    Unavailable:                 -

  Python (for build):            /usr/bin/python3.8

  Java:
    ant:                         /usr/bin/ant (ver 1.10.7)
    JNI:                         $VISP_WS/jdk-17.0.2/include /home/rainbow/soft/java/jdk-17.0.2/include/linux /home/rainbow/soft/java/jdk-17.0.2/include
\endverbatim

  - **On macOS**
\verbatim
$ more ViSP-third-party.txt
==========================================================
General configuration information for ViSP 3.4.1

  Version control:               v3.4.0-328-g011e5bc43-dirty

  Platform:
    Timestamp:                   2022-01-28T07:18:34Z
    Host:                        Darwin 20.6.0 x86_64
    CMake:                       3.22.2
    CMake generator:             Unix Makefiles
    CMake build tool:            /usr/bin/make
    Configuration:               Release

  C/C++:
    Built as dynamic libs?:      yes
    C++ Compiler:                /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++  (ver 13.0.0.13000029)
    C++ flags (Release):         -Wall -Wextra -Xclang -fopenmp -std=c++14 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O3 -DNDEBUG
    C++ flags (Debug):           -Wall -Wextra -Xclang -fopenmp -std=c++14 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
    C Compiler:                  /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/cc
    C flags (Release):           -Wall -Wextra -Xclang -fopenmp -std=c++14 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -O3 -DNDEBUG
    C flags (Debug):             -Wall -Wextra -Xclang -fopenmp -std=c++14 -fvisibility=hidden -msse2 -msse3 -mssse3 -fPIC -g
    Linker flags (Release):
    Linker flags (Debug):

  ViSP modules:
    To be built:                 core gui imgproc io java_bindings_generator klt me sensor ar blob robot visual_features vs vision detection mbt tt tt_mi java
    Disabled:                    -
    Disabled by dependency:      -
    Unavailable:                 -

  Python (for build):            /usr/bin/python

  Java:
    ant:                         /usr/local/bin/ant (ver 1.10.12)
    JNI:                         /usr/local/Cellar/openjdk/17.0.1_1/libexec/openjdk.jdk/Contents/Home/include /usr/local/Cellar/openjdk/17.0.1_1/libexec/openjdk.jdk/Contents/Home/include/darwin /usr/local/Cellar/openjdk/17.0.1_1/libexec/openjdk.jdk/Contents/Home/include
\endverbatim

  - **On Windows**
\verbatim
C:\> type ViSP-third-party.txt
==========================================================
General configuration information for ViSP 3.4.1

  Version control:               v3.4.0-334-g43ca93e97

  Platform:
    Timestamp:                   2022-01-29T16:07:10Z
    Host:                        Windows 10.0.17763 AMD64
    CMake:                       3.22.1
    CMake generator:             Visual Studio 17 2022
    CMake build tool:            C:/Program Files/Microsoft Visual Studio/2022/Community/MSBuild/Current/Bin/amd64/MSBuild.exe
    MSVC:                        1930

  C/C++:
    Built as dynamic libs?:      yes
    C++ Compiler:                C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.30.30705/bin/Hostx64/x64/cl.exe  (ver 19.30.30706.0)
    C++ flags (Release):         /DWIN32 /D_WINDOWS /W3 /GR /EHsc /MP3   /EHa -openmp /Gy /bigobj /MD /O2 /Ob2 /DNDEBUG
    C++ flags (Debug):           /DWIN32 /D_WINDOWS /W3 /GR /EHsc /MP3   /EHa -openmp /Gy /bigobj /MDd /Zi /Ob0 /Od /RTC1
    C Compiler:                  C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.30.30705/bin/Hostx64/x64/cl.exe
    C flags (Release):           /DWIN32 /D_WINDOWS /W3   /MP3   /EHa -openmp /MD /O2 /Ob2 /DNDEBUG
    C flags (Debug):             /DWIN32 /D_WINDOWS /W3   /MP3   /EHa -openmp /MDd /Zi /Ob0 /Od /RTC1
    Linker flags (Release):      /machine:x64 /INCREMENTAL:NO
    Linker flags (Debug):        /machine:x64 /debug /INCREMENTAL /ignore:4099

  ViSP modules:
    To be built:                 core gui imgproc io java_bindings_generator klt me sensor ar blob robot visual_features vs vision detection mbt tt tt_mi java
    Disabled:                    -
    Disabled by dependency:      -
    Unavailable:                 -

  Windows RT support:            no

  Python (for build):            C:/Users/chercheur/AppData/Local/Programs/Python/Python310/python.exe

  Java:
    ant:                         C:/visp-ws/eclipse/plugins/org.apache.ant_1.10.12.v20211102-1452/bin/ant.bat (ver 1.10.12)
    JNI:                         C:/Program Files/Java/jdk-17.0.2/include C:/Program Files/Java/jdk-17.0.2/include/win32 C:/Program Files/Java/jdk-17.0.2/include
\endverbatim

  \note If JNI is not found (ie. the line starting with `JNI:` is empty), we recommend to do a fresh build removing all the files in the build folder and configuring again from scratch with CMake.

\subsection install_java_visp_build Building ViSP libraries

Depending on you platform, you can now build `visp_java` module:

- **On Ubuntu/Debian like, proceed with:**
\verbatim
$ cd $VISP_WS/visp-build
$ make -j$(nproc) visp_java
\endverbatim

- **On macOS, proceed with:**
\verbatim
$ cd $VISP_WS/visp-build
$ make -j$(sysctl -n hw.ncpu) visp_java
\endverbatim

- **On Windows, proceed with:**
\verbatim
C:\> cd %VISP_WS%\visp-build
C:\> cmake --build . --config Release --target visp_java
\endverbatim

Note that ViSP Java ARchive is now available in `$VISP_WS/visp-build/bin/visp-340.jar`.

\section set_up_visp_java_eclipse Setting Up ViSP Java in Eclipse

\subsection create_user_library Creating a user library

Open Eclipse and select a workspace location of your choice, for example in `$VISP_WS/eclipse/eclipse-workspace` and press `Launch` button.

\image html img-tutorial-java-eclipse-workspace.jpg

Now we propose to create a ViSP user library ready to be used on all your next Java projects. To this end,
- if you are on OS X enter `"Eclipse > Preferences..."` menu
- otherwise enter `"Window > Preferences"` menu:
\image html img-tutorial-java-eclipse1.jpeg Open Preferences panel in Eclipse

In the Preferences panel navigate under `"Java > Build Path > User Libraries"` and choose **New**. Enter a name for the library (e.g visp) and press **OK** button.

\image html img-tutorial-java-eclipse2.jpeg Create a new User Library

Press `"Add External JARs"` button, browse to select <b>`$VISP_WS/visp-build/bin/visp-350.jar`</b> from your computer. After adding the jar, select `"Native library location"`, press first `"Edit"`, press `"External Folder"`, browse to select the folder <b>`$VISP-WS/visp_build/lib`</b> containing ViSP libraries and finally press **OK** button. We recall that the libraries have the extension <b>.so</b> in linux, <b>.dylib</b> in MacOS and <b>.dll</b> in Windows.

\image html img-tutorial-java-eclipse3.jpeg Add jar and native libraries to User Library

Once done, press `"Apply and Close"` button.

\section java_install_tips Tips & Tricks

\subsection java_install_tips_uninstall_jdk How to uninstall JDK

Here we give here some tips to uninstall JDK to be able to downgrade or upgrade JDK version.

- <b>On Ubuntu or Debian platform</b>
  On Ubuntu or Debian platform remove first the folder containing JDK.
\verbatim
$ rm -rf $VISP_VS/jdk-11.0.6
\endverbatim
  Then in `~/.bashrc` remove any reference to `JAVA_HOME` env var deleting the lines similar to:
\verbatim
export JAVA_HOME=$VISP_VS/jdk-11.0.6
export PATH=${JAVA_HOME}/bin:${PATH}
\endverbatim

- <b>On macOS platform</b>
  To uninstall JDK on Mac OSX, you must have administrator privileges and remove the directory whose name matches the following format: `/Library/Java/JavaVirtualMachines/jdkmajor.minor.macro[_update].jdk`. You can proceed using:
\verbatim
$ sudo mv /Library/Java/JavaVirtualMachines/jdk-13.jdk/ /tmp
\endverbatim
  and/or:
\verbatim
$ sudo mv /Library/Java/JavaVirtualMachines/jdk-12.0.2.jdk/ /tmp
\endverbatim

- <b>On Windows platform</b>
  To uninstall JDK on Windows, click Start menu, select `"Settings > System > Apps & features"`. Select the program to unsinstall like `Java(TM) SE Development Kit 13.0 (64-bit)`, then click its Uninstall button. Respond to the prompts to complete the uninstall.

\subsection java_install_tips_rm_workspace How to delete an Eclipse workspace

To remove existing Eclipse workspaces, enter `"Preferences > General > Startup & Shudown > Workspaces"` menu, select the workspace to remove and press `Remove` button and then `Apply and Close` button.

\image html img-tutorial-java-eclipse-remove-workspace.jpeg

Note that this does not actually delete the files from the system, it simply removes it from the list of suggested workspaces. You need to remove the workspace directory by hand.

\section java_install_next Next tutorial

You are now ready to follow \ref tutorial-java-started.

*/