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.