docs/source/building.rst

.. _chapter-building:

========
Building
========

Ceres source code and documentation are hosted at
http://code.google.com/p/ceres-solver/ .

.. _section-dependencies:

Dependencies
============

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` .

1. `CMake <http://www.cmake.org>`_ is a cross platform build
system. Ceres needs a relatively recent version of CMake (version
2.8.0 or better).

2. `eigen3 <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_ is
used for doing all the low level matrix and linear algebra operations.

3. `google-glog <http://http://code.google.com/p/google-glog>`_ is
used for error checking and logging. Ceres needs glog version 0.3.1 or
later. Version 0.3 (which ships with Fedora 16) has a namespace bug
which prevents Ceres from building.

4. `gflags <http://code.google.com/p/gflags>`_ is a library for
processing command line flags. It is used by some of the examples and
tests. While it is not strictly necessary to build the library, we
strongly recommend building the library with gflags.


5. `SuiteSparse
<http://www.cise.ufl.edu/research/sparse/SuiteSparse/>`_ is used for
sparse matrix analysis, ordering and factorization. In particular
Ceres uses the AMD, COLAMD and CHOLMOD libraries. This is an optional
dependency.

6. `CXSparse <http://www.cise.ufl.edu/research/sparse/CXSparse/>`_ is
used for sparse matrix analysis, ordering and factorization. While it
is similar to SuiteSparse in scope, its performance is a bit worse but
is a much simpler library to build and does not have any other
dependencies. This is an optional dependency.

7. `BLAS <http://www.netlib.org/blas/>`_ and `LAPACK
<http://www.netlib.org/lapack/>`_ routines are needed by
SuiteSparse. We recommend either `GotoBlas2
<http://www.tacc.utexas.edu/tacc- projects/gotoblas2>`_ or `ATLAS
<http://math- atlas.sourceforge.net/>`_ , both of which ship with BLAS
and LAPACK routines.

8. `protobuf <http://code.google.com/p/protobuf/>`_ is used for
serializing and deserializing linear least squares problems to
disk. This is useful for debugging and testing. It is an optional
depdendency and without it some of the tests will be disabled.

.. _section-linux:

Building on Linux
=================
We will use `Ubuntu <http://www.ubuntu.com>`_ as our example platform.

#. ``CMake``

   .. code-block:: bash

      sudo apt-get install cmake

#. ``gflags`` can either be installed from source via the ``autoconf``
   invocation

   .. code-block:: bash

     tar -xvzf gflags-2.0.tar.gz
     cd gflags-2.0
     ./configure --prefix=/usr/local
     make
     sudo make install.


   or via the ``deb`` or ``rpm`` packages available on the ``gflags`` website.

#. ``google-glog`` must be configured to use the previously installed
   ``gflags``, rather than the stripped down version that is bundled
   with ``google-glog``. Assuming you have it installed in ``/usr/local`` the
   following ``autoconf`` invocation installs it.

   .. code-block:: bash

     tar -xvzf glog-0.3.2.tar.gz
     cd glog-0.3.2
     ./configure --with-gflags=/usr/local/
     make
     sudo make install

#. ``Eigen``

   .. code-block:: bash

      sudo apt-get install libeigen3-dev

#. ``SuiteSparse`` and ``CXSparse``

   .. code-block:: bash

      sudo apt-get install libsuitesparse-dev

   This should automatically bring in the necessary ``BLAS`` and
   ``LAPACK`` dependencies. By co-incidence on Ubuntu, this also
   installs ``CXSparse``.

#. ``protobuf``

   .. code-block:: bash

      sudo apt-get install libprotobuf-dev


We are now ready to build and test Ceres. Note that ``CMake`` requires
the exact path to the ``libglog.a`` and ``libgflag.a``.

.. code-block:: bash

 tar zxf ceres-solver-1.2.1.tar.gz
 mkdir ceres-bin
 cd ceres-bin
 cmake ../ceres-solver-1.2.1
 make -j3
 make test

You can also try running the command line bundling application with one of the
included problems, which comes from the University of Washington's BAL
dataset [Agarwal]_.

