/**

\page tutorial-install-iOS Tutorial: Installation from source for iOS devices
\tableofcontents

In this tutorial you will learn how to build ViSP framework from source on OSX in order to use it for iOS developments. These steps have been tested on macOS Big Sur 11.6.2, with CMake 3.22.1, Xcode 13.2.1 and Python 2.7.16 or Python 3.9.9.

\note Concerning ViSP installation, we provide also other \ref tutorial.

\section install_iOS_required Install required software

- CMake gui for OSX that could be download at : http://www.cmake.org or installed using `brew install cmake`
- Xcode
- Python 2.7 or Python 3 installed using `brew install python`

\section install_iOS_opencv Getting OpenCV framework (optional)

We suggest to follow these steps in order to install OpenCV framework in such a way that the resulting ViSP framework builds with OpenCV as 3rd party. This could be useful for users who want to use ViSP and OpenCV together. It will also allow to exploit keypoints throw ViSP classes (vpKltOpencv, vpKeyPoint) or the model-based tracker in his hybrid version (vpMbKltTracker). If you are not interested in capabilities leveraged by using OpenCV as 3rd party, just skip this section.

- Download the latest <a href="https://opencv.org/releases">OpenCV for iOS</a> like `opencv-4.5.5-ios-framework.zip`
- Unzip the archive in a directory denoted `<framework_dir>/ios`. If `<framework_dir>` is for example the following folder `$HOME/framework` just do the following:
\verbatim
$ mkdir -p $HOME/framework/ios
\endverbatim
If the download was performed with Safari, do the following
\verbatim
$ mv $HOME/Downloads/opencv2.framework $HOME/framework/ios/
\endverbatim
or if the download was either performed with Firefox, do the following
\verbatim
$ unzip $HOME/Downloads/opencv-4.5.5-ios-framework.zip -d $HOME/framework/ios
\endverbatim
- Add `opencv2.framework` to iPhoneOS existing frameworks
\verbatim
$ cd `xcrun --sdk iphoneos --show-sdk-platform-path`/Developer/Library/Frameworks
$ sudo ln -s ~/framework/ios/opencv2.framework
\endverbatim
- Add `opencv2.framework` to iPhoneSimulator existing frameworks
\verbatim
$ cd `xcrun --sdk iphonesimulator --show-sdk-platform-path`/Developer/Library/Frameworks
$ sudo ln -s ~/framework/ios/opencv2.framework
\endverbatim

\note If you encounter an error with `xcrun`, check \ref install_iOS_know_issue_xcrun

\section install_iOS_get_source Getting ViSP source code

\note The following steps are only working with ViSP 3.0.1 or higher.

Here the goal is to get ViSP source code in a directory denoted `<framework_dir>`. If `<framework_dir>` is for example the following folder `$HOME/framework` there are different ways to get ViSP:

- You can get the cutting-edge ViSP from <a href="https://github.com/lagadic/visp">GitHub repository</a> using the following command
\verbatim
$ cd $HOME/framework
$ git clone https://github.com/lagadic/visp.git
\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 $HOME/framework
\endverbatim

- Or 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 $HOME/framework
\endverbatim
or
\verbatim
$ unzip visp-x.y.z.zip -d $HOME/framework
\endverbatim

- We suppose now that ViSP source is in a directory denoted `<framework_dir>` besides ios folder.
\verbatim
$ ls $HOME/framework
ios  visp
\endverbatim

\section install_iOS_build Building ViSP framework

- Build ViSP framework
\verbatim
$ cd $HOME/framework
$ python3 visp/platforms/ios/build_framework.py ios
\endverbatim

- Once build, you will have `$HOME/framework/ios/visp3.framework` that could be added to a Xcode project for iOS devices. If you follow \ref install_iOS_opencv you have also `$HOME/framework/ios/opencv2.framework` that should also be added to the Xcode project.
\verbatim
$ ls $HOME/framework/ios
build			opencv2.framework	visp3.framework
\endverbatim

- There is also the possibility to build ViSP framework specifying the deployment target and the arch
\verbatim
$ cd $HOME/framework
$ python3 visp/platforms/ios/build_framework.py ios --iphoneos_deployment_target 11.0 --iphoneos_archs arm64 --build_only_specified_archs True
\endverbatim

\note ViSP framework is build with capabilities that enables the usage of the following 3rd parties: XML, OpenCV, pthread, apriltag, lapack.

\section install_iOS_know_issue Known issues
\subsection install_iOS_know_issue_xcrun xcrun: error: SDK cannot be located

If you encounter the following issue:
\verbatim
$ cd `xcrun --sdk iphoneos --show-sdk-platform-path`/Developer/Library/Frameworks
xcrun: error: SDK "iphoneos" cannot be located
xcrun: error: SDK "iphoneos" cannot be located
xcrun: error: unable to lookup item 'PlatformPath' in SDK 'iphoneos'
-bash: cd: /Developer/Library/Frameworks: No such file or directory
\endverbatim
It means that the Xcode command line tools are not installed.

Launch `Xcode` and go to Preferences, then Locations, and make sure the command line tools is set to the version of Xcode you’re using.

\image html img-xcode-cmdline-tools.jpg

\section install_iOS_next Next tutorial

You are now ready to see the next \ref tutorial-getting-started-iOS that shows how to use ViSP as a 3rd party to build your own project for iOS devices.

*/
