diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 1e32d6095..4012231be 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -83,6 +83,14 @@ optional. For details on customizing the build process, see 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 `_. Similar to ``SuiteSparse`` but simpler and slower. CXSparse has no dependencies on ``LAPACK`` and ``BLAS``. This makes for a simpler @@ -223,13 +231,13 @@ this. 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 -`_ (recomended) or `MacPorts +`_ (recommended) or `MacPorts `_ to install Ceres Solver. If using `Homebrew `_, then @@ -409,6 +417,12 @@ dependencies. #. 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 @@ To build Ceres for Android, we need to force ``CMake`` to find 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 @@ To build Ceres for iOS, we need to force ``CMake`` to find the 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 @@ Options controlling Ceres configuration 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 - `_ + `_ where it will be detected **without requiring installation** in a client project using CMake when `find_package(Ceres) - `_ + `_ is invoked. #. ``BUILD_DOCUMENTATION [Default: OFF]``: Use this to enable building @@ -722,8 +740,16 @@ Options controlling Ceres dependency locations ---------------------------------------------- Ceres uses the ``CMake`` `find_package -`_ -function to find all of its dependencies using +`_ +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 ``_DIR`` variables, or since ``CMake`` 3.12 the +``_ROOT`` variables. + +Other dependencies are found using ``Find.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 @@ Using Ceres with CMake ====================== In order to use Ceres in client code with CMake using `find_package() -`_ +`_ then either: #. Ceres must have been installed with ``make install``. If the @@ -827,6 +853,7 @@ directory. 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 @@ The Ceres components which can be specified are: To specify one/multiple Ceres components use the ``COMPONENTS`` argument to `find_package() -`_ like so: +`_ like so: .. code-block:: cmake @@ -885,7 +912,7 @@ Specify Ceres version Additionally, when CMake has found Ceres it can optionally check the package version, if it has been specified in the `find_package() -`_ +`_ call. For example: .. code-block:: cmake @@ -943,9 +970,9 @@ following references are very useful: All libraries and executables built using CMake are represented as *targets* created using `add_library() - `_ + `_ and `add_executable() - `_. + `_. 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 @@ and compiled libraries, a set of CMake-specific project configuration files are also installed to: ``/lib/cmake/Ceres`` (if Ceres is installed), or created in the build directory (if Ceres' build directory is exported). When `find_package -`_ is +`_ 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 @@ due to missing references to Ceres public dependencies. Note that this description applies both to projects that are **installed** using CMake, and to those whose **build directory is exported** using `export() -`_ (instead +`_ (instead of `install() -`_). Ceres +`_). 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 @@ and it is these copied files that are used by any client code. When a 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 -`_, +`_, ``/.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 @@ Ceres) to invoke ``find_package(Ceres)`` in ``FooConfig.cmake``, thus # 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.cmake`` modules any + more. Hence, instead of the custom variables (``_INCLUDE_DIR_HINTS``, + ``_INCLUDE_DIR``, ...) you should use standard + CMake facilities to customize where these dependencies are found, such as + ``CMAKE_PREFIX_PATH``, the ``_DIR`` variables, or + since CMake 3.12 the ``_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.