docs/build.tex

%!TEX root = ceres-solver.tex
\chapter{Building Ceres}
\label{chapter:build}
Ceres source code and documentation are 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. 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. We require that you have a relative recent install of \texttt{cmake} (version 2.8.0 or better).
\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, \textbf{ we do not recommend building Ceres without \texttt{gflags}}.

\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{\texttt{CXSparse}~\footnote{\url{http://www.cise.ufl.edu/research/sparse/CXSparse/}}} is used for sparse matrix analysis, ordering and factorization. While it is similar to \texttt{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.

\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\ and \texttt{CXSparse}}
\begin{minted}{bash}
sudo apt-get install libsuitesparse-dev
\end{minted}
This should automatically bring in the necessary \blas\ and \lapack\ dependencies. By co-incidence on Ubuntu, this also installs \texttt{CXSparse}.

\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.2.1.tar.gz
mkdir ceres-bin
cd ceres-bin
cmake ../ceres-solver-1.2.1
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}
bin/simple_bundle_adjuster \
  ../ceres-solver-1.2.1/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
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\ and \texttt{CXSparse}}
\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.2.1.tar.gz
mkdir ceres-bin
cd ceres-bin
cmake ../ceres-solver-1.2.1
make -j3
make test
\end{minted}
Like the Linux build, you should now be able to run \texttt{bin/simple\_bundle\_adjuster}.


\section{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.

\begin{enumerate}
  \item Make a toplevel directory for deps \& build \& src somewhere: \texttt{ceres/}
  \item Get dependencies; unpack them as subdirectories in \texttt{ceres/}
        (\texttt{ceres/eigen}, \texttt{ceres/glog}, etc)
        \begin{itemize}
          \item Eigen 3.1 from eigen.tuxfamily.org (needed on Windows; 3.0.x will not
                work). There is no need to build anything; just unpack the source
                tarball.
          \item Goolge Log. Open up the Visual Studio solution and build it.
          \item Goolge Flags. Open up the Visual Studio solution and build it.
        \end{itemize}
  \item Unpack the Ceres tarball into \texttt{ceres}. For the tarball, you
        should get a directory inside \texttt{ceres} similar to
        \texttt{ceres-solver-1.3.0}. Alternately, checkout Ceres via git to get
        \texttt{ceres-solver.git} inside \texttt{ceres}.
  \item Install CMake.
  \item Make a dir \texttt{ceres/ceres-bin} (for an out-of-tree build)
  \item Run CMake; select the \texttt{ceres-solver-X.Y.Z} or
        \texttt{ceres-solver.git} directory for the CMake file. Then select the
        \texttt{ceres-bin} for the build dir.
  \item Try running "Configure". It won't work. It'll show a bunch of options.
        You'll need to set:
        \begin{itemize}
        \item \texttt{GLOG\_INCLUDE}
        \item \texttt{GLOG\_LIB}
        \item \texttt{GFLAGS\_LIB}
        \item \texttt{GFLAGS\_INCLUDE}
        \end{itemize}
        to the appropriate place where you unpacked/built them.
  \item You may have to tweak some more settings to generate a MSVC project.
        After each adjustment, try pressing Configure \& Generate until it
        generates successfully.
  \item Open the solution and build it in MSVC
\end{enumerate}

To run the tests, select the \texttt{RUN\_TESTS} target and hit "Build RUN\_TESTS" from the build menu.

Like the Linux build, you should now be able to run \texttt{bin/simple\_bundle\_adjuster}.

Notes:
\begin{itemize}
\item The default build is Debug; consider switching it to release mode.
\item Currently \texttt{system\_test} is not working properly.
\item Building Ceres as a DLL is not supported; patches welcome.
\item CMake puts the resulting test binaries in ceres-bin/examples/Debug by
      default.
\item The solvers supported on Windows are \texttt{DENSE\_QR},
      \texttt{DENSE\_SCHUR}, \texttt{CGNR}, and \texttt{ITERATIVE\_SCHUR}.
\item 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.
\end{itemize}

\section{Building on Android}
\label{sec:android}
Download the Android NDK. Run \texttt{ndk-build} from inside the \texttt{jni} directory. Use the \texttt{libceres.a} that gets created.

TODO(keir): Expand this section further.

\section{Compiler Flags to use when building your own applications}
\label{sec:compiler-flags}
TBD


\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 \texttt{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{\texttt{CXSparse}}

By default, Ceres will only link to \texttt{CXSparse} if all its dependencies are present.
To build Ceres without \suitesparse\ use
\begin{minted}{bash}
-DCXSPARSE=OFF.
\end{minted}

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}