Squashed 'third_party/ceres/' changes from e51e9b46f..399cda773
399cda773 Update build documentation to reflect detection of Eigen via config mode
bb127272f Fix typos.
a0ec5c32a Update version history for 2.0.0RC2
3f6d27367 Unify symbol visibility configuration for all compilers
29c2912ee Unbreak the bazel build some more
bf47e1a36 Fix the Bazel build.
600e8c529 fix minor typos
bdcdcc78a update docs for changed cmake usage
3f69e5b36 Corrections from William Rucklidge
8bfdb02fb Rewrite uses of VLOG_IF and LOG_IF.
d1b35ffc1 Corrections from William Rucklidge
f34e80e91 Add dividers between licenses.
65c397dae Fix formatting
f63b1fea9 Add the MIT license text corresponding to the libmv derived files.
542613c13 minor formatting fix for trust_region_minimizer.cc
6d9e9843d Remove inclusion of ceres/eigen.h
eafeca5dc Fix a logging bug in TrustRegionMinimizer.
1fd0be916 Fix default initialisation of IterationCallback::cost
137bbe845 add info about clang-format to contributing docs
d3f66d77f fix formatting generated files (best effort)
a9c7361c8 minor formatting fix (wrongly updated in earlier commit)
7b8f675bf fix formatting for (non-generated) internal source files
921368ce3 Fix a number of typos in covariance.h
7b6b2491c fix formatting for examples
82275d8a4 some fixes for Linux and macOS install docs
9d762d74f fix formatting for public header files
c76478c48 gitignore *.pyc
4e69a475c Fix potential for mismatched release/debug TBB libraries
8e1d8e32a A number of small changes.
368a738e5 AutoDiffCostFunction: optional ownership
8cbd721c1 Add erf and erfc to jet.h, including tests in jet_test.cc
31366cff2 Benchmarks for dynamic autodiff.
29fb08aea Use CMAKE_PREFIX_PATH to pass Homebrew install location
242c703b5 Minor fixes to the documentation
79bbf9510 Add changelog for 2.0.0
41d05f13d Fix lint errors in evaluation_callback_test.cc
4b67903c1 Remove unused variables from problem_test.cc
10449fc36 Add Apache license to the LICENSE file for FixedArray
8c3ecec6d Fix some minor errors in IterationCallback docs
7d3ffcb42 Remove forced CONFIG from find_package(Eigen3)
a029fc0f9 Use latest FindTBB.cmake from VTK project
aa1abbc57 Replace use of GFLAGS_LIBRARIES with export gflags target
db2af1be8 Add Problem::EvaluateResidualBlockAssumingParametersUnchanged
ab4ed32cd Replace NULL with nullptr in the documentation.
ee280e27a Allow SubsetParameterization to accept an empty vector of constant parameters.
4b8c731d8 Fix a bug in DynamicAutoDiffCostFunction
5cb5b35a9 Fixed incorrect argument name in RotationMatrixToQuaternion()
e39d9ed1d Add a missing term and remove a superfluous word
27cab77b6 Reformulate some sentences
8ac6655ce Fix documentation formatting issues
7ef83e075 Update minimum required C++ version for Ceres to C++14
1d75e7568 Improve documentation for LocalParameterization
763398ca4 Update the section on Preconditioners
a614f788a Call EvaluationCallback before evaluating the fixed cost.
70308f7bb Simplify documentation generation.
e886d7e65 Reduce the number of minimizer iterations in evaluation_callback_test.cc
9483e6f2f Simplify DynamicCompressedRowJacobianWriter::Write
323cc55bb Update the version in package.xml to 2.0.0.
303b078b5 Fix few typos and alter a NULL to nullptr.
cca93fed6 Bypass Ceres' FindGlog.cmake in CeresConfig.cmake if possible
77fc1d0fc Use build_depend for private dependencies in Catkin package.xml
a09682f00 Fix MSVC version check to support use of clang-cl front-end
b70687fcc Add namespace qualified Ceres::ceres CMake target
99efa54bd Replace type aliases deprecated/removed in C++17/C++20 from FixedArray
adb973e4a NULL -> nullptr
27b717951 Respect FIND_QUIETLY flag in cmake config file
646959ef1 Do not export class template LineParameterization
1f128d070 Change the type of parameter index/offset to match their getter/setter
072c8f070 Initialize integer variables with integer instead of double
8c36bcc81 Use inline & -inlinehint-threshold in auto-diff benchmarks
57cf20aa5 static const -> static constexpr where we can.
40b27482a Add std::numeric_limit specialization for Jets
e751d6e4f Remove AutodiffCodegen
e9eb76f8e Remove AutodiffCodegen CMake integration
9435e08a7 More clang-tidy and wjr@ comment fixes
d93fac4b7 Remove AutodiffCodegen Tests
2281c6ed2 Fixes for comments from William Rucklidge
d797a87a4 Use Ridders' method in GradientChecker.
41675682d Fix a MSVC type deduction bug in ComputeHouseholderVector
947ec0c1f Remove AutodiffCodegen autodiff benchmarks
27183d661 Allow LocalParameterizations to have zero local size.
7ac7d79dc Remove HelloWorldCodegen example
8c8738bf8 Add photometric and relative-pose residuals to autodiff benchmarks
9f7fb66d6 Add a constant cost function to the autodiff benchmarks
ab0d373e4 Fix a comment in autodiff.h
27bb99714 Change SVD algorithm in covariance computation.
84fdac38e Add const to GetCovarianceMatrix*
6bde61d6b Add line local parameterization.
2c1c0932e Update documentation in autodiff.h
8904fa488 Inline Jet initialization in Autodiff
18a464d4e Remove an errant CR from local_parameterization.cc
5c85f2179 Use ArraySelector in Autodiff
80477ff07 Add class ArraySelector
e7a30359e Pass kNumResiduals to Autodiff
f339d71dd Refactor the automatic differentiation benchmarks.
d37b4cb15 Fix some include headers in codegen/test_utils.cc/h
550766e6d Add Autodiff Brdf Benchmark
8da9876e7 Add more autodiff benchmarks
6da364713 Fix Tukey loss function
cf4185c4e Add Codegen BA Benchmark
75dd30fae Simplify GenerateCodeForFunctor
9049688c6 Default Initialize ExpressionRef to Zero
bf1aff2f0 Fix 3+ nested Jet constructor
92d6541c7 Move Codegen files into codegen/ directory
8e962f37d Add Autodiff Codegen Tests
13c7a22ce Codegen Optimizer API
90799e29e Fix install and unnecessary string copy
032d5844c AutoDiff Code Generation - CMake Integration
d82de91b8 Add ExpressionGraph::Erase(ExpressionId)
c8e35e19f Add namespaces to generated functions and constants
75e575cae Fix use of incomplete type in defaulted Problem methods
8def19616 Remove ExpressionRef Move Constructor
f26f95410 Fix windows MSVC build.
fdf9cfd32 Add functions to find the matching ELSE, ENDIF expressions
678c05b28 Fix invert PSD matrix.
a384a7e96 Remove not used using declaration
a60136b7a Add COMMENT ExpressionType
f212c9295 Let Problem::SetParameterization be called more than once.
a3696835b use CMake function to create CeresConfigVersion
67fcff918 Make Problem movable.
19728e72d Add documentation for Problem::IsParameterBlockConstant
ba6e5fb4a Make the custom uninstall target optional
8547cbd55 Make EventLogger more efficient.
edb8322bd Update the minimum required version of Eigen to 3.3.
aa6ef417f Specify Eigen3_DIR in iOS and Android Travis CI builds
4655f2549 Use find_package() instead of find_dependency() in CeresConfig.cmake
a548766d1 Use glfags target
33dd469a5 Use Eigen3::Eigen target
47e784bb4 NULL-jacobians are handled correctly in generated autodiff code
edd54b83e Update Jet.h and rotation.h to use the new IF/ELSE macros
848c1f90c Update return type in code generator and add tests for logical functions
5010421bb Add the expression return type as a member to Expression
f4dc670ee Improve testing of the codegen system
572ec4a5a Rework Expression creation and insertion
c7337154e Disable the code generation module by default
7fa0f3db4 Explicitly state PUBLIC/PRIVATE when linking
4362a2169 Run clang-format on the public headers. Also update copyright year.
c56702aac Fix installation of codegen headers
0d03e74dc Fix the include in the autodiff codegen example
d16026440 Autodiff Codegen Part 4: Public API
d1703db45 Moved AutoDiffCodeGen macros to a separate (public) header
5ce6c063d Fix ExpressionRef copy constructor and add a move constructor
a90b5a12c Pass ExpressionRef by const reference instead of by value
ea057678c Remove MakeFunctionCall() and add test for Ternary
1084c5460 Quote all configure-expanded paths
3d756b07c Test Expressions with 'insert' instead of a macro
486d81812 Add ExpressionGraph::InsertExpression
3831a1dd3 Expression and ExpressionGraph comparison
9bb1dcb84 Remove definition of ExpressionRef::ExpressionRef(double&);
5be2e4883 Autodiff Codegen Part 3: CodeGenerator
6cd633043 Remove unused ExpressionTypes
7d0d69a4d Fix ExpressionRef
6ba8c57d2 Fix expression_test IsArithmetic
2b494cfb3 Update Travis CI to Bionic & Xcode 11.2
a3dde6877 Require Xcode >= 11.2 on macOS 10.15 (Catalina)
6fd4f072d Autodiff Codegen Part 2: Conditionals
52d6477a4 Detect and disable -fstack-check on macOS 10.15 with Xcode 11
46ca461b7 Fix `gradient_check_relative_precision` docs typo
4247d420f Autodiff Codegen Part 1: Expressions
ba62397d8 Run clang-format on jet.h
667062dcc Introduce BlockSparseMatrixData
17becf461 Remove a CHECK failure from covariance_impl.cc
d7f428e5c Add a missing cast in rotation.h
ea4d66e7e clang-tidy fixes.
be15b842a Integrate the SchurEliminatorForOneFBlock for the case <2,3,6>
087b28f1b Remove use of SetUsage as it creates compilation problems.
573046d7f Protect declarations of lapack functions under CERES_NO_LAPACK
71d638ef3 Add a specialized schur eliminator.
2ffddaccf Use override & final instead of just using virtual.
e4577dd6d Use override instead of virtual for subclasses.
3e5db5bc2 Fixing documentation typo.
82d325b73 Avoid memory allocations in Accelerate Sparse[Refactor/Solve]().
f66b51382 Fix some clang-tidy warnings.
0428e2dd0 Fix missing #include of <memory>
487c1aa51 Expose SubsetPreconditioner in the API
bf709ecac Move EvaluationCallback from Solver::Options to Problem::Options.
059bcb7f8 Drop ROS dependency on catkin
c4dbc927d Default to any other sparse libraries over Accelerate
db1f5b57a Allow some methods in Problem to use const double*.
a60c14525 Explicitly delete the copy constructor and copy assignment operator
084042c25 Lint changes from William Rucklidge
93d869020 Use selfAdjoingView<Upper> in InvertPSDMatrix.
a0cd0854a Speed up InvertPSDMatrix
7b53262b7 Allow Solver::Options::max_num_line_search_step_size_iterations = 0.
3e2cdca54 Make LineSearchMinizer work correctly with negative valued functions.
3ff12a878 Fix a clang-tidy warning in problem_test.cc
57441fe90 Fix two bugs.
1b852c57e Add Problem::EvaluateResidualBlock.
54ba6c27b Fix missing declaration warnings in Ceres code
fac46d50e Modernize ProductParameterization.
53dc6213f Add some missing string-to-enum-to-string convertors.
c0aa9a263 Add checks in rotation.h for inplace operations.
0f57fa82d Update Bazel WORKSPACE for newest Bazel
f8e5fba7b TripletSparseMatrix: guard against self-assignment
939253c20 Fix Eigen alignment issues.
bf67daf79 Add the missing <array> header to fixed_array.h
25e1cdbb6 Switch to FixedArray implementation from abseil.
d467a627b IdentityTransformation -> IdentityParameterization
eaec6a9d0 Fix more typos in CostFunctionToFunctor documentation.
99b5aa4aa Fix typos in CostFunctionToFunctor documentation.
ee7e2cb3c Set Homebrew paths via HINTS not CMAKE_PREFIX_PATH
4f8a01853 Revert "Fix custom Eigen on macos (EIGEN_INCLUDE_DIR_HINTS)"
e6c5c7226 Fix custom Eigen on macos (EIGEN_INCLUDE_DIR_HINTS)
5a56d522e Add the 3,3,3 template specialization.
df5c23116 Reorder initializer list to make -Wreorder happy
0fcfdb0b4 Fix the build breakage caused by the last commit.
9b9e9f0dc Reduce machoness of macro definition in cost_functor_to_function_test.cc
21d40daa0 Remove UTF-8 chars
9350e57a4 Enable optional use of sanitizers
0456edffb Update Travis CI Linux distro to 16.04 (Xenial)
bef0dfe35 Fix a typo in cubic_interpolation.h
056ba9bb1 Add AutoDiffFirstOrderFunction
6e527392d Update googletest/googlemock to db9b85e2.
1b2940749 Clarify documentation of BiCubicInterpolator::Evaluate for out-of-bounds values
Change-Id: Id61dd832e8fbe286deb0799aa1399d4017031dae
git-subtree-dir: third_party/ceres
git-subtree-split: 399cda773035d99eaf1f4a129a666b3c4df9d1b1
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index b3dfb50..7f49783 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -9,7 +9,7 @@
.. _section-source:
You can start with the `latest stable release
-<http://ceres-solver.org/ceres-solver-1.14.0.tar.gz>`_ . Or if you want
+<http://ceres-solver.org/ceres-solver-2.0.0.tar.gz>`_ . Or if you want
the latest version, you can clone the git repository
.. code-block:: bash
@@ -23,16 +23,15 @@
.. NOTE ::
- All versions of Ceres > 1.14 require a **fully C++11-compliant**
- compiler. In versions <= 1.14, C++11 was an optional requirement
- controlled by the ``CXX11 [Default: OFF]`` build option.
+ Starting with v2.0 Ceres requires a **fully C++14-compliant**
+ compiler. In versions <= 1.14, C++11 was an optional requirement.
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` .
- `Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_
- 3.2.2 or later **strongly** recommended, 3.1.0 or later **required**.
+ 3.3 or later **required**.
.. NOTE ::
@@ -40,8 +39,7 @@
library. Please see the documentation for ``EIGENSPARSE`` for
more details.
-- `CMake <http://www.cmake.org>`_ 3.5 or later.
- **Required on all platforms except for legacy Android.**
+- `CMake <http://www.cmake.org>`_ 3.5 or later **required**.
- `glog <https://github.com/google/glog>`_ 0.3.1 or
later. **Recommended**
@@ -77,13 +75,21 @@
<https://code.google.com/p/google-glog/issues/detail?id=194>`_.
- `gflags <https://github.com/gflags/gflags>`_. Needed to build
- examples and tests.
+ examples and tests and usually a dependency for glog.
- `SuiteSparse
<http://faculty.cse.tamu.edu/davis/suitesparse.html>`_. Needed for
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
@@ -98,7 +104,7 @@
``SuiteSparse``, and optionally used by Ceres directly for some
operations.
- On ``UNIX`` OSes other than Mac OS X we recommend `ATLAS
+ On ``UNIX`` OSes other than macOS we recommend `ATLAS
<http://math-atlas.sourceforge.net/>`_, which includes ``BLAS`` and
``LAPACK`` routines. It is also possible to use `OpenBLAS
<https://github.com/xianyi/OpenBLAS>`_ . However, one needs to be
@@ -106,7 +112,7 @@
<https://github.com/xianyi/OpenBLAS/wiki/faq#wiki-multi-threaded>`_
inside ``OpenBLAS`` as it conflicts with use of threads in Ceres.
- Mac OS X ships with an optimized ``LAPACK`` and ``BLAS``
+ MacOS ships with an optimized ``LAPACK`` and ``BLAS``
implementation as part of the ``Accelerate`` framework. The Ceres
build system will automatically detect and use it.
@@ -124,18 +130,11 @@
We will use `Ubuntu <http://www.ubuntu.com>`_ as our example linux
distribution.
-.. NOTE::
+ .. NOTE ::
- Up to at least Ubuntu 14.04, the SuiteSparse package in the official
- package repository (built from SuiteSparse v3.4.0) **cannot** be used
- to build Ceres as a *shared* library. Thus if you want to build
- Ceres as a shared library using SuiteSparse, you must perform a
- source install of SuiteSparse or use an external PPA (see `bug report
- here
- <https://bugs.launchpad.net/ubuntu/+source/suitesparse/+bug/1333214>`_).
- It is recommended that you use the current version of SuiteSparse
- (4.2.1 at the time of writing).
-
+ These instructions are for Ubuntu 18.04 and newer. On Ubuntu 16.04
+ you need to manually get a more recent version of Eigen, such as
+ 3.3.7.
Start by installing all the dependencies.
@@ -144,30 +143,22 @@
# CMake
sudo apt-get install cmake
# google-glog + gflags
- sudo apt-get install libgoogle-glog-dev
+ sudo apt-get install libgoogle-glog-dev libgflags-dev
# BLAS & LAPACK
sudo apt-get install libatlas-base-dev
# Eigen3
sudo apt-get install libeigen3-dev
# SuiteSparse and CXSparse (optional)
- # - If you want to build Ceres as a *static* library (the default)
- # you can use the SuiteSparse package in the main Ubuntu package
- # repository:
- sudo apt-get install libsuitesparse-dev
- # - However, if you want to build Ceres as a *shared* library, you must
- # add the following PPA:
- sudo add-apt-repository ppa:bzindovic/suitesparse-bugfix-1319687
- sudo apt-get update
sudo apt-get install libsuitesparse-dev
We are now ready to build, test, and install Ceres.
.. code-block:: bash
- tar zxf ceres-solver-1.14.0.tar.gz
+ tar zxf ceres-solver-2.0.0.tar.gz
mkdir ceres-bin
cd ceres-bin
- cmake ../ceres-solver-1.14.0
+ cmake ../ceres-solver-2.0.0
make -j3
make test
# Optionally install Ceres, it can also be exported using CMake which
@@ -181,7 +172,7 @@
.. code-block:: bash
- bin/simple_bundle_adjuster ../ceres-solver-1.14.0/data/problem-16-22106-pre.txt
+ bin/simple_bundle_adjuster ../ceres-solver-2.0.0/data/problem-16-22106-pre.txt
This runs Ceres for a maximum of 10 iterations using the
``DENSE_SCHUR`` linear solver. The output should look something like
@@ -198,7 +189,7 @@
5 1.803399e+04 5.33e+01 1.48e+04 1.23e+01 9.99e-01 8.33e+05 1 1.45e-01 1.08e+00
6 1.803390e+04 9.02e-02 6.35e+01 8.00e-01 1.00e+00 2.50e+06 1 1.50e-01 1.23e+00
- Ceres Solver v1.14.0 Solve Report
+ Ceres Solver v2.0.0 Solve Report
----------------------------------
Original Reduced
Parameter blocks 22122 22122
@@ -239,30 +230,16 @@
Termination: CONVERGENCE (Function tolerance reached. |cost_change|/cost: 1.769766e-09 <= 1.000000e-06)
-.. section-osx:
+.. section-macos:
-Mac OS X
-========
-.. NOTE::
+macOS
+=====
- Ceres will not compile using Xcode 4.5.x (Clang version 4.1) due to a
- bug in that version of Clang. If you are running Xcode 4.5.x, please
- update to Xcode >= 4.6.x before attempting to build Ceres.
+On macOS, you can either use `Homebrew
+<https://brew.sh/>`_ (recommended) or `MacPorts
+<https://www.macports.org/>`_ to install Ceres Solver.
-
-On OS X, you can either use `MacPorts <https://www.macports.org/>`_ or
-`Homebrew <http://mxcl.github.com/homebrew/>`_ to install Ceres Solver.
-
-If using `MacPorts <https://www.macports.org/>`_, then
-
-.. code-block:: bash
-
- sudo port install ceres-solver
-
-will install the latest version.
-
-If using `Homebrew <http://mxcl.github.com/homebrew/>`_ and assuming
-that you have the ``homebrew/science`` [#f1]_ tap enabled, then
+If using `Homebrew <https://brew.sh/>`_, then
.. code-block:: bash
@@ -277,9 +254,17 @@
will install the latest version in the git repo.
+If using `MacPorts <https://www.macports.org/>`_, then
+
+.. code-block:: bash
+
+ sudo port install ceres-solver
+
+will install the latest version.
+
You can also install each of the dependencies by hand using `Homebrew
-<http://mxcl.github.com/homebrew/>`_. There is no need to install
-``BLAS`` or ``LAPACK`` separately as OS X ships with optimized
+<https://brew.sh/>`_. There is no need to install
+``BLAS`` or ``LAPACK`` separately as macOS ships with optimized
``BLAS`` and ``LAPACK`` routines as part of the `vecLib
<https://developer.apple.com/library/mac/#documentation/Performance/Conceptual/vecLib/Reference/reference.html>`_
framework.
@@ -289,7 +274,7 @@
# CMake
brew install cmake
# google-glog and gflags
- brew install glog
+ brew install glog gflags
# Eigen3
brew install eigen
# SuiteSparse and CXSparse
@@ -299,10 +284,10 @@
.. code-block:: bash
- tar zxf ceres-solver-1.14.0.tar.gz
+ tar zxf ceres-solver-2.0.0.tar.gz
mkdir ceres-bin
cd ceres-bin
- cmake ../ceres-solver-1.14.0
+ cmake ../ceres-solver-2.0.0
make -j3
make test
# Optionally install Ceres, it can also be exported using CMake which
@@ -310,13 +295,13 @@
# documentation for the EXPORT_BUILD_DIR option for more information.
make install
-Building with OpenMP on OS X
-----------------------------
+Building with OpenMP on macOS
+-----------------------------
-Up to at least Xcode 8, OpenMP support was disabled in Apple's version of
+Up to at least Xcode 12, OpenMP support was disabled in Apple's version of
Clang. However, you can install the latest version of the LLVM toolchain
from Homebrew which does support OpenMP, and thus build Ceres with OpenMP
-support on OS X. To do this, you must install llvm via Homebrew:
+support on macOS. To do this, you must install llvm via Homebrew:
.. code-block:: bash
@@ -330,7 +315,7 @@
.. code-block:: bash
- tar zxf ceres-solver-1.14.0.tar.gz
+ tar zxf ceres-solver-2.0.0.tar.gz
mkdir ceres-bin
cd ceres-bin
# Configure the local shell only (not persistent) to use the Homebrew LLVM
@@ -340,9 +325,8 @@
export LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"
export PATH="/usr/local/opt/llvm/bin:$PATH"
- # Force CMake to use the Homebrew version of Clang. OpenMP will be
- # automatically enabled if it is detected that the compiler supports it.
- cmake -DCMAKE_C_COMPILER=/usr/local/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/usr/local/opt/llvm/bin/clang++ ../ceres-solver-1.14.0
+ # Force CMake to use the Homebrew version of Clang and enable OpenMP.
+ cmake -DCMAKE_C_COMPILER=/usr/local/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/usr/local/opt/llvm/bin/clang++ -DCERES_THREADING_MODEL=OPENMP ../ceres-solver-2.0.0
make -j3
make test
# Optionally install Ceres. It can also be exported using CMake which
@@ -353,19 +337,6 @@
Like the Linux build, you should now be able to run
``bin/simple_bundle_adjuster``.
-
-.. rubric:: Footnotes
-
-.. [#f1] Ceres and many of its dependencies are in `homebrew/science
- <https://github.com/Homebrew/homebrew-science>`_ tap. So, if you
- don't have this tap enabled, then you will need to enable it as
- follows before executing any of the commands in this section.
-
- .. code-block:: bash
-
- brew tap homebrew/science
-
-
.. _section-windows:
Windows
@@ -378,9 +349,9 @@
<https://github.com/tbennun/ceres-windows>`_ for Ceres Solver by Tal
Ben-Nun.
-On Windows, we support building with Visual Studio 2013 Release 4 or newer. Note
+On Windows, we support building with Visual Studio 2015.2 of newer. Note
that the Windows port is less featureful and less tested than the
-Linux or Mac OS X versions due to the lack of an officially supported
+Linux or macOS versions due to the lack of an officially supported
way of building SuiteSparse and CXSparse. There are however a number
of unofficial ways of building these libraries. Building on Windows
also a bit more involved since there is no automated way to install
@@ -409,8 +380,9 @@
#. Get dependencies; unpack them as subdirectories in ``ceres/``
(``ceres/eigen``, ``ceres/glog``, etc)
- #. ``Eigen`` 3.1 (needed on Windows; 3.0.x will not work). There is
- no need to build anything; just unpack the source tarball.
+ #. ``Eigen`` 3.3 . Configure and optionally install Eigen. It should be
+ exported into the CMake package registry by default as part of the
+ configure stage so installation should not be necessary.
#. ``google-glog`` Open up the Visual Studio solution and build it.
#. ``gflags`` Open up the Visual Studio solution and build it.
@@ -431,7 +403,7 @@
#. Unpack the Ceres tarball into ``ceres``. For the tarball, you
should get a directory inside ``ceres`` similar to
- ``ceres-solver-1.3.0``. Alternately, checkout Ceres via ``git`` to
+ ``ceres-solver-2.0.0``. Alternately, checkout Ceres via ``git`` to
get ``ceres-solver.git`` inside ``ceres``.
#. Install ``CMake``,
@@ -445,11 +417,10 @@
#. Try running ``Configure``. It won't work. It'll show a bunch of options.
You'll need to set:
- #. ``EIGEN_INCLUDE_DIR_HINTS``
+ #. ``Eigen3_DIR`` (Set to directory containing ``Eigen3Config.cmake``)
#. ``GLOG_INCLUDE_DIR_HINTS``
#. ``GLOG_LIBRARY_DIR_HINTS``
- #. ``GFLAGS_INCLUDE_DIR_HINTS``
- #. ``GFLAGS_LIBRARY_DIR_HINTS``
+ #. (Optional) ``gflags_DIR`` (Set to directory containing ``gflags-config.cmake``)
#. (Optional) ``SUITESPARSE_INCLUDE_DIR_HINTS``
#. (Optional) ``SUITESPARSE_LIBRARY_DIR_HINTS``
#. (Optional) ``CXSPARSE_INCLUDE_DIR_HINTS``
@@ -507,10 +478,10 @@
cmake \
-DCMAKE_TOOLCHAIN_FILE=\
$NDK_DIR/build/cmake/android.toolchain.cmake \
- -DEIGEN_INCLUDE_DIR=/path/to/eigen/header \
- -DANDROID_ABI=armeabi-v7a \
+ -DEigen3_DIR=/path/to/Eigen3Config.cmake \
+ -DANDROID_ABI=arm64-v8a \
-DANDROID_STL=c++_shared \
- -DANDROID_NATIVE_API_LEVEL=android-24 \
+ -DANDROID_NATIVE_API_LEVEL=android-29 \
-DBUILD_SHARED_LIBS=ON \
-DMINIGLOG=ON \
<PATH_TO_CERES_SOURCE>
@@ -538,6 +509,7 @@
the sample by running for example:
.. code-block:: bash
+
adb shell
cd /data/local/tmp
LD_LIBRARY_PATH=/data/local/tmp ./helloworld
@@ -563,7 +535,7 @@
cmake \
-DCMAKE_TOOLCHAIN_FILE=../ceres-solver/cmake/iOS.cmake \
- -DEIGEN_INCLUDE_DIR=/path/to/eigen/header \
+ -DEigen3_DIR=/path/to/Eigen3Config.cmake \
-DIOS_PLATFORM=<PLATFORM> \
<PATH_TO_CERES_SOURCE>
@@ -693,15 +665,6 @@
#. ``EIGENSPARSE [Default: ON]``: By default, Ceres will not use
Eigen's sparse Cholesky factorization.
- .. NOTE::
-
- For good performance, use Eigen version 3.2.2 or later.
-
- .. NOTE::
-
- Unlike the rest of Eigen (>= 3.1.1 MPL2, < 3.1.1 LGPL), Eigen's sparse
- Cholesky factorization is (still) licensed under the LGPL.
-
#. ``GFLAGS [Default: ON]``: Turn this ``OFF`` to build Ceres without
``gflags``. This will also prevent some of the example code from
building.
@@ -717,7 +680,7 @@
gains in the ``SPARSE_SCHUR`` solver, you can disable some of the
template specializations by turning this ``OFF``.
-#. ``CERES_THREADING_MODEL [Default: CXX11_THREADS > OPENMP > NO_THREADS]``:
+#. ``CERES_THREADING_MODEL [Default: CXX_THREADS > OPENMP > NO_THREADS]``:
Multi-threading backend Ceres should be compiled with. This will
automatically be set to only accept the available subset of threading
options in the CMake GUI.
@@ -730,10 +693,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
@@ -769,8 +732,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
@@ -826,7 +797,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
@@ -858,13 +829,13 @@
# helloworld
add_executable(helloworld helloworld.cc)
- target_link_libraries(helloworld ${CERES_LIBRARIES})
+ target_link_libraries(helloworld Ceres::ceres)
Irrespective of whether Ceres was installed or exported, if multiple
versions are detected, set: ``Ceres_DIR`` to control which is used.
If Ceres was installed ``Ceres_DIR`` should be the path to the
directory containing the installed ``CeresConfig.cmake`` file
-(e.g. ``/usr/local/share/Ceres``). If Ceres was exported, then
+(e.g. ``/usr/local/lib/cmake/Ceres``). If Ceres was exported, then
``Ceres_DIR`` should be the path to the exported Ceres build
directory.
@@ -874,6 +845,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
-------------------------------------
@@ -912,11 +884,9 @@
#. ``Multithreading``: Ceres built with *a* multithreading library.
This is equivalent to (``CERES_THREAD != NO_THREADS``).
-#. ``C++11``: Ceres built with C++11.
-
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
@@ -934,7 +904,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
@@ -992,9 +962,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
@@ -1007,10 +977,10 @@
directory is exported into the local CMake package registry (see
:ref:`section-install-vs-export`), in addition to the public headers
and compiled libraries, a set of CMake-specific project configuration
-files are also installed to: ``<INSTALL_ROOT>/share/Ceres`` (if Ceres
+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
@@ -1022,9 +992,9 @@
Which is written by the developers of the project, and is
configured with the selected options and installed locations when
- the project is built and defines the CMake variables:
- ``<PROJECT_NAME>_INCLUDE_DIRS`` & ``<PROJECT_NAME>_LIBRARIES``
- which are used by the caller to import the project.
+ the project is built and imports the project targets and/or defines
+ the legacy CMake variables: ``<PROJECT_NAME>_INCLUDE_DIRS`` &
+ ``<PROJECT_NAME>_LIBRARIES`` which are used by the caller.
The ``<PROJECT_NAME>Config.cmake`` typically includes a second file
installed to the same location:
@@ -1039,39 +1009,33 @@
project using ``add_library()``. However, imported targets refer to
objects that have already been built by a different CMake project.
Principally, an imported target contains the location of the compiled
-object and all of its public dependencies required to link against it.
-Any locally declared target can depend on an imported target, and
-CMake will manage the dependency chain, just as if the imported target
-had been declared locally by the current project.
+object and all of its public dependencies required to link against it
+as well as all required include directories. Any locally declared target
+can depend on an imported target, and CMake will manage the dependency
+chain, just as if the imported target had been declared locally by the
+current project.
Crucially, just like any locally declared CMake target, an imported target is
identified by its **name** when adding it as a dependency to another target.
-Thus, if in a project using Ceres you had the following in your CMakeLists.txt:
+Since v2.0, Ceres has used the target namespace feature of CMake to prefix
+its export targets: ``Ceres::ceres``. However, historically the Ceres target
+did not have a namespace, and was just called ``ceres``.
-.. code-block:: cmake
-
- find_package(Ceres REQUIRED)
- message("CERES_LIBRARIES = ${CERES_LIBRARIES}")
-
-You would see the output: ``CERES_LIBRARIES = ceres``. **However**,
-here ``ceres`` is an **imported target** created when
-``CeresTargets.cmake`` was read as part of ``find_package(Ceres
-REQUIRED)``. It does **not** refer (directly) to the compiled Ceres
-library: ``libceres.a/so/dylib/lib``. This distinction is important,
-as depending on the options selected when it was built, Ceres can have
-public link dependencies which are encapsulated in the imported target
-and automatically added to the link step when Ceres is added as a
-dependency of another target by CMake. In this case, linking only
-against ``libceres.a/so/dylib/lib`` without these other public
-dependencies would result in a linker error.
+Whilst an alias target called ``ceres`` is still provided in v2.0 for backwards
+compatibility, it creates a potential drawback, if you failed to call
+``find_package(Ceres)``, and Ceres is installed in a default search path for
+your compiler, then instead of matching the imported Ceres target, it will
+instead match the installed libceres.so/dylib/a library. If this happens you
+will get either compiler errors for missing include directories or linker errors
+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`.
@@ -1087,8 +1051,8 @@
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>`_,
-``<USER_HOME>/.cmake/packages`` on Linux & OS X, which contains the
+<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
client code uses the compiled libraries and headers in the build
@@ -1128,26 +1092,6 @@
.. code-block:: cmake
- # Importing Ceres in FooConfig.cmake using CMake 2.8.x style.
- #
- # When configure_file() is used to generate FooConfig.cmake from
- # FooConfig.cmake.in, @Ceres_DIR@ will be replaced with the current
- # value of Ceres_DIR being used by Foo. This should be passed as a hint
- # when invoking find_package(Ceres) to ensure that the same install of
- # Ceres is used as was used to build Foo.
- set(CERES_DIR_HINTS @Ceres_DIR@)
-
- # Forward the QUIET / REQUIRED options.
- if (Foo_FIND_QUIETLY)
- find_package(Ceres QUIET HINTS ${CERES_DIR_HINTS})
- elseif (Foo_FIND_REQUIRED)
- find_package(Ceres REQUIRED HINTS ${CERES_DIR_HINTS})
- else ()
- find_package(Ceres HINTS ${CERES_DIR_HINTS})
- endif()
-
-.. code-block:: cmake
-
# Importing Ceres in FooConfig.cmake using CMake 3.x style.
#
# In CMake v3.x, the find_dependency() macro exists to forward the REQUIRED
@@ -1158,3 +1102,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.