.. code-block:: bash

 bin/simple_bundle_adjuster \
   ../ceres-solver-1.2.1/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
this.

.. code-block:: bash

    0: f: 4.185660e+06 d: 0.00e+00 g: 1.09e+08 h: 0.00e+00 rho: 0.00e+00 mu: 1.00e+04 li:  0 it: 1.16e-01 tt: 3.39e-01
    1: f: 1.062590e+05 d: 4.08e+06 g: 8.99e+06 h: 5.36e+02 rho: 9.82e-01 mu: 3.00e+04 li:  1 it: 3.90e-01 tt: 7.29e-01
    2: f: 4.992817e+04 d: 5.63e+04 g: 8.32e+06 h: 3.19e+02 rho: 6.52e-01 mu: 3.09e+04 li:  1 it: 3.52e-01 tt: 1.08e+00
    3: f: 1.899774e+04 d: 3.09e+04 g: 1.60e+06 h: 1.24e+02 rho: 9.77e-01 mu: 9.26e+04 li:  1 it: 3.60e-01 tt: 1.44e+00
    4: f: 1.808729e+04 d: 9.10e+02 g: 3.97e+05 h: 6.39e+01 rho: 9.51e-01 mu: 2.78e+05 li:  1 it: 3.62e-01 tt: 1.80e+00
    5: f: 1.803399e+04 d: 5.33e+01 g: 1.48e+04 h: 1.23e+01 rho: 9.99e-01 mu: 8.33e+05 li:  1 it: 3.54e-01 tt: 2.16e+00
    6: f: 1.803390e+04 d: 9.02e-02 g: 6.35e+01 h: 8.00e-01 rho: 1.00e+00 mu: 2.50e+06 li:  1 it: 3.59e-01 tt: 2.52e+00

 Ceres Solver Report
 -------------------
                                      Original                  Reduced
 Parameter blocks                        22122                    22122
 Parameters                              66462                    66462
 Residual blocks                         83718                    83718
 Residual                               167436                   167436
 Trust Region Strategy     LEVENBERG_MARQUARDT

                                         Given                     Used
 Linear solver                     DENSE_SCHUR              DENSE_SCHUR
 Preconditioner                            N/A                      N/A
 Threads:                                    1                        1
 Linear solver threads                       1                        1
 Linear solver ordering              AUTOMATIC                 22106,16

 Cost:
 Initial                          4.185660e+06
 Final                            1.803390e+04
 Change                           4.167626e+06

 Number of iterations:
 Successful                                  6
 Unsuccessful                                0
 Total                                       6

 Time (in seconds):
 Preprocessor                        2.229e-01

   Evaluator::Residuals              7.438e-02
   Evaluator::Jacobians              6.790e-01
   Linear Solver                     1.681e+00
 Minimizer                           2.547e+00

 Postprocessor                       1.920e-02
 Total                               2.823e+00

 Termination:               FUNCTION_TOLERANCE

.. section-osx:

Building on Mac OS X
====================

On OS X, we recommend using the `homebrew
<http://mxcl.github.com/homebrew/>`_ package manager.


#. ``CMake``

   .. code-block:: bash

      brew install cmake

#. ``google-glog`` and ``gflags``

Installing ``google-glog`` takes also brings in ``gflags`` as a dependency.

   .. code-block:: bash

      brew install glog

#. ``Eigen3``

   .. code-block:: bash

      brew install eigen

#. ``SuiteSparse`` and ``CXSparse``

   .. code-block:: bash

      brew install suite-sparse

#. ``protobuf``

   .. code-block:: bash

      brew install protobuf


We are now ready to build and test Ceres.

.. code-block:: bash

   tar zxf ceres-solver-1.2.1.tar.gz
   mkdir ceres-bin
   cd ceres-bin
   cmake ../ceres-solver-1.2.1
   make -j3
   make test


Like the Linux build, you should now be able to run
``bin/simple_bundle_adjuster``.

.. _section-windows:

Building on Windows with Visual Studio
======================================

