| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257 | %!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 otherplatforms 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.gzcd gflags-2.0./configure --prefix=/usr/localmakesudo 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.gzcd glog-0.3.2./configure --with-gflags=/usr/local/makesudo 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.gzmkdir ceres-bincd ceres-bincmake ../ceres-solver-1.2.1make -j3make test\end{minted}You can also try running the command line bundling application with one of theincluded problems, which comes from the University of Washington's BAL dataset~\cite{Agarwal10bal}:\begin{minted}{bash}examples/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:  01: 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:  12: 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:  13: 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:  14: 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:  15: 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:  16: 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:  1Ceres Solver Report-------------------                                     Original                  ReducedParameter blocks                        22122                    22122Parameters                              66462                    66462Residual blocks                         83718                    83718Residual                               167436                   167436                                        Given                     UsedLinear solver                     DENSE_SCHUR              DENSE_SCHURPreconditioner                            N/A                      N/AOrdering                                SCHUR                    SCHURnum_eliminate_blocks                      N/A                    22106Threads:                                    1                        1Linear Solver Threads:                      1                        1Cost:Initial                          1.598216e+06Final                            1.803390e+04Change                           1.580182e+06Number of iterations:Successful                                  6Unsuccessful                                0Total                                       6Time (in seconds):Preprocessor                     0.000000e+00Minimizer                        2.000000e+00Total                            2.000000e+00Termination:               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.gzmkdir ceres-bincd ceres-bincmake ../ceres-solver-1.2.1make -j3make test\end{minted}Like the Linux build, you should now be able to run \texttt{examples/simple\_bundle\_adjuster}.\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 andcustomize the build process by passing appropriate flags to \texttt{cmake}. But unless you really know what you aredoing, 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 suitedto 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 somesmall (10-20\%) performance gains in the \sparseschur\ solver, you can disable some of the templatespecializations 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}
 |