update docs for changed cmake usage

- update links to cmake docs to version 3.5
- highlight difference between dependencies with and without custom
  find modules
- point out removal of CERES_INCLUDE_DIRS
- point out that TBB might be linked if SuiteSparseQR is found
- added 'Migration' section
- fixed typos

Change-Id: Icbcc0e723d11f12246fb3cf09b9d7c6206195a82
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 1e32d60..4012231 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -83,6 +83,14 @@
   solving large sparse linear systems. **Optional; strongly recomended
   for large scale bundle adjustment**
 
+  .. NOTE ::
+
+     If SuiteSparseQR is found, Ceres attempts to find the Intel
+     Thread Building Blocks (TBB) library. If found, Ceres assumes
+     SuiteSparseQR was compiled with TBB support and will link to the
+     found TBB version. You can customize the searched TBB location
+     with the ``TBB_ROOT`` variable.
+
 - `CXSparse <http://faculty.cse.tamu.edu/davis/suitesparse.html>`_.
   Similar to ``SuiteSparse`` but simpler and slower. CXSparse has
   no dependencies on ``LAPACK`` and ``BLAS``. This makes for a simpler
@@ -223,13 +231,13 @@
 
     Termination:                      CONVERGENCE (Function tolerance reached. |cost_change|/cost: 1.769766e-09 <= 1.000000e-06)
 
-.. section-osx:
+.. section-macos:
 
 macOS
 =====
 
 On macOS, you can either use `Homebrew
-<https://brew.sh/>`_ (recomended) or `MacPorts
+<https://brew.sh/>`_ (recommended) or `MacPorts
 <https://www.macports.org/>`_ to install Ceres Solver.
 
 If using `Homebrew <https://brew.sh/>`_, then
@@ -409,6 +417,12 @@
 #. Try running ``Configure``. It won't work. It'll show a bunch of options.
    You'll need to set:
 
+FIXME: since ``EIGEN_INCLUDE_DIR_HINTS``, ``GFLAGS_INCLUDE_DIR_HINTS``
+and ``GFLAGS_LIBRARY_DIR_HINTS`` was removed, these instructions won't
+work to find those dependencies (in particular eigen, for which it
+says just unpack; you need to run build & install to generate the
+cmake configs and then point cmake it that location...)
+
    #. ``GLOG_INCLUDE_DIR_HINTS``
    #. ``GLOG_LIBRARY_DIR_HINTS``
    #. (Optional) ``SUITESPARSE_INCLUDE_DIR_HINTS``
@@ -463,6 +477,8 @@
 the toolchains from the Android NDK instead of using the standard
 ones. For example, assuming you have specified ``$NDK_DIR``:
 
+FIXME: EIGEN_INCLUDE_DIR was removed
+
 .. code-block:: bash
 
     cmake \
@@ -521,6 +537,8 @@
 toolchains from the iOS SDK instead of using the standard ones. For
 example:
 
+FIXME: EIGEN_INCLUDE_DIR was removed
+
 .. code-block:: bash
 
    cmake \
@@ -683,10 +701,10 @@
    solely for installation, and so must be installed in order for
    clients to use it.  Turn this ``ON`` to export Ceres' build
    directory location into the `user's local CMake package registry
-   <http://www.cmake.org/cmake/help/v3.2/manual/cmake-packages.7.html#user-package-registry>`_
+   <http://www.cmake.org/cmake/help/v3.5/manual/cmake-packages.7.html#user-package-registry>`_
    where it will be detected **without requiring installation** in a
    client project using CMake when `find_package(Ceres)
-   <http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_
+   <http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_
    is invoked.
 
 #. ``BUILD_DOCUMENTATION [Default: OFF]``: Use this to enable building
@@ -722,8 +740,16 @@
 ----------------------------------------------
 
 Ceres uses the ``CMake`` `find_package
-<http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_
-function to find all of its dependencies using
+<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_
+function to find all of its dependencies. Dependencies that reliably
+provide config files on all supported platforms are expected to be
+found in "Config" mode of ``find_package`` (``Eigen``, ``gflags``).
+This means you can use the standard ``CMake`` facilities to customize
+where these dependencies are found, such as ``CMAKE_PREFIX_PATH``,
+the ``<DEPENDENCY_NAME>_DIR`` variables, or since ``CMake`` 3.12 the
+``<DEPENDENCY_NAME>_ROOT`` variables.
+
+Other dependencies are found using
 ``Find<DEPENDENCY_NAME>.cmake`` scripts which are either included in
 Ceres (for most dependencies) or are shipped as standard with
 ``CMake`` (for ``LAPACK`` & ``BLAS``).  These scripts will search all