On Windows, we support building with Visual Studio 2010 or newer. Note
that the Windows port is less featureful and less tested than the
Linux or Mac OS X versions due to the unavaliability of SuiteSparse
and ``CXSparse``. Building is also more involved since there is no
automated way to install the dependencies.

#. Make a toplevel directory for deps & build & src somewhere: ``ceres/``
#. 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.

   #. ``google-glog`` Open up the Visual Studio solution and build it.
   #. ``gflags`` Open up the Visual Studio solution and build it.

#. 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
   get ``ceres-solver.git`` inside ``ceres``.

#. Install ``CMake``,

#. Make a dir ``ceres/ceres-bin`` (for an out-of-tree build)

#. Run ``CMake``; select the ``ceres-solver-X.Y.Z`` or
   ``ceres-solver.git`` directory for the CMake file. Then select the
   ``ceres-bin`` for the build dir.

#. Try running "Configure". It won't work. It'll show a bunch of options.
   You'll need to set:

   #. ``GLOG_INCLUDE``
   #. ``GLOG_LIB``
   #. ``GFLAGS_LIB``
   #. ``GFLAGS_INCLUDE``

   to the appropriate place where you unpacked/built them.

#. You may have to tweak some more settings to generate a MSVC
   project.  After each adjustment, try pressing Configure & Generate
   until it generates successfully.

#. Open the solution and build it in MSVC


To run the tests, select the ``RUN_TESTS`` target and hit **Build
RUN_TESTS** from the build menu.

Like the Linux build, you should now be able to run ``bin/simple_bundle_adjuster``.

Notes:

#. The default build is Debug; consider switching it to release mode.
#. Currently ``system_test`` is not working properly.
#. Building Ceres as a DLL is not supported; patches welcome.
#. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug``
   by default.
#. The solvers supported on Windows are ``DENSE_QR``, ``DENSE_SCHUR``,
   ``CGNR``, and ``ITERATIVE_SCHUR``.
#. We're looking for someone to work with upstream ``SuiteSparse`` to
   port their build system to something sane like ``CMake``, and get a
   supported Windows port.


.. _section-android:

Building on Android
===================


Download the ``Android NDK``. Run ``ndk-build`` from inside the
``jni`` directory. Use the ``libceres.a`` that gets created.

.. _section-customizing:

Customizing the build
=====================

It is possible to reduce the libraries needed to build Ceres and
customize the build process by passing appropriate flags to
``CMake``. Use these flags only if you really know what you are doing.

#. ``-DPROTOBUF=OFF`` : ``protobuf`` is a big dependency and if you do not
   care for the tests that depend on it and the logging support it
   enables, you can use this flag to turn it off.

#. ``-DSUITESPARSE=OFF`` : By default, Ceres will link to
   ``SuiteSparse`` if all its dependencies are present. Use this flag
   to buils Ceres without ``SuiteSparse``. This will also disable
   dependency checking for ``LAPACK`` and ``BLAS`` This saves on
   binary size, but the resulting version of Ceres is not suited to
   large scale problems due to the lack of a sparse Cholesky solver.
   This will reduce Ceres' dependencies down to ``Eigen``, ``gflags``
   and ``google-glog``.

#. ``-DCXSPARSE=OFF`` : By default, Ceres will link to ``CXSparse`` if all
   its dependencies are present. Use this flag to buils Ceres without
   ``CXSparse``. This saves on binary size, but the resulting version
   of Ceres is not suited to large scale problems due to the lack of a
   sparse Cholesky solver.  This will reduce Ceres' dependencies down
   to ``Eigen``, ``gflags`` and ``google-glog``.

#. ``-DGFLAGS=OFF`` : Use this flag to build Ceres without
   ``gflags``. This will also prevent some of the example code from
   building.

#. ``-DSCHUR_SPECIALIZATIONS=OFF`` : If you are concerned about binary
   size/compilation time over some small (10-20%) performance gains in
   the ``SPARSE_SCHUR`` solver, you can disable some of the template
   specializations by using this flag.

#. ``-DOPENMP=OFF`` : On certain platforms like Android,
   multithreading with ``OpenMP`` is not supported. Use this flag to
   disable multithreading.