docs/build.tex

%!TEX root = ceres.tex
\chapter{Building Ceres}
\label{chapter:build}
Ceres source code and documentation is hosted at
\url{http://code.google.com/p/ceres-solver/}.

\section{Dependencies}
Ceres relies on a number of open source libraries, some of which are optional. However, we recommend that you start out by building Ceres with all its dependencies. For details on customizing the build process, please see Section~\ref{sec:custom}.

\begin{enumerate}
\item{\cmake~\footnote{\url{http://www.cmake.org/}}} is the cross-platform build system used by Ceres.
\item{\eigen~\footnote{\url{http://eigen.tuxfamily.org}}} is used for doing all the low level matrix and
  linear algebra operations.

\item{\glog~\footnote{\url{http://code.google.com/p/google-glog}}} is used for error checking and logging.

 Note: Ceres requires \texttt{glog}\ version 0.3.1 or later. Version 0.3 (which ships with Fedora 16) has a namespace bug which prevents Ceres from building.

\item{\gflags~\footnote{\url{http://code.google.com/p/gflags}}} is used by the code in
  \texttt{examples}. It is also used by some of the tests. Strictly speaking it is not required to build the core library, we do not recommend building Ceres without it.
\item{\suitesparse~\footnote{\url{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.
\item{\blas\ and \lapack} are needed by
  \suitesparse.  We
  recommend either
  \texttt{GotoBlas2}~\footnote{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2}}
  or
  \texttt{ATLAS}~\footnote{\url{http://math-atlas.sourceforge.net/}},
    both of which ship with \blas\ and \lapack\ routines.
\item{\texttt{protobuf}~\footnote{\url{http://code.google.com/p/protobuf/}}} is an optional dependency that is used for serializing and deserializing linear least squares problems to disk. This is useful for debugging and testing. Without it, some of the tests will be disabled.
\end{enumerate}

Currently we support building on Linux and MacOS X. Support for other
platforms is forthcoming.

\section{Building on Linux}
We will use Ubuntu as our example platform.

\begin{enumerate}
\item{\cmake}
\begin{minted}{bash}
sudo apt-get install cmake
\end{minted}

\item{\gflags} can either be installed from source via the \texttt{autoconf} invocation
\begin{minted}{bash}
tar -xvzf gflags-2.0.tar.gz
cd gflags-2.0
./configure --prefix=/usr/local
make
sudo make install.
\end{minted}
or via the \texttt{deb} or \texttt{rpm} packages available on the \gflags\ website.

\item{\glog} must be configured to use the previously installed
\gflags, rather than the stripped down version that is bundled with \glog. Assuming you have it installed in \texttt{/usr/local} the following \texttt{autoconf} invocation installs it.
\begin{minted}{bash}
tar -xvzf glog-0.3.2.tar.gz
cd glog-0.3.2
./configure --with-gflags=/usr/local/
make
sudo make install
\end{minted}

\item{\eigen}
\begin{minted}{bash}
sudo apt-get install libeigen3-dev
\end{minted}

\item{\suitesparse}
\begin{minted}{bash}
sudo apt-get install libsuitesparse-dev
\end{minted}
This should automatically bring in the necessary \blas\ and \lapack\ dependencies.

\item{\texttt{protobuf}}
\begin{minted}{bash}
sudo apt-get install libprotobuf-dev
\end{minted}
\end{enumerate}


We are now ready to build and test Ceres. Note that \texttt{cmake} requires the exact path to the \texttt{libglog.a} and \texttt{libgflag.a}

\begin{minted}{bash}
tar zxf ceres-solver-1.0.tar.gz
mkdir ceres-bin
cd ceres-bin
cmake ../ceres-solver-1.0
make -j3
make test
\end{minted}

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~\cite{Agarwal10bal}:
\begin{minted}{bash}
examples/simple_bundle_adjuster \
  ../ceres-solver-1.0/data/problem-16-22106-pre.txt \
\end{minted}
This runs Ceres for a maximum of 10 iterations using the  \denseschur\ linear solver. The output should look something like this.
\clearpage
\begin{minted}{bash}
0: f: 1.598216e+06 d: 0.00e+00 g: 5.67e+18 h: 0.00e+00 rho: 0.00e+00 mu: 1.00e-04 li:  0
1: f: 1.116401e+05 d: 1.49e+06 g: 1.42e+18 h: 5.48e+02 rho: 9.50e-01 mu: 3.33e-05 li:  1
2: f: 4.923547e+04 d: 6.24e+04 g: 8.57e+17 h: 3.21e+02 rho: 6.79e-01 mu: 3.18e-05 li:  1
3: f: 1.884538e+04 d: 3.04e+04 g: 1.45e+17 h: 1.25e+02 rho: 9.81e-01 mu: 1.06e-05 li:  1
4: f: 1.807384e+04 d: 7.72e+02 g: 3.88e+16 h: 6.23e+01 rho: 9.57e-01 mu: 3.53e-06 li:  1
5: f: 1.803397e+04 d: 3.99e+01 g: 1.35e+15 h: 1.16e+01 rho: 9.99e-01 mu: 1.18e-06 li:  1
6: f: 1.803390e+04 d: 6.16e-02 g: 6.69e+12 h: 7.31e-01 rho: 1.00e+00 mu: 3.93e-07 li:  1

Ceres Solver Report
-------------------
                                     Original                  Reduced
Parameter blocks                        22122                    22122
Parameters                              66462                    66462
Residual blocks                         83718                    83718
Residual                               167436                   167436

                                        Given                     Used
Linear solver                     DENSE_SCHUR              DENSE_SCHUR
Preconditioner                            N/A                      N/A
Ordering                                SCHUR                    SCHUR
num_eliminate_blocks                      N/A                    22106
Threads:                                    1                        1
Linear Solver Threads:                      1                        1

Cost:
Initial                          1.598216e+06
Final                            1.803390e+04
Change                           1.580182e+06

Number of iterations:
Successful                                  6
Unsuccessful                                0
Total                                       6

Time (in seconds):
Preprocessor                     0.000000e+00
Minimizer                        2.000000e+00
Total                            2.000000e+00
Termination:               FUNCTION_TOLERANCE
\end{minted}

\section{Building on OS X}
On OS X, we recommend using the \texttt{homebrew}~\footnote{\url{http://mxcl.github.com/homebrew/}} package manager.

\begin{enumerate}
\item{\cmake}
\begin{minted}{bash}
brew install cmake
\end{minted}
\item{\texttt{glog}\ and \texttt{gflags}}

Installing \texttt{\glog} takes also brings in \texttt{gflags} as a dependency.
\begin{minted}{bash}
brew install glog
\end{minted}
\item{\eigen}
\begin{minted}{bash}
brew install eigen
\end{minted}
\item{\suitesparse}
\begin{minted}{bash}
brew install suite-sparse
\end{minted}
\item{\texttt{protobuf}}
\begin{minted}{bash}
brew install protobuf
\end{minted}
\end{enumerate}

We are now ready to build and test Ceres.
\begin{minted}{bash}
tar zxf ceres-solver-1.0.tar.gz
mkdir ceres-bin
cd ceres-bin
cmake ../ceres-solver-1.0
make -j3
make test
\end{minted}
Like the Linux build, you should now be able to run \texttt{examples/simple\_bundle\_adjuster}.
\section{Customizing the Build Process}
\label{sec:custom}
It is possible to reduce the libraries needed to build Ceres and
customize the build process by passing appropriate flags to \texttt{cmake}. But unless you really know what you are
doing, we recommend against disabling any of the following flags.

\begin{enumerate}
\item{\texttt{protobuf}}


Protocol Buffers 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 turn it off by using
\begin{minted}{bash}
-DPROTOBUF=OFF.
\end{minted}

\item{\suitesparse}

By default, Ceres will only link to SuiteSparse if all its dependencies are present.
To build Ceres without \suitesparse\ use
\begin{minted}{bash}
-DSUITESPARSE=OFF.
\end{minted}
 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 \glog.

\item{\gflags}

To build Ceres without \gflags, use
\begin{minted}{bash}
-DGFLAGS=OFF.
\end{minted}
Disabling this flag will prevent some of the example code from building.

\item{Template Specializations}


If you are concerned about binary size/compilation time over some
small (10-20\%) performance gains in the \sparseschur\ solver, you can disable some of the template
specializations by using
\begin{minted}{bash}
-DSCHUR_SPECIALIZATIONS=OFF.
\end{minted}

\item{\texttt{OpenMP}}


On certain platforms like Android, multithreading with OpenMP is not supported. OpenMP support can be disabled by using
\begin{minted}{bash}
-DOPENMP=OFF.
\end{minted}
\end{enumerate}