/**

\page tutorial-create-android-sdk Tutorial: Building ViSP SDK for Android
\tableofcontents

\section android_sdk_intro 1. Introduction
This tutorial is designed to help you build ViSP Android SDK which can be used to create Android Apps supporting ViSP
Java functionalities.

\section android_sdk_ws 2. Create a workspace

\subsection java_sdk_ws_unix 2.1. On Ubuntu, Debian or Mac OSX

First create a workspace in `$HOME/visp-ws` that will contain ViSP sources, build and dataset.
\code{.sh}
$ export VISP_WS=$HOME/visp-ws
$ mkdir -p $VISP_WS/3rdparty
\endcode

\subsection java_sdk_ws_win 2.2. On Windows

Follow instructions to \ref install_win11_msvc17_ws on Windows.

We suppose now that you have set `%%VISP_WS%` var.

\section android_sdk_prereq 3. Prerequisites

This tutorial assumes you have the following software installed and configured:
<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development Kit (JDK)</a>,
<a href="https://developer.android.com/studio/">Android SDK and NDK</a>,
<a href="https://www.python.org/downloads/">Python Interpreter</a>,
<a href="https://ant.apache.org/bindownload.cgi">Apache Ant</a>,
<a href="https://cmake.org/download/">CMake</a>,
<a href="https://github.com/ninja-build/ninja/releases">Ninja</a> and
<a href="https://ccache.samba.org/">ccache</a>.

\subsection android_sdk_prereq_linux 3.1. On Ubuntu or debian

- Install <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development Kit (JDK)</a>
  following \ref java_install_jdk tutorial.
  \note At the time this tutorial was updated `"Java SE Development Kit 21"` was used.
- To install <a href="https://developer.android.com/studio/">Android SDK and NDK</a> follow the link to
  <a href="https://developer.android.com/studio/">Android Studio</a>, download and install Android Studio.
  Once installed start Android Studio using default settings. This allows to download Android SDK that will be installed
  in `$HOME/Android/Sdk` on Ubuntu.

  Now to install Android NDK, open Android Studio and start a new Native C++ Android project using the default
  configuration.
  \image html img-android-mac-native-c++.jpg

  From this new project enter `"File > Settings... > Languages & Frameworks > Android SDK"` menu.
  Select the `"SDK Tools"` tab and check the boxes next to `"Android SDK Build-Tools"`, `"NDK (Side by side)"`
  and `"CMake"`.
  \image html img-android-mac-install-ndk.jpg

  As visible in the previous and next images, we will download and install NDK 28.
  Confirm changes pressing "OK" button.
  \image html img-android-mac-install-ndk-confirm.jpg

  Once all the tools are downloaded, you can exit Android Studio.
- Now to install <a href="https://www.python.org/downloads/">Python Interpreter (prefer version 3.x)</a>,
  <a href="https://cmake.org/download/">CMake</a>, <a href="https://github.com/ninja-build/ninja/releases">Ninja</a>
  and <a href="https://ccache.samba.org/">ccache</a> (a compiler cache for a faster build) run the following:
\code{.sh}
$ sudo apt-get install python3 ant cmake-curses-gui ninja-build ccache
\endcode

- At the time this tutorial was written, on Ubuntu 24.04 LTS we got Android Studio BumbleBee 2024.2.14,
  NDK 28.0 (see \ref android_sdk_ndk_version) and the following other tools versions:
\code{.sh}
$ java --version
java 21.0.6 2025-01-21 LTS
$ python3 --version
Python 3.12.7
$ ant -version
Apache Ant(TM) version 1.10.14 compiled on September 25 2023
$ cmake -version
cmake version 3.28.3
$ ninja --version
1.11.1
$ ccache --version
ccache version 4.9.1
\endcode

\subsection android_sdk_prereq_osx 3.2. On Mac OSX

- Install <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development Kit (JDK)</a>
  following \ref java_install_jdk tutorial.
- To install <a href="https://developer.android.com/studio/">Android SDK and NDK</a> follow the link to
  <a href="https://developer.android.com/studio/">Android Studio</a>, download and install Android Studio from dmg.
  Once installed start Android Studio using default settings. This allows to download Android SDK that will
  be installed in `$HOME/Library/Android/sdk` folder on OSX.

  Now to install Android NDK, open Android Studio and start a new Native C++ Android project using the default
  configuration.
  \image html img-android-mac-native-c++.jpg

  From this new project enter `"Android Studio > Settings... > Languages & Frameworks > Android SDK"` menu.
  Select the `"SDK Tools"` tab and check the boxes next to `"Android SDK Build-Tools"`, `"NDK (Side by side)"`
  and `"CMake"`.
  \image html img-android-mac-install-ndk.jpg

  As visible in the previous and next images, we will download and install NDK 28.
  Confirm changes pressing "OK" button.
  \image html img-android-mac-install-ndk-confirm.jpg

  Once all the tools are downloaded, you can exit Android Studio.
- Now to install <a href="https://www.python.org/downloads/">Python Interpreter (prefer versions 3.x)</a>,
  <a href="https://cmake.org/download/">CMake</a>,
  <a href="https://github.com/ninja-build/ninja/releases">Ninja</a>
  and <a href="https://ccache.samba.org/">ccache</a> (a compiler cache for a faster build) run the following:
\code{.sh}
$ brew install python3 ant cmake ninja ccache
\endcode

- At the time this tutorial was written, on macOS Sequoia 15.3.1 we got Android Studio Ladybug 2024.2.2.13, NDK 28.0
  (see \ref android_sdk_ndk_version) and the following other tools versions:
\code{.sh}
$ java --version
java version "23.0.2" 2025-01-21
$ python3 --version
Python 3.10.13
$ ant -version
Apache Ant(TM) version 1.10.15 compiled on August 25 2024
$ cmake -version
cmake version 3.31.5
$ ninja --version
1.12.1
$ ccache --version
ccache version 4.10.2
\endcode

\subsection android_sdk_prereq_win 3.3. On Windows

- Install <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development Kit (JDK)</a>
  following \ref java_install_jdk tutorial.
- To install <a href="https://developer.android.com/studio/">Android SDK and NDK</a> follow the link to
  <a href="https://developer.android.com/studio/">Android Studio</a>,
  download and install Android Studio for Windows 64-bit.
  Once installed start Android Studio using default settings. This allows to download Android SDK that will
  be installed in `"C:\Users\username\AppData\Local\Android\Sdk"` folder on Windows.

  Now to install Android NDK, open Android Studio and start a new Native C++ Android project using the default
  configuration.
  \image html img-android-mac-native-c++.jpg

  From this new project enter `"File > Settings... > Languages & Frameworks > Android SDK"` menu.
  Select the `"SDK Tools"` tab and check the boxes next to `"Android SDK Build-Tools"`, `"NDK (Side by side)"`
  and `"CMake"`.
  \image html img-android-mac-install-ndk.jpg

  As visible in the previous and next images, we will download and install NDK 28.
  Confirm changes pressing "OK" button.
  \image html img-android-mac-install-ndk-confirm.jpg

  Once all the tools are downloaded, you can exit Android Studio.
- Now install <a href="https://www.python.org/downloads/">Python Interpreter</a> without forgetting to add Python to
  environment variables.
  \image html img-android-python-path.jpg
- Download and install latest <a href="https://cmake.org/download/">CMake release</a> using Windows win64-x64 installer
  without forgetting to add CMake to the system PATH for all users.
- Download <a href="https://github.com/ninja-build/ninja/releases">Ninja</a> for windows. Place `ninja.exe` in a
  suitable spot. For example, in `%%VISP_WS%\3rdparty\ninja-win`. Now make sure that CMake can find `ninja.exe` by adding
  `%%VISP_WS%\3rdparty\ninja-win` to your `%%Path%` environment var.
- Download `ccache` for Windows from github and add its location (`%%VISP_WS%\3rdparty\ccache-win64`) to your `%%Path%`
  environment variable
\code{.sh}
C:\> cd %VISP_WS%/3rdparty
C:\> git clone https://github.com/nagayasu-shinya/ccache-win64.git
\endcode

- At the time this tutorial was written, on Windows 11 we got Android Studio Ladybug 2024.2.2.13, NDK 28.0
  (see \ref android_sdk_ndk_version) and the following other tools versions:
\code{.sh}
C:\> java -version
java version 23.0.2 2025-01-21
C:\> python --version
Python 3.13.2
C:\> cmake -version
cmake version 4.0.0-rc1
C:\> ninja --version
1.12.1
C:\> ccache --version
ccache version 3.7.4
\endcode

\section android_sdk_get_source 4. Get 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
\code{.sh}
$ tar xvzf visp-x.y.z.tar.gz -C $VISP_WS
\endcode
or
\code{.sh}
$ unzip visp-x.y.z.zip -d $VISP_WS
\endcode

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

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

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`.

\section android_sdk_build 5. Build ViSP Android SDK

\subsection android_sdk_build_overview 5.1. Overview
Note that the scripts for building the SDK are included in the source code.

In the workspace create a build folder
\code{.sh}
$ mkdir $VISP_WS/visp-build-android
\endcode

Enter the directory `$VISP_WS/platforms/android` having the python build script and check which are the command line
options that are available.
\code{.sh}
$ cd $VISP_WS/visp/platforms/android
$ python3 build_sdk.py --help
\endcode

Generally the script has to be used like:
\code{.sh}
$ python3 build_sdk.py --config <ndk-*.config.py> --sdk_path <path-to-Android-Sdk> --ndk_path <path-to-Android-Sdk>/ndk-bundle <installation-directory> <visp-source-code-directory>
\endcode


\note It is possible to directly pass some CMake arguments using the `--additional_cmake_flags` option. The values it
accepts must respect the pattern `NAME_OPT_1=VALUE,NAME_OPT_2=VAL_2`, i.e. it must contain tuples `CMakeOptionName=CmakeOptionValue`
separated by commas (without space). An example of such a command would be:
\code{.sh}
$ mkdir $VISP_WS/visp-build-android
$ cd $VISP_WS/visp/platforms/android
$ python3 build_sdk.py --config ndk-28.config.py --sdk_path $HOME/Android/Sdk --ndk_path $HOME/Android/Sdk/ndk/28.0.13004108 $VISP_WS/visp-build-android $VISP_WS/visp --additional_cmake_flags USE_OPENCV=TRUE,OpenCV_FOUND=ON,OpenCV_VERSION=4.10.0
\endcode

In `$VISP_WS/visp/platforms/android` folder we provide different NDK config files:
\code{.sh}
$ ls ndk-*.config.py
ndk-10.config.py  ndk-17.config.py               ndk-18.config.py  ndk-22.config.py
ndk-16.config.py  ndk-18-api-level-21.config.py  ndk-20.config.py  ndk-23.config.py ndk-28.config.py
\endcode
The file that should be used after `--config` option should match your NDK version (see \ref android_sdk_ndk_version).

Above command will build SDK for multiple Android architectures. If you're aware on what Android architecture you'll be
working on (refer <a href="https://android.gadgethacks.com/how-to/android-basics-see-what-kind-processor-you-have-arm-arm64-x86-0168051/">here</a>),
say `x86_64`, you can do a minimal build by changing contents of `ndk-*.config.py` file
\code{.sh}
ABIs = [
    ABI("5", "x86_64",      None)
]
\endcode
This will speed up the installation process.

Once build ViSP Android SDK will be available in `$VISP_WS/visp-build-android/visp-android-sdk/sdk` folder. Its
content should be similar to the following:
\code{.sh}
$ cd $VISP_WS/visp-build-android/visp-android-sdk/sdk
$ find . -maxdepth 3 -type d
./native
./native/3rdparty
./native/3rdparty/libs
./native/staticlibs
./native/staticlibs/x86_64
./native/staticlibs/arm64-v8a
./native/staticlibs/x86
./native/staticlibs/armeabi-v7a
./native/libs
./native/libs/x86_64
./native/libs/arm64-v8a
./native/libs/x86
./native/libs/armeabi-v7a
./native/jni
./native/jni/abi-armeabi-v7a
./native/jni/include
./native/jni/abi-x86_64
./native/jni/abi-arm64-v8a
./native/jni/abi-x86
./java
./java/src
./java/src/org
./java/javadoc
./java/res
./java/res/values
./etc
./etc/data
./etc/data/robot-simulator
./etc/data/wireframe-simulator
\endcode

\subsection android_sdk_build_linux 5.2. On Linux or Debian

For example, on Ubuntu 20.04 the command might look like
\code{.sh}
$ mkdir $VISP_WS/visp-build-android
$ cd $VISP_WS/visp/platforms/android
$ python3 build_sdk.py --config ndk-28.config.py --sdk_path $HOME/Android/Sdk --ndk_path $HOME/Android/Sdk/ndk/28.0.13004108 $VISP_WS/visp-build-android $VISP_WS/visp
\endcode

\subsection android_sdk_build_osx 5.3. On Mac OSX

For example, on Mac OSX the command might rather look like
\code{.sh}
$ mkdir $VISP_WS/visp-build-android
$ cd $VISP_WS/visp/platforms/android
$ python3 build_sdk.py --config ndk-28.config.py --sdk_path $HOME/Library/Android/sdk --ndk_path $HOME/Library/Android/sdk/ndk/28.0.13004108 $VISP_WS/visp-build-android $VISP_WS/visp
\endcode

\subsection android_sdk_build_win 5.4. On Windows

For example, on Windows the command might rather look like
\code{.sh}
C:\> mkdir %VISP_WS%\visp-build-android
C:\> cd %VISP_WS%\visp\platforms\android
C:\> python3 build_sdk.py --config ndk-23.config.py --sdk_path %USERPROFILE%\AppData\Local\Android\Sdk --ndk_path %USERPROFILE%\AppData\Local\Android\Sdk\ndk\23.1.7779620 %VISP_WS%\visp-build-android %VISP_WS%\visp
\endcode

\subsection android_sdk_build_issue 5.5. Known issue

If you're experiencing problems with `ccache` or if you don't install `ccache`, you can try a build without it adding
`--no_ccache` command line option like the following on Ubuntu:
\code{.sh}
$ python3 build_sdk.py --no_ccache --config ndk-18.config.py --sdk_path $HOME/Android/Sdk --ndk_path $HOME/Android/Sdk/ndk-bundle $VISP_WS/visp-build-android $VISP_WS/visp
\endcode

\section android_sdk_tips 6. Tips & tricks
\subsection android_sdk_ndk_version 6.1. How to know Android NDK version

- Start Android Studio
- on Ubuntu enter `"File > Settings... > Appearance > System Settings"` menu, while on Mac OSX enter
  `"Android Studio > Preferences... > Appearance & Behavior > System Settings"` menu, then select `Android SDK` in the
  left part and select `"SDK Tools"` tab to see which is the NDK version that you are using.
  The following swnapshot shows that NDK 18.1 is used:
\image html img-android-ndk-version-18.1.jpg
  This other snapshot shows that NDK 20.0 is used:
\image html img-android-ndk-version-20.0.jpg
  This other snapshot taken on Ubuntu 20.04 with Android Studio 4.1.2 shows that NDK 22.0 is used:
\image html img-android-ndk-version-22.0.jpg

\section android_sdk_next 7. Next tutorial

You are now ready to follow \ref tutorial-android-getting-started where you'll be creating a sample Android App using
ViSP SDK.

*/
