.. _chapter-building: ======================= Building & Installation ======================= Getting the source code ======================= .. _section-source: You can start with the `latest stable release `_ . Or if you want the latest version, you can clone the git repository .. code-block:: bash git clone https://ceres-solver.googlesource.com/ceres-solver .. _section-dependencies: Dependencies ============ Ceres relies on a number of open source libraries, some of which are optional. For details on customizing the build process, see :ref:`section-customizing` . - `Eigen `_ 3.2.1 or later. **Required** .. NOTE :: Ceres can also use Eigen as a sparse linear algebra library. Please see the documentation for ``-DEIGENSPARSE`` for more details. - `CMake `_ 2.8.0 or later. **Required on all platforms except for Android.** - `Google Log `_ 0.3.1 or later. **Recommended** .. NOTE:: Ceres has a minimal replacement of ``glog`` called ``miniglog`` that can be enabled with the ``MINIGLOG`` build option. ``miniglog`` is needed on Android as ``glog`` currently does not build using the NDK. It can however be used on other platforms too. **We do not advise using** ``miniglog`` **on platforms other than Android due to the various performance and functionality compromises in** ``miniglog``. - `Google Flags `_. Needed to build examples and tests. - `SuiteSparse `_. Needed for solving large sparse linear systems. **Optional; strongly recomended for large scale bundle adjustment** - `CXSparse `_. Similar to ``SuiteSparse`` but simpler and slower. CXSparse has no dependencies on ``LAPACK`` and ``BLAS``. This makes for a simpler build process and a smaller binary. **Optional** - `BLAS `_ and `LAPACK `_ routines are needed by ``SuiteSparse``, and optionally used by Ceres directly for some operations. On ``UNIX`` OSes other than Mac OS X we recommend `ATLAS `_, which includes ``BLAS`` and ``LAPACK`` routines. It is also possible to use `OpenBLAS `_ . However, one needs to be careful to `turn off the threading `_ inside ``OpenBLAS`` as it conflicts with use of threads in Ceres. MAC OS X ships with an optimized ``LAPACK`` and ``BLAS`` implementation as part of the ``Accelerate`` framework. The Ceres build system will automatically detect and use it. For Windows things are much more complicated. `LAPACK For Windows `_ has detailed instructions.. **Optional but required for** ``SuiteSparse``. .. _section-linux: Linux ===== We will use `Ubuntu `_ as our example linux distribution. .. NOTE:: Up to at least Ubuntu 13.10, the SuiteSparse package in the official package repository (built from SuiteSparse v3.4.0) **cannot** be used to build Ceres as a *shared* library. Thus if you want to build Ceres as a shared library using SuiteSparse, you must perform a source install of SuiteSparse. It is recommended that you use the current version of SuiteSparse (4.2.1 at the time of writing). Start by installing all the dependencies. .. code-block:: bash # CMake sudo apt-get install cmake # gflags tar -xvzf gflags-2.0.tar.gz cd gflags-2.0 ./configure --prefix=/usr/local make sudo make install. # google-glog must be configured to use the previously installed gflags tar -xvzf glog-0.3.2.tar.gz cd glog-0.3.2 ./configure --with-gflags=/usr/local/ make sudo make install # BLAS & LAPACK sudo apt-get install libatlas-base-dev # Eigen3 sudo apt-get install libeigen3-dev # SuiteSparse and CXSparse (optional) # - If you want to build Ceres as a *static* library (the default) # you can use the SuiteSparse package in the main Ubuntu package # repository: sudo apt-get install libsuitesparse-dev # - However, if you want to build Ceres as a *shared* library, you must # perform a source install of SuiteSparse (and uninstall the Ubuntu # package if it is currently installed. We are now ready to build, test, and install Ceres. .. code-block:: bash tar zxf ceres-solver-1.9.0.tar.gz mkdir ceres-bin cd ceres-bin cmake ../ceres-solver-1.9.0 make -j3 make test make install 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 [Agarwal]_. .. code-block:: bash bin/simple_bundle_adjuster ../ceres-solver-1.9.0/data/problem-16-22106-pre.txt This runs Ceres for a maximum of 10 iterations using the ``DENSE_SCHUR`` linear solver. The output should look something like this. .. code-block:: bash iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time 0 4.185660e+06 0.00e+00 1.09e+08 0.00e+00 0.00e+00 1.00e+04 0 7.59e-02 3.37e-01 1 1.062590e+05 4.08e+06 8.99e+06 5.36e+02 9.82e-01 3.00e+04 1 1.65e-01 5.03e-01 2 4.992817e+04 5.63e+04 8.32e+06 3.19e+02 6.52e-01 3.09e+04 1 1.45e-01 6.48e-01 3 1.899774e+04 3.09e+04 1.60e+06 1.24e+02 9.77e-01 9.26e+04 1 1.43e-01 7.92e-01 4 1.808729e+04 9.10e+02 3.97e+05 6.39e+01 9.51e-01 2.78e+05 1 1.45e-01 9.36e-01 5 1.803399e+04 5.33e+01 1.48e+04 1.23e+01 9.99e-01 8.33e+05 1 1.45e-01 1.08e+00 6 1.803390e+04 9.02e-02 6.35e+01 8.00e-01 1.00e+00 2.50e+06 1 1.50e-01 1.23e+00 Ceres Solver v1.10.0 Solve Report ---------------------------------- Original Reduced Parameter blocks 22122 22122 Parameters 66462 66462 Residual blocks 83718 83718 Residual 167436 167436 Minimizer TRUST_REGION Dense linear algebra library EIGEN Trust region strategy LEVENBERG_MARQUARDT Given Used Linear solver DENSE_SCHUR DENSE_SCHUR Threads 1 1 Linear solver threads 1 1 Linear solver ordering AUTOMATIC 22106, 16 Cost: Initial 4.185660e+06 Final 1.803390e+04 Change 4.167626e+06 Minimizer iterations 6 Successful steps 6 Unsuccessful steps 0 Time (in seconds): Preprocessor 0.261 Residual evaluation 0.082 Jacobian evaluation 0.412 Linear solver 0.442 Minimizer 1.051 Postprocessor 0.002 Total 1.357 Termination: CONVERGENCE (Function tolerance reached. |cost_change|/cost: 1.769766e-09 <= 1.000000e-06) .. section-osx: Mac OS X ======== .. NOTE:: Ceres will not compile using Xcode 4.5.x (Clang version 4.1) due to a bug in that version of Clang. If you are running Xcode 4.5.x, please update to Xcode >= 4.6.x before attempting to build Ceres. On OS X, we recommend using the `homebrew `_ package manager to install Ceres. .. code-block:: bash brew install ceres-solver will install the latest stable version along with all the required dependencies and .. code-block:: bash brew install ceres-solver --HEAD will install the latest version in the git repo. You can also install each of the dependencies by hand using `homebrew `_. There is no need to install ``BLAS`` or ``LAPACK`` separately as OS X ships with optimized ``BLAS`` and ``LAPACK`` routines as part of the `vecLib `_ framework. .. code-block:: bash # CMake brew install cmake # google-glog and gflags brew install glog # Eigen3 brew install eigen # SuiteSparse and CXSparse brew install suite-sparse We are now ready to build, test, and install Ceres. .. code-block:: bash tar zxf ceres-solver-1.9.0.tar.gz mkdir ceres-bin cd ceres-bin cmake ../ceres-solver-1.9.0 make -j3 make test make install Like the Linux build, you should now be able to run ``bin/simple_bundle_adjuster``. .. _section-windows: Windows ======= 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 lack of an officially supported way of building SuiteSparse and CXSparse. There are however a number of unofficial ways of building these libraries. Building on Windows also a bit more involved since there is no automated way to install dependencies. .. NOTE:: Using ``google-glog`` & ``miniglog`` with windows.h. The windows.h header if used with GDI (Graphics Device Interface) defines ``ERROR``, which conflicts with the definition of ``ERROR`` as a LogSeverity level in ``google-glog`` and ``miniglog``. There are at least two possible fixes to this problem: #. Use ``google-glog`` and define ``GLOG_NO_ABBREVIATED_SEVERITIES`` when building Ceres and your own project, as documented `here `__. Note that this fix will not work for ``miniglog``, but use of ``miniglog`` is strongly discouraged on any platform for which ``google-glog`` is available (which includes Windows). #. If you do not require GDI, then define ``NOGDI`` **before** including windows.h. This solution should work for both ``google-glog`` and ``miniglog`` and is documented for ``google-glog`` `here `__. #. Make a toplevel directory for deps & build & src somewhere: ``ceres/`` #. Get dependencies; unpack them as subdirectories in ``ceres/`` (``ceres/eigen``, ``ceres/glog``, etc) #. ``Eigen`` 3.1 (needed on Windows; 3.0.x will not work). There is no need to build anything; just unpack the source tarball. #. ``google-glog`` Open up the Visual Studio solution and build it. #. ``gflags`` Open up the Visual Studio solution and build it. #. (Experimental) ``SuiteSparse`` Previously SuiteSparse was not available on Windows, recently it has become possible to build it on Windows using the `suitesparse-metis-for-windows `_ project. If you wish to use ``SuiteSparse``, follow their instructions for obtaining and building it. #. (Experimental) ``CXSparse`` Previously CXSparse was not available on Windows, there are now several ports that enable it to be, including: `[1] `_ and `[2] `_. If you wish to use ``CXSparse``, follow their instructions for obtaining and building it. #. Unpack the Ceres tarball into ``ceres``. For the tarball, you should get a directory inside ``ceres`` similar to ``ceres-solver-1.3.0``. Alternately, checkout Ceres via ``git`` to get ``ceres-solver.git`` inside ``ceres``. #. Install ``CMake``, #. Make a dir ``ceres/ceres-bin`` (for an out-of-tree build) #. Run ``CMake``; select the ``ceres-solver-X.Y.Z`` or ``ceres-solver.git`` directory for the CMake file. Then select the ``ceres-bin`` for the build dir. #. Try running ``Configure``. It won't work. It'll show a bunch of options. You'll need to set: #. ``EIGEN_INCLUDE_DIR_HINTS`` #. ``GLOG_INCLUDE_DIR_HINTS`` #. ``GLOG_LIBRARY_DIR_HINTS`` #. ``GFLAGS_INCLUDE_DIR_HINTS`` #. ``GFLAGS_LIBRARY_DIR_HINTS`` #. (Optional) ``SUITESPARSE_INCLUDE_DIR_HINTS`` #. (Optional) ``SUITESPARSE_LIBRARY_DIR_HINTS`` #. (Optional) ``CXSPARSE_INCLUDE_DIR_HINTS`` #. (Optional) ``CXSPARSE_LIBRARY_DIR_HINTS`` to the appropriate directories where you unpacked/built them. If any of the variables are not visible in the ``CMake`` GUI, create a new entry for them. We recommend using the ``_(INCLUDE/LIBRARY)_DIR_HINTS`` variables rather than setting the ``_INCLUDE_DIR`` & ``_LIBRARY`` variables directly to keep all of the validity checking, and to avoid having to specify the library files manually. #. You may have to tweak some more settings to generate a MSVC project. After each adjustment, try pressing Configure & Generate until it generates successfully. #. Open the solution and build it in MSVC To run the tests, select the ``RUN_TESTS`` target and hit **Build RUN_TESTS** from the build menu. Like the Linux build, you should now be able to run ``bin/simple_bundle_adjuster``. Notes: #. The default build is Debug; consider switching it to release mode. #. Currently ``system_test`` is not working properly. #. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug`` by default. #. The solvers supported on Windows are ``DENSE_QR``, ``DENSE_SCHUR``, ``CGNR``, and ``ITERATIVE_SCHUR``. #. We're looking for someone to work with upstream ``SuiteSparse`` to port their build system to something sane like ``CMake``, and get a fully supported Windows port. .. _section-android: Android ======= Download the ``Android NDK`` version ``r9d`` or later. Run ``ndk-build`` from inside the ``jni`` directory. Use the ``libceres.a`` that gets created. .. _section-ios: iOS === .. NOTE:: You need iOS version 6.0 or higher to build Ceres Solver. To build Ceres for iOS, we need to force ``CMake`` to find the toolchains from the iOS SDK instead of using the standard ones. For example: .. code-block:: bash cmake ../ceres-solver \ -DCMAKE_TOOLCHAIN_FILE=../ceres-solver/cmake/iOS.cmake \ -DEIGEN_INCLUDE_DIR=/path/to/eigen/header \ -DIOS_PLATFORM= ``PLATFORM`` can be one of ``OS``, ``SIMULATOR`` and ``SIMULATOR64``. You can build for ``OS`` (``armv7``, ``armv7s``, ``arm64``), ``SIMULATOR`` (``i386``) or ``SIMULATOR64`` (``x86_64``) separately and use ``LIPO`` to merge them into one static library. See ``cmake/iOS.cmake`` for more options. After building, you will get a ``libceres.a`` library, which you will need to add to your Xcode project. The default CMake configuration builds a bare bones version of Ceres Solver that only depends on Eigen (``MINIGLOG`` is compiled into Ceres if it is used), this should be sufficient for solving small to moderate sized problems (No ``SPARSE_SCHUR``, ``SPARSE_NORMAL_CHOLESKY`` linear solvers and no ``CLUSTER_JACOBI`` and ``CLUSTER_TRIDIAGONAL`` preconditioners). If you decide to use ``LAPACK`` and ``BLAS``, then you also need to add ``Accelerate.framework`` to your XCode project's linking dependency. .. _section-customizing: Customizing the build ===================== It is possible to reduce the libraries needed to build Ceres and customize the build process by setting the appropriate options in ``CMake``. These options can either be set in the ``CMake`` GUI, or via ``-D