1%!TEX root = ceres-solver.tex 2\chapter{Building Ceres} 3\label{chapter:build} 4Ceres source code and documentation are hosted at 5\url{http://code.google.com/p/ceres-solver/}. 6 7\section{Dependencies} 8Ceres 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}. 9 10\begin{enumerate} 11\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). 12\item{\eigen~\footnote{\url{http://eigen.tuxfamily.org}}} is used for doing all the low level matrix and 13 linear algebra operations. 14 15\item{\glog~\footnote{\url{http://code.google.com/p/google-glog}}} is used for error checking and logging. 16 17 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. 18 19\item{\gflags~\footnote{\url{http://code.google.com/p/gflags}}} is used by the code in 20 \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}}. 21 22\item{\suitesparse~\footnote{\url{http://www.cise.ufl.edu/research/sparse/SuiteSparse/}}} is used for sparse matrix analysis, 23 ordering and factorization. In particular Ceres uses the 24 \amd, \colamd\ and \cholmod\ libraries. This is an optional 25 dependency. 26 27\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. 28 29\item{\blas\ and \lapack} are needed by 30 \suitesparse. We 31 recommend either 32 \texttt{GotoBlas2}~\footnote{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2}} 33 or 34 \texttt{ATLAS}~\footnote{\url{http://math-atlas.sourceforge.net/}}, 35 both of which ship with \blas\ and \lapack\ routines. 36 37\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. 38\end{enumerate} 39 40Currently we support building on Linux and MacOS X. Support for other 41platforms is forthcoming. 42 43\section{Building on Linux} 44We will use Ubuntu as our example platform. 45 46\begin{enumerate} 47\item{\cmake} 48\begin{minted}{bash} 49sudo apt-get install cmake 50\end{minted} 51 52\item{\gflags} can either be installed from source via the \texttt{autoconf} invocation 53\begin{minted}{bash} 54tar -xvzf gflags-2.0.tar.gz 55cd gflags-2.0 56./configure --prefix=/usr/local 57make 58sudo make install. 59\end{minted} 60or via the \texttt{deb} or \texttt{rpm} packages available on the \gflags\ website. 61 62\item{\glog} must be configured to use the previously installed 63\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. 64\begin{minted}{bash} 65tar -xvzf glog-0.3.2.tar.gz 66cd glog-0.3.2 67./configure --with-gflags=/usr/local/ 68make 69sudo make install 70\end{minted} 71 72\item{\eigen} 73\begin{minted}{bash} 74sudo apt-get install libeigen3-dev 75\end{minted} 76 77\item{\suitesparse\ and \texttt{CXSparse}} 78\begin{minted}{bash} 79sudo apt-get install libsuitesparse-dev 80\end{minted} 81This should automatically bring in the necessary \blas\ and \lapack\ dependencies. By co-incidence on Ubuntu, this also installs \texttt{CXSparse}. 82 83\item{\texttt{protobuf}} 84\begin{minted}{bash} 85sudo apt-get install libprotobuf-dev 86\end{minted} 87\end{enumerate} 88 89 90We 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} 91 92\begin{minted}{bash} 93tar zxf ceres-solver-1.2.1.tar.gz 94mkdir ceres-bin 95cd ceres-bin 96cmake ../ceres-solver-1.2.1 97make -j3 98make test 99\end{minted} 100 101You can also try running the command line bundling application with one of the 102included problems, which comes from the University of Washington's BAL dataset~\cite{Agarwal10bal}: 103\begin{minted}{bash} 104bin/simple_bundle_adjuster \ 105 ../ceres-solver-1.2.1/data/problem-16-22106-pre.txt \ 106\end{minted} 107This runs Ceres for a maximum of 10 iterations using the \denseschur\ linear solver. The output should look something like this. 108\clearpage 109\begin{minted}{bash} 1100: 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 1111: 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 1122: 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 1133: 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 1144: 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 1155: 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 1166: 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 117 118Ceres Solver Report 119------------------- 120 Original Reduced 121Parameter blocks 22122 22122 122Parameters 66462 66462 123Residual blocks 83718 83718 124Residual 167436 167436 125 126 Given Used 127Linear solver DENSE_SCHUR DENSE_SCHUR 128Preconditioner N/A N/A 129Threads: 1 1 130Linear Solver Threads: 1 1 131 132Cost: 133Initial 1.598216e+06 134Final 1.803390e+04 135Change 1.580182e+06 136 137Number of iterations: 138Successful 6 139Unsuccessful 0 140Total 6 141 142Time (in seconds): 143Preprocessor 0.000000e+00 144Minimizer 2.000000e+00 145Total 2.000000e+00 146Termination: FUNCTION_TOLERANCE 147\end{minted} 148 149\section{Building on OS X} 150On OS X, we recommend using the \texttt{homebrew}~\footnote{\url{http://mxcl.github.com/homebrew/}} package manager. 151 152\begin{enumerate} 153\item{\cmake} 154\begin{minted}{bash} 155brew install cmake 156\end{minted} 157\item{\texttt{glog}\ and \texttt{gflags}} 158 159Installing \texttt{\glog} takes also brings in \texttt{gflags} as a dependency. 160\begin{minted}{bash} 161brew install glog 162\end{minted} 163\item{\eigen} 164\begin{minted}{bash} 165brew install eigen 166\end{minted} 167\item{\suitesparse\ and \texttt{CXSparse}} 168\begin{minted}{bash} 169brew install suite-sparse 170\end{minted} 171\item{\texttt{protobuf}} 172\begin{minted}{bash} 173brew install protobuf 174\end{minted} 175\end{enumerate} 176 177We are now ready to build and test Ceres. 178\begin{minted}{bash} 179tar zxf ceres-solver-1.2.1.tar.gz 180mkdir ceres-bin 181cd ceres-bin 182cmake ../ceres-solver-1.2.1 183make -j3 184make test 185\end{minted} 186Like the Linux build, you should now be able to run \texttt{bin/simple\_bundle\_adjuster}. 187 188 189\section{Building on Windows with Visual Studio} 190On Windows, we support building with Visual Studio 2010 or newer. Note that the 191Windows port is less featureful and less tested than the Linux or Mac OS X 192versions due to the unavaliability of SuiteSparse and CXSparse. Building is 193also more involved since there is no automated way to install the dependencies. 194 195\begin{enumerate} 196 \item Make a toplevel directory for deps \& build \& src somewhere: \texttt{ceres/} 197 \item Get dependencies; unpack them as subdirectories in \texttt{ceres/} 198 (\texttt{ceres/eigen}, \texttt{ceres/glog}, etc) 199 \begin{itemize} 200 \item Eigen 3.1 from eigen.tuxfamily.org (needed on Windows; 3.0.x will not 201 work). There is no need to build anything; just unpack the source 202 tarball. 203 \item Goolge Log. Open up the Visual Studio solution and build it. 204 \item Goolge Flags. Open up the Visual Studio solution and build it. 205 \end{itemize} 206 \item Unpack the Ceres tarball into \texttt{ceres}. For the tarball, you 207 should get a directory inside \texttt{ceres} similar to 208 \texttt{ceres-solver-1.3.0}. Alternately, checkout Ceres via git to get 209 \texttt{ceres-solver.git} inside \texttt{ceres}. 210 \item Install CMake. 211 \item Make a dir \texttt{ceres/ceres-bin} (for an out-of-tree build) 212 \item Run CMake; select the \texttt{ceres-solver-X.Y.Z} or 213 \texttt{ceres-solver.git} directory for the CMake file. Then select the 214 \texttt{ceres-bin} for the build dir. 215 \item Try running "Configure". It won't work. It'll show a bunch of options. 216 You'll need to set: 217 \begin{itemize} 218 \item \texttt{GLOG\_INCLUDE} 219 \item \texttt{GLOG\_LIB} 220 \item \texttt{GFLAGS\_LIB} 221 \item \texttt{GFLAGS\_INCLUDE} 222 \end{itemize} 223 to the appropriate place where you unpacked/built them. 224 \item You may have to tweak some more settings to generate a MSVC project. 225 After each adjustment, try pressing Configure \& Generate until it 226 generates successfully. 227 \item Open the solution and build it in MSVC 228\end{enumerate} 229 230To run the tests, select the \texttt{RUN\_TESTS} target and hit "Build RUN\_TESTS" from the build menu. 231 232Like the Linux build, you should now be able to run \texttt{bin/simple\_bundle\_adjuster}. 233 234Notes: 235\begin{itemize} 236\item The default build is Debug; consider switching it to release mode. 237\item Currently \texttt{system\_test} is not working properly. 238\item Building Ceres as a DLL is not supported; patches welcome. 239\item CMake puts the resulting test binaries in ceres-bin/examples/Debug by 240 default. 241\item The solvers supported on Windows are \texttt{DENSE\_QR}, 242 \texttt{DENSE\_SCHUR}, \texttt{CGNR}, and \texttt{ITERATIVE\_SCHUR}. 243\item We're looking for someone to work with upstream SuiteSparse to port their 244 build system to something sane like CMake, and get a supported Windows 245 port. 246\end{itemize} 247 248\section{Building on Android} 249\label{sec:android} 250Download the Android NDK. Run \texttt{ndk-build} from inside the \texttt{jni} directory. Use the \texttt{libceres.a} that gets created. 251 252TODO(keir): Expand this section further. 253 254\section{Compiler Flags to use when building your own applications} 255\label{sec:compiler-flags} 256TBD 257 258 259\section{Customizing the Build Process} 260\label{sec:custom} 261It is possible to reduce the libraries needed to build Ceres and 262customize the build process by passing appropriate flags to \texttt{cmake}. But unless you really know what you are 263doing, we recommend against disabling any of the following flags. 264 265\begin{enumerate} 266\item{\texttt{protobuf}} 267 268 269Protocol 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 270\begin{minted}{bash} 271-DPROTOBUF=OFF. 272\end{minted} 273 274\item{\suitesparse} 275 276By default, Ceres will only link to \texttt{SuiteSparse}\ if all its dependencies are present. 277To build Ceres without \suitesparse\ use 278\begin{minted}{bash} 279-DSUITESPARSE=OFF. 280\end{minted} 281 This will also disable dependency checking for \lapack\ and \blas. This saves on binary size, but the resulting version of Ceres is not suited 282to large scale problems due to the lack of a sparse Cholesky solver. This will reduce Ceres' dependencies down to 283\eigen, \gflags\ and \glog. 284 285\item{\texttt{CXSparse}} 286 287By default, Ceres will only link to \texttt{CXSparse} if all its dependencies are present. 288To build Ceres without \suitesparse\ use 289\begin{minted}{bash} 290-DCXSPARSE=OFF. 291\end{minted} 292 293This 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 294\eigen, \gflags\ and \glog. 295 296\item{\gflags} 297To build Ceres without \gflags, use 298\begin{minted}{bash} 299-DGFLAGS=OFF. 300\end{minted} 301Disabling this flag will prevent some of the example code from building. 302 303\item{Template Specializations} 304 305 306If you are concerned about binary size/compilation time over some 307small (10-20\%) performance gains in the \sparseschur\ solver, you can disable some of the template 308specializations by using 309\begin{minted}{bash} 310-DSCHUR_SPECIALIZATIONS=OFF. 311\end{minted} 312 313\item{\texttt{OpenMP}} 314 315 316On certain platforms like Android, multithreading with OpenMP is not supported. OpenMP support can be disabled by using 317\begin{minted}{bash} 318-DOPENMP=OFF. 319\end{minted} 320\end{enumerate} 321 322