1 .. _chapter-installation:
7 Getting the source code
8 =======================
11 You can start with the `latest stable release
12 <http://ceres-solver.org/ceres-solver-1.13.0.tar.gz>`_ . Or if you want
13 the latest version, you can clone the git repository
17 git clone https://ceres-solver.googlesource.com/ceres-solver
19 .. _section-dependencies:
24 Ceres relies on a number of open source libraries, some of which are
25 optional. For details on customizing the build process, see
26 :ref:`section-customizing` .
28 - `Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_
29 3.2.2 or later **strongly** recommended, 3.1.0 or later **required**.
33 Ceres can also use Eigen as a sparse linear algebra
34 library. Please see the documentation for ``EIGENSPARSE`` for
37 - `CMake <http://www.cmake.org>`_ 2.8.0 or later.
38 **Required on all platforms except for Android.**
40 - `glog <https://github.com/google/glog>`_ 0.3.1 or
41 later. **Recommended**
43 ``glog`` is used extensively throughout Ceres for logging detailed
44 information about memory allocations and time consumed in various
45 parts of the solve, internal error conditions etc. The Ceres
46 developers use it extensively to observe and analyze Ceres's
47 performance. `glog <https://github.com/google/glog>`_ allows you to
48 control its behaviour from the command line. Starting with
49 ``-logtostderr`` you can add ``-v=N`` for increasing values of ``N``
50 to get more and more verbose and detailed information about Ceres
53 Unfortunately, the current version of `google-glog
54 <https://github.com/google/glog>`_ does not build using the Android
55 NDK. So, Ceres also ships with a minimal replacement of ``glog``
56 called ``miniglog`` that can be enabled with the ``MINIGLOG`` build
59 So, in an attempt to reduce dependencies, it is tempting to use
60 `miniglog` on platforms other than Android. While there is nothing
61 preventing the user from doing so, we strongly recommend against
62 it. ``miniglog`` has worse performance than ``glog`` and is much
63 harder to control and use.
67 If you are compiling ``glog`` from source, please note that
68 currently, the unit tests for ``glog`` (which are enabled by
69 default) do not compile against a default build of ``gflags`` 2.1
70 as the gflags namespace changed from ``google::`` to
71 ``gflags::``. A patch to fix this is available from `here
72 <https://code.google.com/p/google-glog/issues/detail?id=194>`_.
74 - `gflags <https://github.com/gflags/gflags>`_. Needed to build
78 <http://faculty.cse.tamu.edu/davis/suitesparse.html>`_. Needed for
79 solving large sparse linear systems. **Optional; strongly recomended
80 for large scale bundle adjustment**
82 - `CXSparse <http://faculty.cse.tamu.edu/davis/suitesparse.html>`_.
83 Similar to ``SuiteSparse`` but simpler and slower. CXSparse has
84 no dependencies on ``LAPACK`` and ``BLAS``. This makes for a simpler
85 build process and a smaller binary. **Optional**
87 - `BLAS <http://www.netlib.org/blas/>`_ and `LAPACK
88 <http://www.netlib.org/lapack/>`_ routines are needed by
89 ``SuiteSparse``, and optionally used by Ceres directly for some
92 On ``UNIX`` OSes other than Mac OS X we recommend `ATLAS
93 <http://math-atlas.sourceforge.net/>`_, which includes ``BLAS`` and
94 ``LAPACK`` routines. It is also possible to use `OpenBLAS
95 <https://github.com/xianyi/OpenBLAS>`_ . However, one needs to be
96 careful to `turn off the threading
97 <https://github.com/xianyi/OpenBLAS/wiki/faq#wiki-multi-threaded>`_
98 inside ``OpenBLAS`` as it conflicts with use of threads in Ceres.
100 Mac OS X ships with an optimized ``LAPACK`` and ``BLAS``
101 implementation as part of the ``Accelerate`` framework. The Ceres
102 build system will automatically detect and use it.
104 For Windows things are much more complicated. `LAPACK For
105 Windows <http://icl.cs.utk.edu/lapack-for-windows/lapack/>`_
106 has detailed instructions..
108 **Optional but required for** ``SuiteSparse``.
115 We will use `Ubuntu <http://www.ubuntu.com>`_ as our example linux
120 Up to at least Ubuntu 14.04, the SuiteSparse package in the official
121 package repository (built from SuiteSparse v3.4.0) **cannot** be used
122 to build Ceres as a *shared* library. Thus if you want to build
123 Ceres as a shared library using SuiteSparse, you must perform a
124 source install of SuiteSparse or use an external PPA (see `bug report
126 <https://bugs.launchpad.net/ubuntu/+source/suitesparse/+bug/1333214>`_).
127 It is recommended that you use the current version of SuiteSparse
128 (4.2.1 at the time of writing).
131 Start by installing all the dependencies.
136 sudo apt-get install cmake
137 # google-glog + gflags
138 sudo apt-get install libgoogle-glog-dev
140 sudo apt-get install libatlas-base-dev
142 sudo apt-get install libeigen3-dev
143 # SuiteSparse and CXSparse (optional)
144 # - If you want to build Ceres as a *static* library (the default)
145 # you can use the SuiteSparse package in the main Ubuntu package
147 sudo apt-get install libsuitesparse-dev
148 # - However, if you want to build Ceres as a *shared* library, you must
149 # add the following PPA:
150 sudo add-apt-repository ppa:bzindovic/suitesparse-bugfix-1319687
152 sudo apt-get install libsuitesparse-dev
154 We are now ready to build, test, and install Ceres.
158 tar zxf ceres-solver-1.13.0.tar.gz
161 cmake ../ceres-solver-1.13.0
164 # Optionally install Ceres, it can also be exported using CMake which
165 # allows Ceres to be used without requiring installation, see the documentation
166 # for the EXPORT_BUILD_DIR option for more information.
169 You can also try running the command line bundling application with one of the
170 included problems, which comes from the University of Washington's BAL
175 bin/simple_bundle_adjuster ../ceres-solver-1.13.0/data/problem-16-22106-pre.txt
177 This runs Ceres for a maximum of 10 iterations using the
178 ``DENSE_SCHUR`` linear solver. The output should look something like
183 iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time
184 0 4.185660e+06 0.00e+00 1.09e+08 0.00e+00 0.00e+00 1.00e+04 0 7.59e-02 3.37e-01
185 1 1.062590e+05 4.08e+06 8.99e+06 5.36e+02 9.82e-01 3.00e+04 1 1.65e-01 5.03e-01
186 2 4.992817e+04 5.63e+04 8.32e+06 3.19e+02 6.52e-01 3.09e+04 1 1.45e-01 6.48e-01
187 3 1.899774e+04 3.09e+04 1.60e+06 1.24e+02 9.77e-01 9.26e+04 1 1.43e-01 7.92e-01
188 4 1.808729e+04 9.10e+02 3.97e+05 6.39e+01 9.51e-01 2.78e+05 1 1.45e-01 9.36e-01
189 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
190 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
192 Ceres Solver v1.13.0 Solve Report
193 ----------------------------------
195 Parameter blocks 22122 22122
196 Parameters 66462 66462
197 Residual blocks 83718 83718
198 Residual 167436 167436
200 Minimizer TRUST_REGION
202 Dense linear algebra library EIGEN
203 Trust region strategy LEVENBERG_MARQUARDT
206 Linear solver DENSE_SCHUR DENSE_SCHUR
208 Linear solver threads 1 1
209 Linear solver ordering AUTOMATIC 22106, 16
216 Minimizer iterations 6
223 Residual evaluation 0.082
224 Jacobian evaluation 0.412
231 Termination: CONVERGENCE (Function tolerance reached. |cost_change|/cost: 1.769766e-09 <= 1.000000e-06)
239 Ceres will not compile using Xcode 4.5.x (Clang version 4.1) due to a
240 bug in that version of Clang. If you are running Xcode 4.5.x, please
241 update to Xcode >= 4.6.x before attempting to build Ceres.
244 On OS X, you can either use `MacPorts <https://www.macports.org/>`_ or
245 `Homebrew <http://mxcl.github.com/homebrew/>`_ to install Ceres Solver.
247 If using `MacPorts <https://www.macports.org/>`_, then
251 sudo port install ceres-solver
253 will install the latest version.
255 If using `Homebrew <http://mxcl.github.com/homebrew/>`_ and assuming
256 that you have the ``homebrew/science`` [#f1]_ tap enabled, then
260 brew install ceres-solver
262 will install the latest stable version along with all the required
267 brew install ceres-solver --HEAD
269 will install the latest version in the git repo.
271 You can also install each of the dependencies by hand using `Homebrew
272 <http://mxcl.github.com/homebrew/>`_. There is no need to install
273 ``BLAS`` or ``LAPACK`` separately as OS X ships with optimized
274 ``BLAS`` and ``LAPACK`` routines as part of the `vecLib
275 <https://developer.apple.com/library/mac/#documentation/Performance/Conceptual/vecLib/Reference/reference.html>`_
282 # google-glog and gflags
286 # SuiteSparse and CXSparse
287 brew install suite-sparse
289 We are now ready to build, test, and install Ceres.
293 tar zxf ceres-solver-1.13.0.tar.gz
296 cmake ../ceres-solver-1.13.0
299 # Optionally install Ceres, it can also be exported using CMake which
300 # allows Ceres to be used without requiring installation, see the
301 # documentation for the EXPORT_BUILD_DIR option for more information.
304 Like the Linux build, you should now be able to run
305 ``bin/simple_bundle_adjuster``.
308 .. rubric:: Footnotes
310 .. [#f1] Ceres and many of its dependencies are in `homebrew/science
311 <https://github.com/Homebrew/homebrew-science>`_ tap. So, if you
312 don't have this tap enabled, then you will need to enable it as
313 follows before executing any of the commands in this section.
317 brew tap homebrew/science
327 If you find the following CMake difficult to set up, then you may
328 be interested in a `Microsoft Visual Studio wrapper
329 <https://github.com/tbennun/ceres-windows>`_ for Ceres Solver by Tal
332 On Windows, we support building with Visual Studio 2010 or newer. Note
333 that the Windows port is less featureful and less tested than the
334 Linux or Mac OS X versions due to the lack of an officially supported
335 way of building SuiteSparse and CXSparse. There are however a number
336 of unofficial ways of building these libraries. Building on Windows
337 also a bit more involved since there is no automated way to install
340 .. NOTE:: Using ``google-glog`` & ``miniglog`` with windows.h.
342 The windows.h header if used with GDI (Graphics Device Interface)
343 defines ``ERROR``, which conflicts with the definition of ``ERROR``
344 as a LogSeverity level in ``google-glog`` and ``miniglog``. There
345 are at least two possible fixes to this problem:
347 #. Use ``google-glog`` and define ``GLOG_NO_ABBREVIATED_SEVERITIES``
348 when building Ceres and your own project, as documented `here
349 <http://google-glog.googlecode.com/svn/trunk/doc/glog.html>`__.
350 Note that this fix will not work for ``miniglog``, but use of
351 ``miniglog`` is strongly discouraged on any platform for which
352 ``google-glog`` is available (which includes Windows).
353 #. If you do not require GDI, then define ``NOGDI`` **before**
354 including windows.h. This solution should work for both
355 ``google-glog`` and ``miniglog`` and is documented for
356 ``google-glog`` `here
357 <https://code.google.com/p/google-glog/issues/detail?id=33>`__.
359 #. Make a toplevel directory for deps & build & src somewhere: ``ceres/``
360 #. Get dependencies; unpack them as subdirectories in ``ceres/``
361 (``ceres/eigen``, ``ceres/glog``, etc)
363 #. ``Eigen`` 3.1 (needed on Windows; 3.0.x will not work). There is
364 no need to build anything; just unpack the source tarball.
366 #. ``google-glog`` Open up the Visual Studio solution and build it.
367 #. ``gflags`` Open up the Visual Studio solution and build it.
369 #. (Experimental) ``SuiteSparse`` Previously SuiteSparse was not
370 available on Windows, recently it has become possible to build
371 it on Windows using the `suitesparse-metis-for-windows
372 <https://github.com/jlblancoc/suitesparse-metis-for-windows>`_
373 project. If you wish to use ``SuiteSparse``, follow their
374 instructions for obtaining and building it.
376 #. (Experimental) ``CXSparse`` Previously CXSparse was not
377 available on Windows, there are now several ports that enable it
378 to be, including: `[1] <https://github.com/PetterS/CXSparse>`_
379 and `[2] <https://github.com/TheFrenchLeaf/CXSparse>`_. If you
380 wish to use ``CXSparse``, follow their instructions for
381 obtaining and building it.
383 #. Unpack the Ceres tarball into ``ceres``. For the tarball, you
384 should get a directory inside ``ceres`` similar to
385 ``ceres-solver-1.3.0``. Alternately, checkout Ceres via ``git`` to
386 get ``ceres-solver.git`` inside ``ceres``.
388 #. Install ``CMake``,
390 #. Make a dir ``ceres/ceres-bin`` (for an out-of-tree build)
392 #. Run ``CMake``; select the ``ceres-solver-X.Y.Z`` or
393 ``ceres-solver.git`` directory for the CMake file. Then select the
394 ``ceres-bin`` for the build dir.
396 #. Try running ``Configure``. It won't work. It'll show a bunch of options.
399 #. ``EIGEN_INCLUDE_DIR_HINTS``
400 #. ``GLOG_INCLUDE_DIR_HINTS``
401 #. ``GLOG_LIBRARY_DIR_HINTS``
402 #. ``GFLAGS_INCLUDE_DIR_HINTS``
403 #. ``GFLAGS_LIBRARY_DIR_HINTS``
404 #. (Optional) ``SUITESPARSE_INCLUDE_DIR_HINTS``
405 #. (Optional) ``SUITESPARSE_LIBRARY_DIR_HINTS``
406 #. (Optional) ``CXSPARSE_INCLUDE_DIR_HINTS``
407 #. (Optional) ``CXSPARSE_LIBRARY_DIR_HINTS``
409 to the appropriate directories where you unpacked/built them. If
410 any of the variables are not visible in the ``CMake`` GUI, create a
411 new entry for them. We recommend using the
412 ``<NAME>_(INCLUDE/LIBRARY)_DIR_HINTS`` variables rather than
413 setting the ``<NAME>_INCLUDE_DIR`` & ``<NAME>_LIBRARY`` variables
414 directly to keep all of the validity checking, and to avoid having
415 to specify the library files manually.
417 #. You may have to tweak some more settings to generate a MSVC
418 project. After each adjustment, try pressing Configure & Generate
419 until it generates successfully.
421 #. Open the solution and build it in MSVC
424 To run the tests, select the ``RUN_TESTS`` target and hit **Build
425 RUN_TESTS** from the build menu.
427 Like the Linux build, you should now be able to run
428 ``bin/simple_bundle_adjuster``.
432 #. The default build is Debug; consider switching it to release mode.
433 #. Currently ``system_test`` is not working properly.
434 #. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug``
436 #. The solvers supported on Windows are ``DENSE_QR``, ``DENSE_SCHUR``,
437 ``CGNR``, and ``ITERATIVE_SCHUR``.
438 #. We're looking for someone to work with upstream ``SuiteSparse`` to
439 port their build system to something sane like ``CMake``, and get a
440 fully supported Windows port.
448 Download the ``Android NDK`` version ``r9d`` or later. Run
449 ``ndk-build`` from inside the ``jni`` directory. Use the
450 ``libceres.a`` that gets created.
459 You need iOS version 7.0 or higher to build Ceres Solver.
461 To build Ceres for iOS, we need to force ``CMake`` to find the
462 toolchains from the iOS SDK instead of using the standard ones. For
468 -DCMAKE_TOOLCHAIN_FILE=../ceres-solver/cmake/iOS.cmake \
469 -DEIGEN_INCLUDE_DIR=/path/to/eigen/header \
470 -DIOS_PLATFORM=<PLATFORM> \
471 <PATH_TO_CERES_SOURCE>
473 ``PLATFORM`` can be: ``OS``, ``SIMULATOR`` or ``SIMULATOR64``. You can
474 build for ``OS`` (``armv7``, ``armv7s``, ``arm64``), ``SIMULATOR``
475 (``i386``) or ``SIMULATOR64`` (``x86_64``) separately and use ``lipo``
476 to merge them into one static library. See ``cmake/iOS.cmake`` for
479 After building, you will get a ``libceres.a`` library, which you will
480 need to add to your Xcode project.
482 The default CMake configuration builds a bare bones version of Ceres
483 Solver that only depends on Eigen (``MINIGLOG`` is compiled into Ceres
484 if it is used), this should be sufficient for solving small to
485 moderate sized problems (No ``SPARSE_SCHUR``,
486 ``SPARSE_NORMAL_CHOLESKY`` linear solvers and no ``CLUSTER_JACOBI``
487 and ``CLUSTER_TRIDIAGONAL`` preconditioners).
489 If you decide to use ``LAPACK`` and ``BLAS``, then you also need to
490 add ``Accelerate.framework`` to your Xcode project's linking
493 .. _section-customizing:
495 Customizing the build
496 =====================
498 It is possible to reduce the libraries needed to build Ceres and
499 customize the build process by setting the appropriate options in
500 ``CMake``. These options can either be set in the ``CMake`` GUI, or
501 via ``-D<OPTION>=<ON/OFF>`` when running ``CMake`` from the command
502 line. In general, you should only modify these options from their
503 defaults if you know what you are doing.
507 If you are setting variables via ``-D<VARIABLE>=<VALUE>`` when
508 calling ``CMake``, it is important to understand that this forcibly
509 **overwrites** the variable ``<VARIABLE>`` in the ``CMake`` cache at
510 the start of *every configure*.
512 This can lead to confusion if you are invoking the ``CMake`` `curses
513 <http://www.gnu.org/software/ncurses/ncurses.html>`_ terminal GUI
514 (via ``ccmake``, e.g. ```ccmake -D<VARIABLE>=<VALUE>
515 <PATH_TO_SRC>``). In this case, even if you change the value of
516 ``<VARIABLE>`` in the ``CMake`` GUI, your changes will be
517 **overwritten** with the value passed via ``-D<VARIABLE>=<VALUE>``
518 (if one exists) at the start of each configure.
520 As such, it is generally easier not to pass values to ``CMake`` via
521 ``-D`` and instead interactively experiment with their values in the
522 ``CMake`` GUI. If they are not present in the *Standard View*,
523 toggle to the *Advanced View* with ``<t>``.
525 Options controlling Ceres configuration
526 ---------------------------------------
528 #. ``LAPACK [Default: ON]``: By default Ceres will use ``LAPACK`` (&
529 ``BLAS``) if they are found. Turn this ``OFF`` to build Ceres
530 without ``LAPACK``. Turning this ``OFF`` also disables
531 ``SUITESPARSE`` as it depends on ``LAPACK``.
533 #. ``SUITESPARSE [Default: ON]``: By default, Ceres will link to
534 ``SuiteSparse`` if it and all of its dependencies are present. Turn
535 this ``OFF`` to build Ceres without ``SuiteSparse``. Note that
536 ``LAPACK`` must be ``ON`` in order to build with ``SuiteSparse``.
538 #. ``CXSPARSE [Default: ON]``: By default, Ceres will link to
539 ``CXSparse`` if all its dependencies are present. Turn this ``OFF``
540 to build Ceres without ``CXSparse``.
542 #. ``EIGENSPARSE [Default: OFF]``: By default, Ceres will not use
543 Eigen's sparse Cholesky factorization. The is because this part of
544 the code is licensed under the ``LGPL`` and since ``Eigen`` is a
545 header only library, including this code will result in an ``LGPL``
546 licensed version of Ceres.
550 For good performance, use Eigen version 3.2.2 or later.
552 #. ``GFLAGS [Default: ON]``: Turn this ``OFF`` to build Ceres without
553 ``gflags``. This will also prevent some of the example code from
556 #. ``MINIGLOG [Default: OFF]``: Ceres includes a stripped-down,
557 minimal implementation of ``glog`` which can optionally be used as
558 a substitute for ``glog``, thus removing ``glog`` as a required
559 dependency. Turn this ``ON`` to use this minimal ``glog``
562 #. ``SCHUR_SPECIALIZATIONS [Default: ON]``: If you are concerned about
563 binary size/compilation time over some small (10-20%) performance
564 gains in the ``SPARSE_SCHUR`` solver, you can disable some of the
565 template specializations by turning this ``OFF``.
567 #. ``OPENMP [Default: ON]``: On certain platforms like Android,
568 multi-threading with ``OpenMP`` is not supported. Turn this ``OFF``
569 to disable multi-threading.
571 #. ``CXX11 [Default: OFF]`` *Non-MSVC compilers only*.
573 Although Ceres does not currently use C++11, it does use
574 ``shared_ptr`` (required) and ``unordered_map`` (if available);
575 both of which existed in the previous iterations of what became the
576 C++11 standard: TR1 & C++0x. As such, Ceres can compile on
577 pre-C++11 compilers, using the TR1/C++0x versions of ``shared_ptr``
580 Note that when using GCC & Clang, compiling against the TR1/C++0x
581 versions: ``CXX11=OFF`` (the default) *does not* require
582 ``-std=c++11`` when compiling Ceres, *nor* does it require that any
583 client code using Ceres use ``-std=c++11``. However, this will
584 cause compile errors if any client code that uses Ceres also uses
585 C++11 (mismatched versions of ``shared_ptr`` & ``unordered_map``).
587 Enabling this option: ``CXX11=ON`` forces Ceres to use the C++11
588 versions of ``shared_ptr`` & ``unordered_map`` if they are
589 available, and thus imposes the requirement that all client code
590 using Ceres also compile with ``-std=c++11``. This requirement is
591 handled automatically through CMake target properties on the
592 exported Ceres target for CMake >= 2.8.12 (when it was introduced).
593 Thus, any client code which uses CMake will automatically be
594 compiled with ``-std=c++11``. **On CMake versions < 2.8.12, you
595 are responsible for ensuring that any code which uses Ceres is
596 compiled with** ``-std=c++11``.
598 On OS X 10.9+, Clang will use the C++11 versions of ``shared_ptr``
599 & ``unordered_map`` without ``-std=c++11`` and so this option does
600 not change the versions detected, although enabling it *will*
601 require that client code compile with ``-std=c++11``.
603 The following table summarises the effects of the ``CXX11`` option:
605 =================== ========== ================ ======================================
606 OS CXX11 Detected Version Ceres & client code require ``-std=c++11``
607 =================== ========== ================ ======================================
608 Linux (GCC & Clang) OFF tr1 **No**
609 Linux (GCC & Clang) ON std **Yes**
610 OS X 10.9+ OFF std **No**
611 OS X 10.9+ ON std **Yes**
612 =================== ========== ================ ======================================
614 The ``CXX11`` option does does not exist when using MSVC, as there
615 any new C++ features available are enabled by default, and there is
616 no analogue of ``-std=c++11``. It will however be available on
617 MinGW & CygWin, which can support ``-std=c++11``.
619 #. ``BUILD_SHARED_LIBS [Default: OFF]``: By default Ceres is built as
620 a static library, turn this ``ON`` to instead build Ceres as a
623 #. ``EXPORT_BUILD_DIR [Default: OFF]``: By default Ceres is configured
624 solely for installation, and so must be installed in order for
625 clients to use it. Turn this ``ON`` to export Ceres' build
626 directory location into the `user's local CMake package registry
627 <http://www.cmake.org/cmake/help/v3.2/manual/cmake-packages.7.html#user-package-registry>`_
628 where it will be detected **without requiring installation** in a
629 client project using CMake when `find_package(Ceres)
630 <http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_
633 #. ``BUILD_DOCUMENTATION [Default: OFF]``: Use this to enable building
634 the documentation, requires `Sphinx <http://sphinx-doc.org/>`_ and
635 the `sphinx-better-theme
636 <https://pypi.python.org/pypi/sphinx-better-theme>`_ package
637 available from the Python package index. In addition, ``make
638 ceres_docs`` can be used to build only the documentation.
640 #. ``MSVC_USE_STATIC_CRT [Default: OFF]`` *Windows Only*: By default
641 Ceres will use the Visual Studio default, *shared* C-Run Time (CRT)
642 library. Turn this ``ON`` to use the *static* C-Run Time library
645 #. ``LIB_SUFFIX [Default: "64" on non-Debian/Arch based 64-bit Linux,
646 otherwise: ""]``: The suffix to append to the library install
647 directory, built from:
648 ``${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX}``.
650 The filesystem hierarchy standard recommends that 64-bit systems
651 install native libraries to lib64 rather than lib. Most Linux
652 distributions follow this convention, but Debian and Arch based
653 distros do not. Note that the only generally sensible values for
654 ``LIB_SUFFIX`` are "" and "64".
656 Although by default Ceres will auto-detect non-Debian/Arch based
657 64-bit Linux distributions and default ``LIB_SUFFIX`` to "64", this
658 can always be overridden by manually specifying LIB_SUFFIX using:
659 ``-DLIB_SUFFIX=<VALUE>`` when invoking CMake.
662 Options controlling Ceres dependency locations
663 ----------------------------------------------
665 Ceres uses the ``CMake`` `find_package
666 <http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_
667 function to find all of its dependencies using
668 ``Find<DEPENDENCY_NAME>.cmake`` scripts which are either included in
669 Ceres (for most dependencies) or are shipped as standard with
670 ``CMake`` (for ``LAPACK`` & ``BLAS``). These scripts will search all
671 of the "standard" install locations for various OSs for each
672 dependency. However, particularly for Windows, they may fail to find
673 the library, in this case you will have to manually specify its
674 installed location. The ``Find<DEPENDENCY_NAME>.cmake`` scripts
675 shipped with Ceres support two ways for you to do this:
677 #. Set the *hints* variables specifying the *directories* to search in
678 preference, but in addition, to the search directories in the
679 ``Find<DEPENDENCY_NAME>.cmake`` script:
681 - ``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR_HINTS``
682 - ``<DEPENDENCY_NAME (CAPS)>_LIBRARY_DIR_HINTS``
684 These variables should be set via ``-D<VAR>=<VALUE>``
685 ``CMake`` arguments as they are not visible in the GUI.
687 #. Set the variables specifying the *explicit* include directory
688 and library file to use:
690 - ``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR``
691 - ``<DEPENDENCY_NAME (CAPS)>_LIBRARY``
693 This bypasses *all* searching in the
694 ``Find<DEPENDENCY_NAME>.cmake`` script, but validation is still
697 These variables are available to set in the ``CMake`` GUI. They are
698 visible in the *Standard View* if the library has not been found
699 (but the current Ceres configuration requires it), but are always
700 visible in the *Advanced View*. They can also be set directly via
701 ``-D<VAR>=<VALUE>`` arguments to ``CMake``.
703 Building using custom BLAS & LAPACK installs
704 ----------------------------------------------
706 If the standard find package scripts for ``BLAS`` & ``LAPACK`` which
707 ship with ``CMake`` fail to find the desired libraries on your system,
708 try setting ``CMAKE_LIBRARY_PATH`` to the path(s) to the directories
709 containing the ``BLAS`` & ``LAPACK`` libraries when invoking ``CMake``
710 to build Ceres via ``-D<VAR>=<VALUE>``. This should result in the
711 libraries being found for any common variant of each.
713 If you are building on an exotic system, or setting
714 ``CMAKE_LIBRARY_PATH`` does not work, or is not appropriate for some
715 other reason, one option would be to write your own custom versions of
716 ``FindBLAS.cmake`` & ``FindLAPACK.cmake`` specific to your
717 environment. In this case you must set ``CMAKE_MODULE_PATH`` to the
718 directory containing these custom scripts when invoking ``CMake`` to
719 build Ceres and they will be used in preference to the default
720 versions. However, in order for this to work, your scripts must
721 provide the full set of variables provided by the default scripts.
722 Also, if you are building Ceres with ``SuiteSparse``, the versions of
723 ``BLAS`` & ``LAPACK`` used by ``SuiteSparse`` and Ceres should be the
726 .. _section-using-ceres:
728 Using Ceres with CMake
729 ======================
731 In order to use Ceres in client code with CMake using `find_package()
732 <http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_
735 #. Ceres must have been installed with ``make install``. If the
736 install location is non-standard (i.e. is not in CMake's default
737 search paths) then it will not be detected by default, see:
738 :ref:`section-local-installations`.
740 Note that if you are using a non-standard install location you
741 should consider exporting Ceres instead, as this will not require
742 any extra information to be provided in client code for Ceres to
745 #. Or Ceres' build directory must have been exported by enabling the
746 ``EXPORT_BUILD_DIR`` option when Ceres was configured.
749 As an example of how to use Ceres, to compile `examples/helloworld.cc
750 <https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/helloworld.cc>`_
751 in a separate standalone project, the following CMakeList.txt can be
754 .. code-block:: cmake
756 cmake_minimum_required(VERSION 2.8)
760 find_package(Ceres REQUIRED)
761 include_directories(${CERES_INCLUDE_DIRS})
764 add_executable(helloworld helloworld.cc)
765 target_link_libraries(helloworld ${CERES_LIBRARIES})
767 Irrespective of whether Ceres was installed or exported, if multiple
768 versions are detected, set: ``Ceres_DIR`` to control which is used.
769 If Ceres was installed ``Ceres_DIR`` should be the path to the
770 directory containing the installed ``CeresConfig.cmake`` file
771 (e.g. ``/usr/local/share/Ceres``). If Ceres was exported, then
772 ``Ceres_DIR`` should be the path to the exported Ceres build
775 Specify Ceres components
776 -------------------------------------
778 You can specify particular Ceres components that you require (in order
779 for Ceres to be reported as found) when invoking
780 ``find_package(Ceres)``. This allows you to specify, for example,
781 that you require a version of Ceres built with SuiteSparse support.
782 By definition, if you do not specify any components when calling
783 ``find_package(Ceres)`` (the default) any version of Ceres detected
784 will be reported as found, irrespective of which components it was
787 The Ceres components which can be specified are:
789 #. ``LAPACK``: Ceres built using LAPACK (``LAPACK=ON``).
791 #. ``SuiteSparse``: Ceres built with SuiteSparse (``SUITESPARSE=ON``).
793 #. ``CXSparse``: Ceres built with CXSparse (``CXSPARSE=ON``).
795 #. ``EigenSparse``: Ceres built with Eigen's sparse Cholesky factorization
796 (``EIGENSPARSE=ON``).
798 #. ``SparseLinearAlgebraLibrary``: Ceres built with *at least one* sparse linear
799 algebra library. This is equivalent to ``SuiteSparse`` **OR** ``CXSparse``
800 **OR** ``EigenSparse``.
802 #. ``SchurSpecializations``: Ceres built with Schur specializations
803 (``SCHUR_SPECIALIZATIONS=ON``).
805 #. ``OpenMP``: Ceres built with OpenMP (``OPENMP=ON``).
807 #. ``C++11``: Ceres built with C++11 (``CXX11=ON``).
809 To specify one/multiple Ceres components use the ``COMPONENTS`` argument to
811 <http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_ like so:
813 .. code-block:: cmake
815 # Find a version of Ceres compiled with SuiteSparse & EigenSparse support.
817 # NOTE: This will report Ceres as **not** found if the detected version of
818 # Ceres was not compiled with both SuiteSparse & EigenSparse.
819 # Remember, if you have multiple versions of Ceres installed, you
820 # can use Ceres_DIR to specify which should be used.
821 find_package(Ceres REQUIRED COMPONENTS SuiteSparse EigenSparse)
824 Specify Ceres version
825 ---------------------
827 Additionally, when CMake has found Ceres it can optionally check the package
828 version, if it has been specified in the `find_package()
829 <http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_
832 .. code-block:: cmake
834 find_package(Ceres 1.2.3 REQUIRED)
836 .. _section-local-installations:
841 If Ceres was installed in a non-standard path by specifying
842 ``-DCMAKE_INSTALL_PREFIX="/some/where/local"``, then the user should
843 add the **PATHS** option to the ``find_package()`` command, e.g.,
845 .. code-block:: cmake
847 find_package(Ceres REQUIRED PATHS "/some/where/local/")
849 Note that this can be used to have multiple versions of Ceres
850 installed. However, particularly if you have only a single version of
851 Ceres which you want to use but do not wish to install to a system
852 location, you should consider exporting Ceres using the
853 ``EXPORT_BUILD_DIR`` option instead of a local install, as exported
854 versions of Ceres will be automatically detected by CMake,
855 irrespective of their location.
857 Understanding the CMake Package System
858 ----------------------------------------
860 Although a full tutorial on CMake is outside the scope of this guide,
861 here we cover some of the most common CMake misunderstandings that
862 crop up when using Ceres. For more detailed CMake usage, the
863 following references are very useful:
865 - The `official CMake tutorial <http://www.cmake.org/cmake-tutorial/>`_
867 Provides a tour of the core features of CMake.
869 - `ProjectConfig tutorial
870 <http://www.cmake.org/Wiki/CMake/Tutorials/How_to_create_a_ProjectConfig.cmake_file>`_
871 and the `cmake-packages documentation
872 <http://www.cmake.org/cmake/help/git-master/manual/cmake-packages.7.html>`_
874 Cover how to write a ``ProjectConfig.cmake`` file, discussed below,
875 for your own project when installing or exporting it using CMake.
876 It also covers how these processes in conjunction with
877 ``find_package()`` are actually handled by CMake. The
878 `ProjectConfig tutorial
879 <http://www.cmake.org/Wiki/CMake/Tutorials/How_to_create_a_ProjectConfig.cmake_file>`_
880 is the older style, currently used by Ceres for compatibility with
881 older versions of CMake.
883 .. NOTE :: **Targets in CMake.**
885 All libraries and executables built using CMake are represented as
886 *targets* created using `add_library()
887 <http://www.cmake.org/cmake/help/v3.2/command/add_library.html>`_
888 and `add_executable()
889 <http://www.cmake.org/cmake/help/v3.2/command/add_executable.html>`_.
890 Targets encapsulate the rules and dependencies (which can be other
891 targets) required to build or link against an object. This allows
892 CMake to implicitly manage dependency chains. Thus it is
893 sufficient to tell CMake that a library target: ``B`` depends on a
894 previously declared library target ``A``, and CMake will
895 understand that this means that ``B`` also depends on all of the
896 public dependencies of ``A``.
898 When a project like Ceres is installed using CMake, or its build
899 directory is exported into the local CMake package registry (see
900 :ref:`section-install-vs-export`), in addition to the public headers
901 and compiled libraries, a set of CMake-specific project configuration
902 files are also installed to: ``<INSTALL_ROOT>/share/Ceres`` (if Ceres
903 is installed), or created in the build directory (if Ceres' build
904 directory is exported). When `find_package
905 <http://www.cmake.org/cmake/help/v3.2/command/find_package.html>`_ is
906 invoked, CMake checks various standard install locations (including
907 ``/usr/local`` on Linux & UNIX systems), and the local CMake package
908 registry for CMake configuration files for the project to be found
909 (i.e. Ceres in the case of ``find_package(Ceres)``). Specifically it
912 - ``<PROJECT_NAME>Config.cmake`` (or
913 ``<lower_case_project_name>-config.cmake``)
915 Which is written by the developers of the project, and is
916 configured with the selected options and installed locations when
917 the project is built and defines the CMake variables:
918 ``<PROJECT_NAME>_INCLUDE_DIRS`` & ``<PROJECT_NAME>_LIBRARIES``
919 which are used by the caller to import the project.
921 The ``<PROJECT_NAME>Config.cmake`` typically includes a second file
922 installed to the same location:
924 - ``<PROJECT_NAME>Targets.cmake``
926 Which is autogenerated by CMake as part of the install process and defines
927 **imported targets** for the project in the caller's CMake scope.
929 An **imported target** contains the same information about a library
930 as a CMake target that was declared locally in the current CMake
931 project using ``add_library()``. However, imported targets refer to
932 objects that have already been built by a different CMake project.
933 Principally, an imported target contains the location of the compiled
934 object and all of its public dependencies required to link against it.
935 Any locally declared target can depend on an imported target, and
936 CMake will manage the dependency chain, just as if the imported target
937 had been declared locally by the current project.
939 Crucially, just like any locally declared CMake target, an imported target is
940 identified by its **name** when adding it as a dependency to another target.
942 Thus, if in a project using Ceres you had the following in your CMakeLists.txt:
944 .. code-block:: cmake
946 find_package(Ceres REQUIRED)
947 message("CERES_LIBRARIES = ${CERES_LIBRARIES}")
949 You would see the output: ``CERES_LIBRARIES = ceres``. **However**,
950 here ``ceres`` is an **imported target** created when
951 ``CeresTargets.cmake`` was read as part of ``find_package(Ceres
952 REQUIRED)``. It does **not** refer (directly) to the compiled Ceres
953 library: ``libceres.a/so/dylib/lib``. This distinction is important,
954 as depending on the options selected when it was built, Ceres can have
955 public link dependencies which are encapsulated in the imported target
956 and automatically added to the link step when Ceres is added as a
957 dependency of another target by CMake. In this case, linking only
958 against ``libceres.a/so/dylib/lib`` without these other public
959 dependencies would result in a linker error.
961 Note that this description applies both to projects that are
962 **installed** using CMake, and to those whose **build directory is
963 exported** using `export()
964 <http://www.cmake.org/cmake/help/v3.2/command/export.html>`_ (instead
966 <http://www.cmake.org/cmake/help/v3.2/command/install.html>`_). Ceres
967 supports both installation and export of its build directory if the
968 ``EXPORT_BUILD_DIR`` option is enabled, see
969 :ref:`section-customizing`.
971 .. _section-install-vs-export:
973 Installing a project with CMake vs Exporting its build directory
974 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
976 When a project is **installed**, the compiled libraries and headers
977 are copied from the source & build directory to the install location,
978 and it is these copied files that are used by any client code. When a
979 project's build directory is **exported**, instead of copying the
980 compiled libraries and headers, CMake creates an entry for the project
981 in the `user's local CMake package registry
982 <http://www.cmake.org/cmake/help/v3.2/manual/cmake-packages.7.html#user-package-registry>`_,
983 ``<USER_HOME>/.cmake/packages`` on Linux & OS X, which contains the
984 path to the project's build directory which will be checked by CMake
985 during a call to ``find_package()``. The effect of which is that any
986 client code uses the compiled libraries and headers in the build
987 directory directly, **thus not requiring the project to be installed
990 Installing / Exporting a project that uses Ceres
991 --------------------------------------------------
993 As described in `Understanding the CMake Package System`_, the contents of
994 the ``CERES_LIBRARIES`` variable is the **name** of an imported target which
995 represents Ceres. If you are installing / exporting your *own* project which
996 *uses* Ceres, it is important to understand that:
998 **Imported targets are not (re)exported when a project which imported them is
1001 Thus, when a project ``Foo`` which uses Ceres is exported, its list of
1002 dependencies as seen by another project ``Bar`` which imports ``Foo``
1003 via: ``find_package(Foo REQUIRED)`` will contain: ``ceres``. However,
1004 the definition of ``ceres`` as an imported target is **not
1005 (re)exported** when Foo is exported. Hence, without any additional
1006 steps, when processing ``Bar``, ``ceres`` will not be defined as an
1007 imported target. Thus, when processing ``Bar``, CMake will assume
1008 that ``ceres`` refers only to: ``libceres.a/so/dylib/lib`` (the
1009 compiled Ceres library) directly if it is on the current list of
1010 search paths. In which case, no CMake errors will occur, but ``Bar``
1011 will not link properly, as it does not have the required public link
1012 dependencies of Ceres, which are stored in the imported target
1015 The solution to this is for ``Foo`` (i.e., the project that uses
1016 Ceres) to invoke ``find_package(Ceres)`` in ``FooConfig.cmake``, thus
1017 ``ceres`` will be defined as an imported target when CMake processes
1018 ``Bar``. An example of the required modifications to
1019 ``FooConfig.cmake`` are show below:
1021 .. code-block:: cmake
1023 # Importing Ceres in FooConfig.cmake using CMake 2.8.x style.
1025 # When configure_file() is used to generate FooConfig.cmake from
1026 # FooConfig.cmake.in, @Ceres_DIR@ will be replaced with the current
1027 # value of Ceres_DIR being used by Foo. This should be passed as a hint
1028 # when invoking find_package(Ceres) to ensure that the same install of
1029 # Ceres is used as was used to build Foo.
1030 set(CERES_DIR_HINTS @Ceres_DIR@)
1032 # Forward the QUIET / REQUIRED options.
1033 if (Foo_FIND_QUIETLY)
1034 find_package(Ceres QUIET HINTS ${CERES_DIR_HINTS})
1035 elseif (Foo_FIND_REQUIRED)
1036 find_package(Ceres REQUIRED HINTS ${CERES_DIR_HINTS})
1038 find_package(Ceres HINTS ${CERES_DIR_HINTS})
1041 .. code-block:: cmake
1043 # Importing Ceres in FooConfig.cmake using CMake 3.x style.
1045 # In CMake v3.x, the find_dependency() macro exists to forward the REQUIRED
1046 # / QUIET parameters to find_package() when searching for dependencies.
1048 # Note that find_dependency() does not take a path hint, so if Ceres was
1049 # installed in a non-standard location, that location must be added to
1050 # CMake's search list before this call.
1051 include(CMakeFindDependencyMacro)
1052 find_dependency(Ceres)