@@ -779,7 +805,7 @@
 ======================
 
 In order to use Ceres in client code with CMake using `find_package()
-<http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_
+<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_
 then either:
 
 #. Ceres must have been installed with ``make install``.  If the
@@ -827,6 +853,7 @@
      as the exported Ceres CMake target already contains the definitions
      of its public include directories which will be automatically
      included by CMake when compiling a target that links against Ceres.
+     In fact, since v2.0 ``CERES_INCLUDE_DIRS`` is not even set.
 
 Specify Ceres components
 -------------------------------------
@@ -867,7 +894,7 @@
 
 To specify one/multiple Ceres components use the ``COMPONENTS`` argument to
 `find_package()
-<http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_ like so:
+<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_ like so:
 
 .. code-block:: cmake
 
@@ -885,7 +912,7 @@
 
 Additionally, when CMake has found Ceres it can optionally check the package
 version, if it has been specified in the `find_package()
-<http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_
+<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_
 call.  For example:
 
 .. code-block:: cmake
@@ -943,9 +970,9 @@
 
     All libraries and executables built using CMake are represented as
     *targets* created using `add_library()
-    <http://www.cmake.org/cmake/help/v3.2/command/add_library.html>`_
+    <http://www.cmake.org/cmake/help/v3.5/command/add_library.html>`_
     and `add_executable()
-    <http://www.cmake.org/cmake/help/v3.2/command/add_executable.html>`_.
+    <http://www.cmake.org/cmake/help/v3.5/command/add_executable.html>`_.
     Targets encapsulate the rules and dependencies (which can be other
     targets) required to build or link against an object.  This allows
     CMake to implicitly manage dependency chains.  Thus it is
@@ -961,7 +988,7 @@
 files are also installed to: ``<INSTALL_ROOT>/lib/cmake/Ceres`` (if Ceres
 is installed), or created in the build directory (if Ceres' build
 directory is exported).  When `find_package
-<http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_ is
+<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_ is
 invoked, CMake checks various standard install locations (including
 ``/usr/local`` on Linux & UNIX systems), and the local CMake package
 registry for CMake configuration files for the project to be found
@@ -1014,9 +1041,9 @@
 Note that this description applies both to projects that are
 **installed** using CMake, and to those whose **build directory is
 exported** using `export()
-<http://www.cmake.org/cmake/help/v3.2/command/export.html>`_ (instead
+<http://www.cmake.org/cmake/help/v3.5/command/export.html>`_ (instead
 of `install()
-<http://www.cmake.org/cmake/help/v3.2/command/install.html>`_).  Ceres
+<http://www.cmake.org/cmake/help/v3.5/command/install.html>`_).  Ceres
 supports both installation and export of its build directory if the
 ``EXPORT_BUILD_DIR`` option is enabled, see
 :ref:`section-customizing`.
@@ -1032,7 +1059,7 @@
 project's build directory is **exported**, instead of copying the
 compiled libraries and headers, CMake creates an entry for the project
 in the `user's local CMake package registry
-<http://www.cmake.org/cmake/help/v3.2/manual/cmake-packages.7.html#user-package-registry>`_,
+<http://www.cmake.org/cmake/help/v3.5/manual/cmake-packages.7.html#user-package-registry>`_,
 ``<USER_HOME>/.cmake/packages`` on Linux & macOS, which contains the
 path to the project's build directory which will be checked by CMake
 during a call to ``find_package()``.  The effect of which is that any
@@ -1083,3 +1110,33 @@
     # CMake's search list before this call.
     include(CMakeFindDependencyMacro)
     find_dependency(Ceres)
+
+.. _section-migration
+
+Migration
+=========
+
+The following includes some hints for migrating from previous versions.
+
+Version 2.0
+-----------
+
+- When using Ceres with CMake, the target name in v2.0 is
+  ``Ceres::ceres`` following modern naming convetions. The legacy
+  target ``ceres`` exists for backwards compatibility, but is
+  deprecated. ``CERES_INCLUDE_DIRS`` is not set any more, as the
+  exported Ceres CMake target already contains the definitions of its
+  public include directories which will be automatically included by
+  CMake when compiling a target that links against Ceres.
+- When building Ceres, some dependencies (Eigen, gflags) are not found
+  using custom ``Find<DEPENDENCY_NAME>.cmake`` modules any
+  more. Hence, instead of the custom variables (``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR_HINTS``,
+  ``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR``, ...) you should use standard
+  CMake facilities to customize where these dependencies are found, such as
+  ``CMAKE_PREFIX_PATH``, the ``<DEPENDENCY_NAME>_DIR`` variables, or
+  since CMake 3.12 the ``<DEPENDENCY_NAME>_ROOT`` variables.
+- While TBB is not used any more directly by Ceres, it might still try
+  to link against it, if SuiteSparseQR was found. The variable (environment
+  or CMake) to customize this is ``TBB_ROOT`` (used to be ``TBBROOT``).
+  For example, use ``cmake -DTBB_ROOT=/opt/intel/tbb ...`` if you want to
+  link against TBB installed from Intel's binary packages on Linux.