mirror of
https://github.com/ceres-solver/ceres-solver.git
synced 2026-08-30 00:50:37 +08:00
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
This commit is contained in:
Nikolaus Demmel
committed by
Sameer Agarwal
Sameer Agarwal
parent
3f69e5b36a
commit
bdcdcc78af
@@ -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 <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 @@ 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
|
||||
<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 @@ 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
|
||||
<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 @@ Options controlling Ceres dependency locations
|
||||
----------------------------------------------
|
||||
|
||||
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 @@ Using Ceres with CMake
|
||||
======================
|
||||
|
||||
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 @@ 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()
|
||||
<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 @@ 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()
|
||||
<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 @@ following references are very useful:
|
||||
|
||||
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 @@ and compiled libraries, a set of CMake-specific project configuration
|
||||
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 @@ 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()
|
||||
<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 @@ 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
|
||||
<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 @@ 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<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.
|
||||
|
||||
Reference in New Issue
Block a user