Partially update the installation docs
1. Update dependencies
2. Mention submodules
Change-Id: I2f238c92a3a1eeee3277e3ec6f973fc2d50fe008
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 4feb1a4..3446ddb 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -4,18 +4,6 @@
Installation
============
-Getting the source code
-=======================
-.. _section-source:
-
-You can start with the `latest stable release
-<http://ceres-solver.org/ceres-solver-2.2.0.tar.gz>`_ . Or if you want
-the latest version, you can clone the git repository
-
-.. code-block:: bash
-
- git clone https://ceres-solver.googlesource.com/ceres-solver
-
.. _section-dependencies:
Dependencies
@@ -23,16 +11,17 @@
.. note ::
- Ceres Solver 2.2 requires a **fully C++17-compliant** compiler.
+ Starting with version 2.2, Ceres Solver requires a **fully
+ C++17-compliant** compiler.
Ceres relies on a number of open source libraries, some of which are
optional. For details on customizing the build process, see
:ref:`section-customizing` .
-- `CMake <http://www.cmake.org>`_ 3.16 or later **required**.
+- `CMake <http://www.cmake.org>`_ (**required**) 3.16 or later.
- `Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_
- 3.3 or later **required**.
+ (**Required**) 3.3 or later.
.. NOTE ::
@@ -40,37 +29,14 @@
library. Please see the documentation for ``EIGENSPARSE`` for
more details.
-- `glog <https://github.com/google/glog>`_ 0.3.5 or
- later. **Recommended**
+- `Abseil <https://abseil.io/>`_ (**Required**) 20240116 or later.
- ``glog`` is used extensively throughout Ceres for logging detailed
- information about memory allocations and time consumed in various
- parts of the solve, internal error conditions etc. The Ceres
- developers use it extensively to observe and analyze Ceres's
- performance. `glog <https://github.com/google/glog>`_ allows you to
- control its behaviour from the command line. Starting with
- ``-logtostderr`` you can add ``-v=N`` for increasing values of ``N``
- to get more and more verbose and detailed information about Ceres
- internals.
-
- Ceres also ships with a minimal replacement of ``glog`` called
- ``miniglog`` that can be enabled with the ``MINIGLOG`` build option.
- ``miniglog`` is supplied for platforms which do not support the full
- version of ``glog``.
-
- In an attempt to reduce dependencies, it may be tempting to use
- ``miniglog`` on platforms which already support ``glog``. While
- there is nothing preventing the user from doing so, we strongly
- recommend against it. ``miniglog`` has worse performance than
- ``glog`` and is much harder to control and use.
-
-- `gflags <https://github.com/gflags/gflags>`_. Needed to build
- examples and tests and usually a dependency for glog.
+- `GoogleTest <https://github.com/google/googletest>`_ (**Optional**;
+ Required if you wish to build and run tests) 1.14.0 or later.
- `SuiteSparse <http://faculty.cse.tamu.edu/davis/suitesparse.html>`_
- 4.5.6 or later. Needed for solving large sparse linear
- systems. **Optional; strongly recommended for large scale bundle
- adjustment**
+ (**Optional; strongly recommended for large problems**) 4.5.6 or
+ later. Needed for solving large sparse linear systems.
.. NOTE ::
@@ -80,17 +46,15 @@
found TBB version. You can customize the searched TBB location
with the ``TBB_ROOT`` variable.
- A CMake native version of SuiteSparse that can be compiled on a variety of
- platforms (e.g., using Visual Studio, Xcode, MinGW, etc.) is maintained by the
- `CMake support for SuiteSparse <https://github.com/sergiud/SuiteSparse>`_
- project.
+- `Apple's Accelerate sparse solvers
+ <https://developer.apple.com/documentation/accelerate/sparse_solvers>`_. (**Optional**)
-- `Apple's Accelerate sparse solvers <https://developer.apple.com/documentation/accelerate/sparse_solvers>`_.
As of Xcode 9.0, Apple's Accelerate framework includes support for
- solving sparse linear systems across macOS, iOS et al. **Optional**
+ solving sparse linear systems across macOS, iOS et al.
- `BLAS <http://www.netlib.org/blas/>`_ and `LAPACK
- <http://www.netlib.org/lapack/>`_ routines are needed by
+ <http://www.netlib.org/lapack/>`_ (**Optional but required for**
+ ``SuiteSparse``) ``LAPACK`` and ``BLAS`` routines are needed by
``SuiteSparse``, and optionally used by Ceres directly for some
operations.
@@ -112,18 +76,50 @@
For Windows things are much more complicated. `LAPACK For
Windows <http://icl.cs.utk.edu/lapack-for-windows/lapack/>`_
- has detailed instructions..
+ has detailed instructions.
- **Optional but required for** ``SuiteSparse``.
-- `CUDA <https://developer.nvidia.com/cuda-toolkit>`_ If you have an
- NVIDIA GPU then Ceres Solver can use it accelerate the solution of
- the Gauss-Newton linear systems using the CMake flag ``USE_CUDA``.
- Currently this support is limited to using the dense linear solvers that ship
- with ``CUDA``. As a result GPU acceleration can be used to speed up
- ``DENSE_QR``, ``DENSE_NORMAL_CHOLESKY`` and
- ``DENSE_SCHUR``. This also enables ``CUDA`` mixed precision solves
- for ``DENSE_NORMAL_CHOLESKY`` and ``DENSE_SCHUR``. **Optional**.
+- `CUDA <https://developer.nvidia.com/cuda-toolkit>`_ and `cuDSS
+ <https://developer.nvidia.com/cudss>`_ (**Optional**)
+
+ If you have an NVIDIA GPU then Ceres Solver can use it accelerate
+ the solution of the Gauss-Newton linear systems using the CMake flag
+ ``USE_CUDA``.
+
+ This support depends on two libraries from NVIDIA `CUDA` and `cuDSS`.
+
+ If ``CUDA`` is available, Ceres Solver is able to use
+ GPU acceleration to speed up ``DENSE_QR``, ``DENSE_NORMAL_CHOLESKY``
+ and ``DENSE_SCHUR`` and ``CGNR``. This also enables ``CUDA`` based
+ mixed precision solves for ``DENSE_NORMAL_CHOLESKY`` and
+ ``DENSE_SCHUR``.
+
+ Additionally if ``cuDSS`` is also available then GPU acceleration can
+ be used for ``SPARSE_NORMAL_CHOLESKY`` and ``SPARSE_SCHUR``.
+
+.. _section-source:
+
+Getting the source code
+=======================
+
+
+You can start with the `latest stable release
+<http://ceres-solver.org/ceres-solver-2.2.0.tar.gz>`_ . Or if you want
+the latest version, you can clone the git repository
+
+.. code-block:: bash
+
+ git clone https://ceres-solver.googlesource.com/ceres-solver
+
+If your system does not have recent enough versions of `Abseil
+<https://abseil.io/>`_ and/or `GoogleTest
+<https://github.com/google/googletest>`_, then you can use the
+versions included with Ceres Solver as submodules by using the command
+
+.. code-block:: bash
+
+ git clone --recurse-submodules https://github.com/ceres-solver/ceres-solver
+
.. _section-linux:
@@ -136,7 +132,7 @@
.. NOTE::
Ceres Solver always supports the previous and current Ubuntu LTS
- releases, currently 18.04 and 20.04, using the default Ubuntu
+ releases, currently 22.04 and 24.04 using the default Ubuntu
repositories and compiler toolchain. Support for earlier versions
is not guaranteed or maintained.
