Merge pull request #18195 from mshabunin:linux-tutorial

Installation tutorials rework

* Doc: general installation, config reference, linux installation

* Doc: addressed review comments

* Minor fixes

doc/stylesheet.css

@@ -6,12 +6,11 @@ body, table, div, p, dl {
 }
 
 code {
-    font: 12px Consolas, "Liberation Mono", Courier, monospace;
     font-size: 85%;
+    font-family: "SFMono-Regular",Consolas,"Liberation Mono",Menlo,Courier,monospace;
     white-space: pre-wrap;
     padding: 1px 5px;
-    padding: 0;
-    background-color: #ddd;
+    background-color: rgb(223, 229, 241);
     vertical-align: baseline;
 }
 
@@ -20,6 +19,16 @@ body {
     margin: 0 auto;
 }
 
+div.fragment {
+    padding: 3px;
+    padding-bottom: 0px;
+}
+
+div.line {
+    padding-bottom: 3px;
+    font-family: "SFMono-Regular",Consolas,"Liberation Mono",Menlo,Courier,monospace;
+}
+
 div.contents {
     width: 980px;
     margin: 0 auto;
@@ -35,3 +44,11 @@ span.arrow {
 div.image img{
     max-width: 900px;
 }
+
+#projectlogo
+{
+    text-align: center;
+    vertical-align: middle;
+    border-collapse: separate;
+    padding-left: 0.5em;
+}

doc/tutorials/introduction/android_binary_package/O4A_SDK.markdown

@@ -4,6 +4,13 @@ OpenCV4Android SDK {#tutorial_O4A_SDK}
 @prev_tutorial{tutorial_android_dev_intro}
 @next_tutorial{tutorial_dev_with_OCV_on_Android}
 
+|    |    |
+| -: | :- |
+| Original author | Vsevolod Glumov |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial is deprecated.
 
 This tutorial was designed to help you with installation and configuration of OpenCV4Android SDK.
 

doc/tutorials/introduction/android_binary_package/android_dev_intro.markdown

@@ -4,6 +4,14 @@ Introduction into Android Development {#tutorial_android_dev_intro}
 @prev_tutorial{tutorial_clojure_dev_intro}
 @next_tutorial{tutorial_O4A_SDK}
 
+|    |    |
+| -: | :- |
+| Original author | Vsevolod Glumov |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial is deprecated.
+
 
 This guide was designed to help you in learning Android development basics and setting up your
 working environment quickly. It was written with Windows 7 in mind, though it would work with Linux

doc/tutorials/introduction/android_binary_package/android_ocl_intro.markdown

@@ -4,6 +4,13 @@ Use OpenCL in Android camera preview based CV application {#tutorial_android_ocl
 @prev_tutorial{tutorial_dev_with_OCV_on_Android}
 @next_tutorial{tutorial_macos_install}
 
+|    |    |
+| -: | :- |
+| Original author | Andrey Pavlenko |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial is deprecated.
 
 This guide was designed to help you in use of [OpenCL ™](https://www.khronos.org/opencl/) in Android camera preview based CV application.
 It was written for [Eclipse-based ADT tools](http://developer.android.com/tools/help/adt.html)

doc/tutorials/introduction/android_binary_package/dev_with_OCV_on_Android.markdown

@@ -4,6 +4,13 @@ Android Development with OpenCV {#tutorial_dev_with_OCV_on_Android}
 @prev_tutorial{tutorial_O4A_SDK}
 @next_tutorial{tutorial_android_ocl_intro}
 
+|    |    |
+| -: | :- |
+| Original author | Vsevolod Glumov |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial is deprecated.
 
 This tutorial has been created to help you use OpenCV library within your Android project.
 

doc/tutorials/introduction/building_tegra_cuda/building_tegra_cuda.markdown

@@ -4,6 +4,13 @@ Building OpenCV for Tegra with CUDA {#tutorial_building_tegra_cuda}
 @prev_tutorial{tutorial_arm_crosscompile_with_cmake}
 @next_tutorial{tutorial_display_image}
 
+|    |    |
+| -: | :- |
+| Original author |  Randy J. Ray |
+| Compatibility | OpenCV >= 3.1.0 |
+
+@warning
+This tutorial is deprecated.
 
 @tableofcontents
 

doc/tutorials/introduction/clojure_dev_intro/clojure_dev_intro.markdown

@@ -4,6 +4,13 @@ Introduction to OpenCV Development with Clojure {#tutorial_clojure_dev_intro}
 @prev_tutorial{tutorial_java_eclipse}
 @next_tutorial{tutorial_android_dev_intro}
 
+|    |    |
+| -: | :- |
+| Original author | Mimmo Cosenza |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
 
 As of OpenCV 2.4.4, OpenCV supports desktop Java development using nearly the same interface as for
 Android development.

doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown

@@ -3,6 +3,13 @@ Cross referencing OpenCV from other Doxygen projects {#tutorial_cross_referencin
 
 @prev_tutorial{tutorial_transition_guide}
 
+|    |    |
+| -: | :- |
+| Original author | Sebastian Höffner |
+| Compatibility | OpenCV >= 3.3.0 |
+
+@warning
+This tutorial can contain obsolete information.
 
 Cross referencing OpenCV
 ------------------------

doc/tutorials/introduction/crosscompilation/arm_crosscompile_with_cmake.markdown

@@ -4,6 +4,13 @@ Cross compilation for ARM based Linux systems {#tutorial_arm_crosscompile_with_c
 @prev_tutorial{tutorial_ios_install}
 @next_tutorial{tutorial_building_tegra_cuda}
 
+|    |    |
+| -: | :- |
+| Original author |  Alexander Smorkalov |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
 
 This steps are tested on Ubuntu Linux 12.04, but should work for other Linux distributions. I case
 of other distributions package names and names of cross compilation tools may differ. There are

doc/tutorials/introduction/desktop_java/java_dev_intro.markdown

@@ -4,6 +4,13 @@ Introduction to Java Development {#tutorial_java_dev_intro}
 @prev_tutorial{tutorial_windows_visual_studio_image_watch}
 @next_tutorial{tutorial_java_eclipse}
 
+|    |    |
+| -: | :- |
+| Original author | Eric Christiansen and Andrey Pavlenko |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
 
 As of OpenCV 2.4.4, OpenCV supports desktop Java development using nearly the same interface as for
 Android development. This guide will help you to create your first Java (or Scala) application using

doc/tutorials/introduction/display_image/display_image.markdown

@@ -4,6 +4,14 @@ Getting Started with Images {#tutorial_display_image}
 @prev_tutorial{tutorial_building_tegra_cuda}
 @next_tutorial{tutorial_documentation}
 
+|    |    |
+| -: | :- |
+| Original author | Ana Huamán |
+| Compatibility | OpenCV >= 3.4.4 |
+
+@warning
+This tutorial can contain obsolete information.
+
 Goal
 ----
 

doc/tutorials/introduction/documenting_opencv/documentation_tutorial.markdown

@@ -4,6 +4,10 @@ Writing documentation for OpenCV {#tutorial_documentation}
 @prev_tutorial{tutorial_display_image}
 @next_tutorial{tutorial_transition_guide}
 
+|    |    |
+| -: | :- |
+| Original author | Maksim Shabunin |
+| Compatibility | OpenCV >= 3.0 |
 
 @tableofcontents
 

doc/tutorials/introduction/general_install/general_install.markdown

+OpenCV installation overview {#tutorial_general_install}
+============================
+
+@tableofcontents
+
+There are two ways of installing OpenCV on your machine: download prebuilt version for your platform or compile from sources.
+
+# Prebuilt version {#tutorial_general_install_prebuilt}
+
+In many cases you can find prebuilt version of OpenCV that will meet your needs.
+
+## Packages by OpenCV core team  {#tutorial_general_install_prebuilt_core}
+
+Packages for Android, iOS and Windows built with default parameters and recent compilers are published for each release, they do not contain _opencv_contrib_ modules.
+
+- GitHub releases: https://github.com/opencv/opencv/releases
+- SourceForge.net: https://sourceforge.net/projects/opencvlibrary/files/
+
+
+## Third-party packages  {#tutorial_general_install_prebuilt_thirdparty}
+
+Other organizations and people maintain their own binary distributions of OpenCV. For example:
+
+- System packages in popular Linux distributions (https://pkgs.org/search/?q=opencv)
+- PyPI (https://pypi.org/search/?q=opencv)
+- Conda (https://anaconda.org/search?q=opencv)
+- Conan (https://github.com/conan-community/conan-opencv)
+- vcpkg (https://github.com/microsoft/vcpkg/tree/master/ports/opencv)
+- NuGet (https://www.nuget.org/packages?q=opencv)
+- Brew (https://formulae.brew.sh/formula/opencv)
+- Maven (https://search.maven.org/search?q=opencv)
+
+
+# Build from sources {#tutorial_general_install_sources}
+
+It can happen that existing binary packages are not applicable for your use case, then you'll have to build custom version of OpenCV by yourself. This section gives a high-level overview of the build process, check tutorial for specific platform for actual build instructions.
+
+OpenCV uses [CMake](https://cmake.org/) build management system for configuration and build, so this section mostly describes generalized process of building software with CMake.
+
+
+## Step 0: Prerequisites {#tutorial_general_install_sources_0}
+
+Install C++ compiler and build tools. On \*NIX platforms it is usually GCC/G++ or Clang compiler and Make or Ninja build tool. On Windows it can be Visual Studio IDE or MinGW-w64 compiler. Native toolchains for Android are provided in the Android NDK. XCode IDE is used to build software for OSX and iOS platforms.
+
+Install CMake from the official site or some other source.
+
+Get other third-party dependencies: libraries with extra functionality like decoding videos or showing GUI elements; libraries providing optimized implementations of selected algorithms; tools used for documentation generation and other extras. Check @ref tutorial_config_reference for available options and corresponding dependencies.
+
+
+## Step 1: Get software sources {#tutorial_general_install_sources_1}
+
+Typical software project consists of one or several code repositories. OpenCV have two repositories with code: _opencv_ - main repository with stable and actively supported algorithms and _opencv_contrib_ which contains experimental and non-free (patented) algorithms; and one repository with test data: _opencv_extra_.
+
+You can download a snapshot of repository in form of an archive or clone repository with full history.
+
+To download snapshot archives:
+
+- Go to https://github.com/opencv/opencv/releases and download "Source code" archive from any release.
+- (optionally) Go to https://github.com/opencv/opencv_contrib/releases and download "Source code" archive for the same release as _opencv_
+- (optionally) Go to https://github.com/opencv/opencv_extra/releases and download "Source code" archive for the same release as _opencv_
+- Unpack all archives to some location
+
+To clone repositories run the following commands in console (_git_ [must be installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)):
+
+```.sh
+git clone https://github.com/opencv/opencv
+git -C opencv checkout <some-tag>
+
+# optionally
+git clone https://github.com/opencv/opencv_contrib
+git -C opencv_contrib checkout <same-tag-as-opencv>
+
+# optionally
+git clone https://github.com/opencv/opencv_extra
+git -C opencv_extra checkout <same-tag-as-opencv>
+```
+
+@note
+If you want to build software using more than one repository, make sure all components are compatible with each other. For OpenCV it means that _opencv_ and _opencv_contrib_ repositories must be checked out at the same tag or that all snapshot archives are downloaded from the same release.
+
+@note
+When choosing which version to download take in account your target platform and development tools versions, latest versions of OpenCV can have build problems with very old compilers and vice versa. We recommend using latest release and fresh OS/compiler combination.
+
+## Step 2: Configure {#tutorial_general_install_sources_2}
+
+At this step CMake will verify that all necessary tools and dependencies are available and compatible with the library and will generate intermediate files for the chosen build system. It could be Makefiles, IDE projects and solutions, etc. Usually this step is performed in newly created build directory:
+```
+cmake -G<generator> <configuration-options> <source-directory>
+```
+
+@note
+`cmake-gui` application allows to see and modify available options using graphical user interface. See https://cmake.org/runningcmake/ for details.
+
+
+## Step 3: Build {#tutorial_general_install_sources_3}
+
+During build process source files are compiled into object files which are linked together or otherwise combined into libraries and applications. This step can be run using universal command:
+```
+cmake --build <build-directory> <build-options>
+```
+... or underlying build system can be called directly:
+```
+make
+```
+
+## Step 3: Install {#tutorial_general_install_sources_4}
+
+During installation procedure build results and other files from build directory will be copied to the install location. Default installation location is `/usr/local` on UNIX and `C:/Program Files` on Windows. This location can be changed at the configuration step by setting `CMAKE_INSTALL_PREFIX` option. To perform installation run the following command:
+```
+cmake --build <build-directory> --target install <other-options>
+```
+
+@note
+This step is optional, OpenCV can be used directly from the build directory.
+
+@note
+If the installation root location is a protected system directory, so the installation process must be run with superuser or administrator privileges (e.g. `sudo cmake ...`).

doc/tutorials/introduction/ios_install/ios_install.markdown

@@ -4,6 +4,14 @@ Installation in iOS {#tutorial_ios_install}
 @prev_tutorial{tutorial_macos_install}
 @next_tutorial{tutorial_arm_crosscompile_with_cmake}
 
+|    |    |
+| -: | :- |
+| Original author | Artem Myagkov, Eduard Feicho, Steve Nicholson |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
+
 Required Packages
 -----------------
 

doc/tutorials/introduction/java_eclipse/java_eclipse.markdown

@@ -4,6 +4,13 @@ Using OpenCV Java with Eclipse {#tutorial_java_eclipse}
 @prev_tutorial{tutorial_java_dev_intro}
 @next_tutorial{tutorial_clojure_dev_intro}
 
+|    |    |
+| -: | :- |
+| Original author | Barış Evrim Demiröz |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
 
 Since version 2.4.4 [OpenCV supports Java](http://opencv.org/opencv-java-api.html). In this tutorial
 I will explain how to setup development environment for using OpenCV Java with Eclipse in

doc/tutorials/introduction/linux_eclipse/linux_eclipse.markdown

@@ -4,6 +4,14 @@ Using OpenCV with Eclipse (plugin CDT) {#tutorial_linux_eclipse}
 @prev_tutorial{tutorial_linux_gcc_cmake}
 @next_tutorial{tutorial_windows_install}
 
+|    |    |
+| -: | :- |
+| Original author | Ana Huamán |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
+
 Prerequisites
 -------------
 Two ways, one by forming a project directly, and another by CMake Prerequisites

doc/tutorials/introduction/linux_gcc_cmake/linux_gcc_cmake.markdown

@@ -4,6 +4,13 @@ Using OpenCV with gcc and CMake {#tutorial_linux_gcc_cmake}
 @prev_tutorial{tutorial_linux_install}
 @next_tutorial{tutorial_linux_eclipse}
 
+|    |    |
+| -: | :- |
+| Original author | Ana Huamán |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
 
 @note We assume that you have successfully installed OpenCV in your workstation.
 

doc/tutorials/introduction/linux_install/linux_install.markdown

@@ -3,146 +3,123 @@ Installation in Linux {#tutorial_linux_install}
 
 @next_tutorial{tutorial_linux_gcc_cmake}
 
+|    |    |
+| -: | :- |
+| Original author | Ana Huamán |
+| Compatibility | OpenCV >= 3.0 |
+
+@tableofcontents
+
+# Quick start {#tutorial_linux_install_quick_start}
+
+
+## Build core modules {#tutorial_linux_install_quick_build_core}
+
+@snippet linux_quick_install.sh body
+
+
+## Build with opencv_contrib {#tutorial_linux_install_quick_build_contrib}
+
+@snippet linux_quick_install_contrib.sh body
+
+
+# Detailed process {#tutorial_linux_install_detailed}
+
+This section provides more details of the build process and describes alternative methods and tools. Please refer to the @ref tutorial_general_install tutorial for general installation details and to the @ref tutorial_config_reference for configuration options documentation.
+
+
+## Install compiler and build tools {#tutorial_linux_install_detailed_basic_compiler}
+
+- To compile OpenCV you will need a C++ compiler. Usually it is G++/GCC or Clang/LLVM:
+    - Install GCC...
+    @snippet linux_install_a.sh gcc
+    - ... or Clang:
+    @snippet linux_install_b.sh clang
+
+- OpenCV uses CMake build configuration tool:
+@snippet linux_install_a.sh cmake
+
+- CMake can generate scripts for different build systems, e.g. _make_, _ninja_:
+
+    - Install Make...
+    @snippet linux_install_a.sh make
+    - ... or Ninja:
+    @snippet linux_install_b.sh ninja
+
+- Install tool for getting and unpacking sources:
+
+    - _wget_ and _unzip_...
+    @snippet linux_install_a.sh wget
+    - ... or _git_:
+    @snippet linux_install_b.sh git
+
+
+## Download sources {#tutorial_linux_install_detailed_basic_download}
+
+There are two methods of getting OpenCV sources:
+
+- Download snapshot of repository using web browser or any download tool (~80-90Mb) and unpack it...
+@snippet linux_install_a.sh download
+- ... or clone repository to local machine using _git_ to get full change history (>470Mb):
+@snippet linux_install_b.sh download
 
-The following steps have been tested for Ubuntu 10.04 but should work with other distros as well.
-
-Required Packages
------------------
-
--   GCC 4.4.x or later
--   CMake 2.8.7 or higher
--   Git
--   GTK+2.x or higher, including headers (libgtk2.0-dev)
--   pkg-config
--   Python 2.6 or later and Numpy 1.5 or later with developer packages (python-dev, python-numpy)
--   ffmpeg or libav development packages: libavcodec-dev, libavformat-dev, libswscale-dev
--   [optional] libtbb2 libtbb-dev
--   [optional] libdc1394 2.x
--   [optional] libjpeg-dev, libpng-dev, libtiff-dev, libjasper-dev, libdc1394-22-dev
--   [optional] CUDA Toolkit 6.5 or higher
-
-The packages can be installed using a terminal and the following commands or by using Synaptic
-Manager:
-@code{.bash}
-[compiler] sudo apt-get install build-essential
-[required] sudo apt-get install cmake git libgtk2.0-dev pkg-config libavcodec-dev libavformat-dev libswscale-dev
-[optional] sudo apt-get install python-dev python-numpy libtbb2 libtbb-dev libjpeg-dev libpng-dev libtiff-dev libjasper-dev libdc1394-22-dev
-@endcode
-Getting OpenCV Source Code
---------------------------
-
-You can use the latest stable OpenCV version or you can grab the latest snapshot from our [Git
-repository](https://github.com/opencv/opencv.git).
-
-### Getting the Latest Stable OpenCV Version
-
--   Go to our [downloads page](http://opencv.org/releases.html).
--   Download the source archive and unpack it.
-
-### Getting the Cutting-edge OpenCV from the Git Repository
-
-Launch Git client and clone [OpenCV repository](http://github.com/opencv/opencv). If you need
-modules from [OpenCV contrib repository](http://github.com/opencv/opencv_contrib) then clone it as well.
-
-For example
-@code{.bash}
-cd ~/<my_working_directory>
-git clone https://github.com/opencv/opencv.git
-git clone https://github.com/opencv/opencv_contrib.git
-@endcode
-Building OpenCV from Source Using CMake
----------------------------------------
-
--#  Create a temporary directory, which we denote as \<cmake_build_dir\>, where you want to put
-    the generated Makefiles, project files as well the object files and output binaries and enter
-    there.
-
-    For example
-    @code{.bash}
-    cd ~/opencv
-    mkdir build
-    cd build
-    @endcode
--#  Configuring. Run cmake [\<some optional parameters\>] \<path to the OpenCV source directory\>
-
-    For example
-    @code{.bash}
-    cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/usr/local ..
-    @endcode
-    or cmake-gui
-
-    -   set full path to OpenCV source code, e.g. /home/user/opencv
-    -   set full path to \<cmake_build_dir\>, e.g. /home/user/opencv/build
-    -   set optional parameters
-    -   run: “Configure”
-    -   run: “Generate”
-
-    @note
-    Use `cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local ..` , without spaces after -D if the above example doesn't work.
-
--#  Description of some parameters
-    -   build type: `CMAKE_BUILD_TYPE=Release\Debug`
-    -   to build with modules from opencv_contrib set OPENCV_EXTRA_MODULES_PATH to \<path to
-        opencv_contrib/modules/\>
-    -   set BUILD_DOCS for building documents
-    -   set BUILD_EXAMPLES to build all examples
-
--#  [optional] Building python. Set the following python parameters:
-    -   PYTHON2(3)_EXECUTABLE = \<path to python\>
-    -   PYTHON_INCLUDE_DIR = /usr/include/python\<version\>
-    -   PYTHON_INCLUDE_DIR2 = /usr/include/x86_64-linux-gnu/python\<version\>
-    -   PYTHON_LIBRARY = /usr/lib/x86_64-linux-gnu/libpython\<version\>.so
-    -   PYTHON2(3)_NUMPY_INCLUDE_DIRS =
-        /usr/lib/python\<version\>/dist-packages/numpy/core/include/
-
--#  [optional] Building java.
-    -   Unset parameter: BUILD_SHARED_LIBS
-    -   It is useful also to unset BUILD_EXAMPLES, BUILD_TESTS, BUILD_PERF_TESTS - as they all
-        will be statically linked with OpenCV and can take a lot of memory.
-
--#  [optional] Generate pkg-config info
-    -   Add this flag when running CMake: `-DOPENCV_GENERATE_PKGCONFIG=ON`
-    -   Will generate the .pc file for pkg-config and install it.
-    -   Useful if not using CMake in projects that use OpenCV
-    -   Installed as `opencv4`, usage: `pkg-config --cflags --libs opencv4`
-
--#  Build. From build directory execute *make*, it is recommended to do this in several threads
-
-    For example
-    @code{.bash}
-    make -j7 # runs 7 jobs in parallel
-    @endcode
--#  [optional] Building documents. Enter \<cmake_build_dir/doc/\> and run make with target
-    "doxygen"
-
-    For example
-    @code{.bash}
-    cd ~/opencv/build/doc/
-    make -j7 doxygen
-    @endcode
--#  To install libraries, execute the following command from build directory
-    @code{.bash}
-    sudo make install
-    @endcode
--#  [optional] Running tests
-
-    -   Get the required test data from [OpenCV extra
-        repository](https://github.com/opencv/opencv_extra).
-
-    For example
-    @code{.bash}
-    git clone https://github.com/opencv/opencv_extra.git
-    @endcode
-    -   set OPENCV_TEST_DATA_PATH environment variable to \<path to opencv_extra/testdata\>.
-    -   execute tests from build directory.
-
-    For example
-    @code{.bash}
-    <cmake_build_dir>/bin/opencv_test_core
-    @endcode
 
 @note
-   If the size of the created library is a critical issue (like in case of an Android build) you
-    can use the install/strip command to get the smallest size possible. The *stripped* version
-    appears to be twice as small. However, we do not recommend using this unless those extra
-    megabytes do really matter.
+Snapshots of other branches, releases or commits can be found on the [GitHub](https://github.com/opencv/opencv) and the [official download page](https://opencv.org/releases.html).
+
+
+## Configure and build {#tutorial_linux_install_detailed_basic_build}
+
+- Create build directory:
+@snippet linux_install_a.sh prepare
+
+- Configure - generate build scripts for the preferred build system:
+    - For _make_...
+    @snippet linux_install_a.sh configure
+    - ... or for _ninja_:
+    @snippet linux_install_b.sh configure
+
+- Build - run actual compilation process:
+    - Using _make_...
+    @snippet linux_install_a.sh build
+    - ... or _ninja_:
+    @snippet linux_install_b.sh build
+
+
+@note
+_Configure_ process can download some files from the internet to satisfy library dependencies, connection failures can cause some of modules or functionalities to be turned off or behave differently. Refer to the @ref tutorial_general_install and @ref tutorial_config_reference tutorials for details and full configuration options reference.
+
+@note
+If you experience problems with the build process, try to clean or recreate the build directory. Changes in the configuration like disabling a dependency, modifying build scripts or switching sources to another branch are not handled very well and can result in broken workspace.
+
+@note
+_Make_ can run multiple compilation processes in parallel, `-j<NUM>` option means "run <NUM> jobs simultaneously". _Ninja_ will automatically detect number of available processor cores and does not need `-j` option.
+
+
+## Check build results {#tutorial_linux_install_detailed_basic_verify}
+
+After successful build you will find libraries in the `build/lib` directory and executables (test, samples, apps) in the `build/bin` directory:
+@snippet linux_install_a.sh check
+
+CMake package files will be located in the build root:
+@snippet linux_install_a.sh check cmake
+
+
+## Install
+
+@warning
+Installation process only copies files to predefined locations and do minor patching. Library installed using this method is not integrated into the system package registry and can not be uninstalled automatically. We do not recommend system-wide installation to regular users due to possible conflicts with system packages.
+
+By default OpenCV will be installed to the `/usr/local` directory, all files will be copied to following locations:
+* `/usr/local/bin` - executable files
+* `/usr/local/lib` - libraries (.so)
+* `/usr/local/cmake/opencv4` - cmake package
+* `/usr/local/include/opencv4` - headers
+* `/usr/local/share/opencv4` - other files (e.g. trained cascades in XML format)
+
+Since `/usr/local` is owned by the root user, the installation should be performed with elevated privileges (`sudo`):
+@snippet linux_install_a.sh install
+or
+@snippet linux_install_b.sh install
+
+Installation root directory can be changed with `CMAKE_INSTALL_PREFIX` configuration parameter, e.g. `-DCMAKE_INSTALL_PREFIX=$HOME/.local` to install to current user's local directory. Installation layout can be changed with `OPENCV_*_INSTALL_PATH` parameters. See @ref tutorial_config_reference for details.

doc/tutorials/introduction/macos_install/macos_install.markdown

@@ -4,6 +4,10 @@ Installation in MacOS {#tutorial_macos_install}
 @prev_tutorial{tutorial_android_ocl_intro}
 @next_tutorial{tutorial_ios_install}
 
+|    |    |
+| -: | :- |
+| Original author | `@sajarindider` |
+| Compatibility | OpenCV >= 3.4 |
 
 The following steps have been tested for MacOSX (Mavericks) but should work with other versions as well.
 

doc/tutorials/introduction/table_of_content_introduction.markdown

 Introduction to OpenCV {#tutorial_table_of_content_introduction}
 ======================
 
-Here you can read tutorials about how to set up your computer to work with the OpenCV library.
-Additionally you can find very basic sample source code to introduce you to the world of the OpenCV.
+- @subpage tutorial_general_install
+- @subpage tutorial_config_reference
 
+##### Linux
 -   @subpage tutorial_linux_install
-
-    _Compatibility:_ \> OpenCV 2.0
-
-    _Author:_ Ana Huamán
-
-    We will learn how to setup OpenCV in your computer!
-
 -   @subpage tutorial_linux_gcc_cmake
-
-    _Compatibility:_ \> OpenCV 2.0
-
-    _Author:_ Ana Huamán
-
-    We will learn how to compile your first project using gcc and CMake
-
 -   @subpage tutorial_linux_eclipse
 
-    _Compatibility:_ \> OpenCV 2.0
-
-    _Author:_ Ana Huamán
-
-    We will learn how to compile your first project using the Eclipse environment
-
+##### Windows
 -   @subpage tutorial_windows_install
-
-    _Compatibility:_ \> OpenCV 2.0
-
-    _Author:_ Bernát Gábor
-
-    You will learn how to setup OpenCV in your Windows Operating System!
-
 -   @subpage tutorial_windows_visual_studio_opencv
-
-    _Compatibility:_ \> OpenCV 2.0
-
-    _Author:_ Bernát Gábor
-
-    You will learn what steps you need to perform in order to use the OpenCV library inside a new
-    Microsoft Visual Studio project.
-
 -   @subpage tutorial_windows_visual_studio_image_watch
 
-    _Compatibility:_ \>= OpenCV 2.4
-
-    _Author:_ Wolf Kienzle
-
-    You will learn how to visualize OpenCV matrices and images within Visual Studio 2012.
-
+##### Java & Android
 -   @subpage tutorial_java_dev_intro
-
-    _Compatibility:_ \> OpenCV 2.4.4
-
-    _Authors:_ Eric Christiansen and Andrey Pavlenko
-
-    Explains how to build and run a simple desktop Java application using Eclipse, Ant or the
-    Simple Build Tool (SBT).
-
 -   @subpage tutorial_java_eclipse
-
-    _Compatibility:_ \> OpenCV 2.4.4
-
-    _Author:_ Barış Evrim Demiröz
-
-    A tutorial on how to use OpenCV Java with Eclipse.
-
 -   @subpage tutorial_clojure_dev_intro
-
-    _Compatibility:_ \> OpenCV 2.4.4
-
-    _Author:_ Mimmo Cosenza
-
-    A tutorial on how to interactively use OpenCV from the Clojure REPL.
-
 -   @subpage tutorial_android_dev_intro
-
-    _Compatibility:_ \> OpenCV 2.4.2
-
-    _Author:_ Vsevolod Glumov
-
-    Not a tutorial, but a guide introducing Android development basics and environment setup
-
 -   @subpage tutorial_O4A_SDK
-
-    _Compatibility:_ \> OpenCV 2.4.2
-
-    _Author:_ Vsevolod Glumov
-
-    OpenCV4Android SDK: general info, installation, running samples
-
 -   @subpage tutorial_dev_with_OCV_on_Android
-
-    _Compatibility:_ \> OpenCV 2.4.3
-
-    _Author:_ Vsevolod Glumov
-
-    Development with OpenCV4Android SDK
-
 -   @subpage tutorial_android_ocl_intro
 
-    _Compatibility:_ \>= OpenCV 3.0
-
-    _Author:_ Andrey Pavlenko
-
-    Modify Android camera preview with OpenCL
-
+##### Other platforms
 -   @subpage tutorial_macos_install
-
-    _Compatibility:_ \> OpenCV 3.4.x
-
-    _Author:_ [\@sajarindider](https://github.com/sajarindider)
-
-    We will learn how to setup OpenCV in MacOS.
-
 -   @subpage tutorial_ios_install
-
-    _Compatibility:_ \> OpenCV 2.4.2
-
-    _Author:_ Artem Myagkov, Eduard Feicho, Steve Nicholson
-
-    We will learn how to setup OpenCV for using it in iOS!
-
 -   @subpage tutorial_arm_crosscompile_with_cmake
-
-    _Compatibility:_ \> OpenCV 2.4.4
-
-    _Author:_ Alexander Smorkalov
-
-    We will learn how to setup OpenCV cross compilation environment for ARM Linux.
-
 -   @subpage tutorial_building_tegra_cuda
 
-    _Compatibility:_ \>= OpenCV 3.1.0
-
-    _Author:_ Randy J. Ray
-
-    This tutorial will help you build OpenCV 3.1.0 for NVIDIA<sup>&reg;</sup> Tegra<sup>&reg;</sup> systems with CUDA 8.0.
-
--   @subpage tutorial_display_image
-
-    _Languages:_ C++, Python
-
-    _Compatibility:_ \> OpenCV 3.4.4
-
-    _Author:_ Ana Huamán
-
-    We will learn how to read an image, display it in a window and write it to a file using OpenCV
-
--   @subpage tutorial_documentation
-
-    _Compatibility:_ \> OpenCV 3.0
-
-    _Author:_ Maksim Shabunin
-
-    This tutorial describes new documenting process and some useful Doxygen features.
-
--   @subpage tutorial_transition_guide
-
-    _Author:_ Maksim Shabunin
-
-    This document describes some aspects of 2.4 -> 3.0 transition process.
-
--   @subpage tutorial_cross_referencing
-
-    _Compatibility:_ \> OpenCV 3.3.0
-
-    _Author:_ Sebastian Höffner
+##### Usage basics
+-   @subpage tutorial_display_image - We will learn how to load an image from file and display it using OpenCV
 
-    This document outlines how to create cross references to the OpenCV documentation from other Doxygen projects.
+##### Miscellaneous
+-   @subpage tutorial_documentation - This tutorial describes new documenting process and some useful Doxygen features.
+-   @subpage tutorial_transition_guide - This document describes some aspects of 2.4 -> 3.0 transition process.
+-   @subpage tutorial_cross_referencing - This document outlines how to create cross references to the OpenCV documentation from other Doxygen projects.

doc/tutorials/introduction/transition_guide/transition_guide.markdown

@@ -4,6 +4,10 @@ Transition guide {#tutorial_transition_guide}
 @prev_tutorial{tutorial_documentation}
 @next_tutorial{tutorial_cross_referencing}
 
+|    |    |
+| -: | :- |
+| Original author | Maksim Shabunin |
+| Compatibility | OpenCV >= 3.0 |
 
 @tableofcontents
 

doc/tutorials/introduction/windows_install/windows_install.markdown

@@ -4,6 +4,13 @@ Installation in Windows {#tutorial_windows_install}
 @prev_tutorial{tutorial_linux_eclipse}
 @next_tutorial{tutorial_windows_visual_studio_opencv}
 
+|    |    |
+| -: | :- |
+| Original author | Bernát Gábor |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
 
 The description here was tested on Windows 7 SP1. Nevertheless, it should also work on any other
 relatively modern version of Windows OS. If you encounter errors after following the steps described

doc/tutorials/introduction/windows_visual_studio_image_watch/windows_visual_studio_image_watch.markdown

@@ -4,6 +4,13 @@ Image Watch: viewing in-memory images in the Visual Studio debugger {#tutorial_w
 @prev_tutorial{tutorial_windows_visual_studio_opencv}
 @next_tutorial{tutorial_java_dev_intro}
 
+|    |    |
+| -: | :- |
+| Original author | Wolf Kienzle |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
 
 Image Watch is a plug-in for Microsoft Visual Studio that lets you to visualize in-memory images
 (*cv::Mat* or *IplImage_* objects, for example) while debugging an application. This can be helpful

doc/tutorials/introduction/windows_visual_studio_opencv/windows_visual_studio_opencv.markdown

 How to build applications with OpenCV inside the "Microsoft Visual Studio" {#tutorial_windows_visual_studio_opencv}
 ==========================================================================
-
 @prev_tutorial{tutorial_windows_install}
 @next_tutorial{tutorial_windows_visual_studio_image_watch}
 
+|    |    |
+| -: | :- |
+| Original author | Bernát Gábor |
+| Compatibility | OpenCV >= 3.0 |
+
+@warning
+This tutorial can contain obsolete information.
 
 Everything I describe here will apply to the `C\C++` interface of OpenCV. I start out from the
 assumption that you have read and completed with success the @ref tutorial_windows_install tutorial.

doc/tutorials/tutorials.markdown

 OpenCV Tutorials {#tutorial_root}
 ================
 
-The following links describe a set of basic OpenCV tutorials. All the source code mentioned here is
-provided as part of the OpenCV regular releases, so check before you start copying & pasting the code.
-The list of tutorials below is automatically generated from reST files located in our GIT
-repository.
-
-As always, we would be happy to hear your comments and receive your contributions on any tutorial.
-
--   @subpage tutorial_table_of_content_introduction
-
-    You will learn how to setup OpenCV on your computer
-
--   @subpage tutorial_table_of_content_core
-
-    Here you will learn
-    about the basic building blocks of this library. A must read for understanding how
-    to manipulate the images on a pixel level.
-
--   @subpage tutorial_table_of_content_imgproc
-
-    In this section
-    you will learn about the image processing (manipulation) functions inside OpenCV.
-
--   @subpage tutorial_table_of_content_highgui
-
-    This section contains valuable tutorials on how to use the
-    built-in graphical user interface of the library.
-
--   @subpage tutorial_table_of_content_imgcodecs
-
-    These tutorials show how to read and write images using imgcodecs module.
-
--   @subpage tutorial_table_of_content_videoio
-
-    These tutorials show how to read and write videos using videio module.
-
--   @subpage tutorial_table_of_content_calib3d
-
-    Although
-    most of our images are in a 2D format they do come from a 3D world. Here you will learn how to find
-    out 3D world information from 2D images.
-
--   @subpage tutorial_table_of_content_features2d
-
-    Learn about how
-    to use the feature points detectors, descriptors and matching framework found inside OpenCV.
-
--   @subpage tutorial_table_of_content_video
-
-    Here you will find
-    algorithms usable on your video streams like motion extraction, feature tracking and
-    foreground extractions.
-
--   @subpage tutorial_table_of_content_objdetect
-
-    Ever wondered
-    how your digital camera detects people's faces? Look here to find out!
-
--   @subpage tutorial_table_of_content_dnn
-
-    These tutorials show how to use dnn module effectively.
-
--   @subpage tutorial_table_of_content_ml
-
-    Use the powerful
-    machine learning classes for statistical classification, regression and clustering of data.
-
--   @subpage tutorial_table_of_content_gapi
-
-    Learn how to use Graph API (G-API) and port algorithms from "traditional" OpenCV to a graph model.
-
--   @subpage tutorial_table_of_content_photo
-
-    Use OpenCV for
-    advanced photo processing.
-
--   @subpage tutorial_table_of_content_stitching
-
-    Learn how to create beautiful photo panoramas and more with OpenCV stitching pipeline.
-
+- @subpage tutorial_table_of_content_introduction - build and install OpenCV on your computer
+- @subpage tutorial_table_of_content_core - basic building blocks of the library
+- @subpage tutorial_table_of_content_imgproc - image processing functions
+- @subpage tutorial_table_of_content_highgui - built-in graphical user interface
+- @subpage tutorial_table_of_content_imgcodecs - read and write images from/to files using _imgcodecs_ module
+- @subpage tutorial_table_of_content_videoio - read and write videos using _videio_ module
+- @subpage tutorial_table_of_content_calib3d - extract 3D world information from 2D images
+- @subpage tutorial_table_of_content_features2d - feature detectors, descriptors and matching framework
+- @subpage tutorial_table_of_content_video - algorithms for video streams: motion detection, object and feature tracking, etc.
+- @subpage tutorial_table_of_content_objdetect - detect objects using conventional CV methods
+- @subpage tutorial_table_of_content_dnn - infer neural networks using built-in _dnn_ module
+- @subpage tutorial_table_of_content_ml - machine learning algorithms for statistical classification, regression and data clustering
+- @subpage tutorial_table_of_content_gapi - graph-based approach to computer vision algorithms building
+- @subpage tutorial_table_of_content_photo - advanced photo processing
+- @subpage tutorial_table_of_content_stitching - create panoramas and more using _stitching_ module
+- @subpage tutorial_table_of_content_ios - running OpenCV on an iDevice
 @cond CUDA_MODULES
--   @subpage tutorial_table_of_content_gpu
-
-    Squeeze out every
-    little computational power from your system by utilizing the power of your video card to run the
-    OpenCV algorithms.
+- @subpage tutorial_table_of_content_gpu - utilizing power of video card to run CV algorithms
 @endcond
-
--   @subpage tutorial_table_of_content_ios
-
-    Run OpenCV and your vision apps on an iDevice

samples/install/linux_install_a.sh

+#!/bin/bash
+# This file contains documentation snippets for Linux installation tutorial
+if [ "$1" = "--check" ] ; then
+sudo()
+{
+    command $@
+}
+fi
+
+sudo apt update
+
+# [gcc]
+sudo apt install -y g++
+# [gcc]
+
+# [make]
+sudo apt install -y make
+# [make]
+
+# [cmake]
+sudo apt install -y cmake
+# [cmake]
+
+# [wget]
+sudo apt install -y wget unzip
+# [wget]
+
+# [download]
+wget -O opencv.zip https://github.com/opencv/opencv/archive/master.zip
+unzip opencv.zip
+mv opencv-master opencv
+# [download]
+
+# [prepare]
+mkdir -p build && cd build
+# [prepare]
+
+# [configure]
+cmake ../opencv
+# [configure]
+
+# [build]
+make -j4
+# [build]
+
+# [check]
+ls bin
+ls lib
+# [check]
+
+# [check cmake]
+ls OpenCVConfig*.cmake
+ls OpenCVModules.cmake
+# [check cmake]
+
+# [install]
+sudo make install
+# [install]

samples/install/linux_install_b.sh

+#!/bin/bash
+# This file contains documentation snippets for Linux installation tutorial
+if [ "$1" = "--check" ] ; then
+sudo()
+{
+    command $@
+}
+fi
+
+sudo apt update
+
+# [clang]
+sudo apt install -y clang
+# [clang]
+
+# [ninja]
+sudo apt install -y ninja-build
+# [ninja]
+
+# [cmake]
+sudo apt install -y cmake
+# [cmake]
+
+# [git]
+sudo apt install -y git
+# [git]
+
+# [download]
+git clone https://github.com/opencv/opencv.git
+git -C opencv checkout master
+# [download]
+
+# [prepare]
+mkdir -p build && cd build
+# [prepare]
+
+# [configure]
+cmake -GNinja ../opencv
+# [configure]
+
+# [build]
+ninja
+# [build]
+
+# [install]
+sudo ninja install
+# [install]

samples/install/linux_quick_install.sh

+#!/bin/bash
+# This file contains documentation snippets for Linux installation tutorial
+if [ "$1" = "--check" ] ; then
+sudo()
+{
+    command $@
+}
+fi
+
+# [body]
+# Install minimal prerequisites (Ubuntu 18.04 as reference)
+sudo apt update && sudo apt install -y cmake g++ wget unzip
+
+# Download and unpack sources
+wget -O opencv.zip https://github.com/opencv/opencv/archive/master.zip
+unzip opencv.zip
+
+# Create build directory
+mkdir -p build && cd build
+
+# Configure
+cmake  ../opencv-master
+
+# Build
+cmake --build .
+# [body]

samples/install/linux_quick_install_contrib.sh

+#!/bin/bash
+# This file contains documentation snippets for Linux installation tutorial
+if [ "$1" = "--check" ] ; then
+sudo()
+{
+    command $@
+}
+fi
+
+# [body]
+# Install minimal prerequisites (Ubuntu 18.04 as reference)
+sudo apt update && sudo apt install -y cmake g++ wget unzip
+
+# Download and unpack sources
+wget -O opencv.zip https://github.com/opencv/opencv/archive/master.zip
+wget -O opencv_contrib.zip https://github.com/opencv/opencv_contrib/archive/master.zip
+unzip opencv.zip
+unzip opencv_contrib.zip
+
+# Create build directory and switch into it
+mkdir -p build && cd build
+
+# Configure
+cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib-master/modules ../opencv-master
+
+# Build
+cmake --build .
+# [body]

samples/install/linux_verify.sh

+#!/bin/bash
+# This script verifies that all shell snippets in the
+# Linux installation tutorial work (in Ubuntu 18 container)
+set -e
+set -x
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"
+
+docker pull ubuntu:18.04
+
+for f in $(cd "${SCRIPT_DIR}" && ls -1 linux_*install*.sh) ; do
+    echo "Checking $f..."
+    docker run -it \
+        --volume "${SCRIPT_DIR}":/install:ro \
+        ubuntu:18.04 \
+        /bin/bash -ex /install/$f --check
+
+done