1 %!TEX root = ceres-solver.tex 2 \chapter{Building Ceres} 3 \label{chapter:build} 4 Ceres source code and documentation are hosted at 5 \url{http://code.google.com/p/ceres-solver/}. 6 7 \section{Dependencies} 8 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}. 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 40 Currently we support building on Linux and MacOS X. Support for other 41 platforms is forthcoming. 42 43 \section{Building on Linux} 44 We will use Ubuntu as our example platform. 45 46 \begin{enumerate} 47 \item{\cmake} 48 \begin{minted}{bash} 49 sudo 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} 54 tar -xvzf gflags-2.0.tar.gz 55 cd gflags-2.0 56 ./configure --prefix=/usr/local 57 make 58 sudo make install. 59 \end{minted} 60 or 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} 65 tar -xvzf glog-0.3.2.tar.gz 66 cd glog-0.3.2 67 ./configure --with-gflags=/usr/local/ 68 make 69 sudo make install 70 \end{minted} 71 72 \item{\eigen} 73 \begin{minted}{bash} 74 sudo apt-get install libeigen3-dev 75 \end{minted} 76 77 \item{\suitesparse\ and \texttt{CXSparse}} 78 \begin{minted}{bash} 79 sudo apt-get install libsuitesparse-dev 80 \end{minted} 81 This 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} 85 sudo apt-get install libprotobuf-dev 86 \end{minted} 87 \end{enumerate} 88 89 90 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} 91 92 \begin{minted}{bash} 93 tar zxf ceres-solver-1.2.1.tar.gz 94 mkdir ceres-bin 95 cd ceres-bin 96 cmake ../ceres-solver-1.2.1 97 make -j3 98 make test 99 \end{minted} 100 101 You can also try running the command line bundling application with one of the 102 included problems, which comes from the University of Washington's BAL dataset~\cite{Agarwal10bal}: 103 \begin{minted}{bash} 104 bin/simple_bundle_adjuster \ 105 ../ceres-solver-1.2.1/data/problem-16-22106-pre.txt \ 106 \end{minted} 107 This 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} 110 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 111 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 112 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 113 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 114 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 115 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 116 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 117 118 Ceres Solver Report 119 ------------------- 120 Original Reduced 121 Parameter blocks 22122 22122 122 Parameters 66462 66462 123 Residual blocks 83718 83718 124 Residual 167436 167436 125 126 Given Used 127 Linear solver DENSE_SCHUR DENSE_SCHUR 128 Preconditioner N/A N/A 129 Threads: 1 1 130 Linear Solver Threads: 1 1 131 132 Cost: 133 Initial 1.598216e+06 134 Final 1.803390e+04 135 Change 1.580182e+06 136 137 Number of iterations: 138 Successful 6 139 Unsuccessful 0 140 Total 6 141 142 Time (in seconds): 143 Preprocessor 0.000000e+00 144 Minimizer 2.000000e+00 145 Total 2.000000e+00 146 Termination: FUNCTION_TOLERANCE 147 \end{minted} 148 149 \section{Building on OS X} 150 On 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} 155 brew install cmake 156 \end{minted} 157 \item{\texttt{glog}\ and \texttt{gflags}} 158 159 Installing \texttt{\glog} takes also brings in \texttt{gflags} as a dependency. 160 \begin{minted}{bash} 161 brew install glog 162 \end{minted} 163 \item{\eigen} 164 \begin{minted}{bash} 165 brew install eigen 166 \end{minted} 167 \item{\suitesparse\ and \texttt{CXSparse}} 168 \begin{minted}{bash} 169 brew install suite-sparse 170 \end{minted} 171 \item{\texttt{protobuf}} 172 \begin{minted}{bash} 173 brew install protobuf 174 \end{minted} 175 \end{enumerate} 176 177 We are now ready to build and test Ceres. 178 \begin{minted}{bash} 179 tar zxf ceres-solver-1.2.1.tar.gz 180 mkdir ceres-bin 181 cd ceres-bin 182 cmake ../ceres-solver-1.2.1 183 make -j3 184 make test 185 \end{minted} 186 Like 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} 190 On Windows, we support building with Visual Studio 2010 or newer. Note that the 191 Windows port is less featureful and less tested than the Linux or Mac OS X 192 versions due to the unavaliability of SuiteSparse and CXSparse. Building is 193 also 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 230 To run the tests, select the \texttt{RUN\_TESTS} target and hit "Build RUN\_TESTS" from the build menu. 231 232 Like the Linux build, you should now be able to run \texttt{bin/simple\_bundle\_adjuster}. 233 234 Notes: 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} 250 Download the Android NDK. Run \texttt{ndk-build} from inside the \texttt{jni} directory. Use the \texttt{libceres.a} that gets created. 251 252 TODO(keir): Expand this section further. 253 254 \section{Compiler Flags to use when building your own applications} 255 \label{sec:compiler-flags} 256 TBD 257 258 259 \section{Customizing the Build Process} 260 \label{sec:custom} 261 It is possible to reduce the libraries needed to build Ceres and 262 customize the build process by passing appropriate flags to \texttt{cmake}. But unless you really know what you are 263 doing, we recommend against disabling any of the following flags. 264 265 \begin{enumerate} 266 \item{\texttt{protobuf}} 267 268 269 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 270 \begin{minted}{bash} 271 -DPROTOBUF=OFF. 272 \end{minted} 273 274 \item{\suitesparse} 275 276 By default, Ceres will only link to \texttt{SuiteSparse}\ if all its dependencies are present. 277 To 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 282 to 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 287 By default, Ceres will only link to \texttt{CXSparse} if all its dependencies are present. 288 To build Ceres without \suitesparse\ use 289 \begin{minted}{bash} 290 -DCXSPARSE=OFF. 291 \end{minted} 292 293 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 294 \eigen, \gflags\ and \glog. 295 296 \item{\gflags} 297 To build Ceres without \gflags, use 298 \begin{minted}{bash} 299 -DGFLAGS=OFF. 300 \end{minted} 301 Disabling this flag will prevent some of the example code from building. 302 303 \item{Template Specializations} 304 305 306 If you are concerned about binary size/compilation time over some 307 small (10-20\%) performance gains in the \sparseschur\ solver, you can disable some of the template 308 specializations by using 309 \begin{minted}{bash} 310 -DSCHUR_SPECIALIZATIONS=OFF. 311 \end{minted} 312 313 \item{\texttt{OpenMP}} 314 315 316 On 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
