.. _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.2 or later **strongly** recommended, 3.1.0 or later **required**. .. NOTE :: Ceres can also use Eigen as a sparse linear algebra library. Please see the documentation for ``EIGENSPARSE`` 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``. .. NOTE :: If you are compiling ``glog`` from source, please note that currently, the unit tests for ``glog`` (which are enabled by default) do not compile against a default build of ``gflags`` 2.1 as the gflags namespace changed from ``google::`` to ``gflags::``. A patch to fix this is available from `here `_. - `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 14.04, 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 or use an external PPA (see `bug report here `_). 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 # google-glog + gflags sudo apt-get install libgoogle-glog-dev # 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 # add the following PPA: sudo add-apt-repository ppa:bzindovic/suitesparse-bugfix-1319687 sudo apt-get update sudo apt-get install libsuitesparse-dev We are now ready to build, test, and install Ceres. .. code-block:: bash tar zxf ceres-solver-1.11.0.tar.gz mkdir ceres-bin cd ceres-bin cmake ../ceres-solver-1.11.0 make -j3 make test # Optionally install Ceres, it can also be exported using CMake which # allows Ceres to be used without requiring installation, see the documentation # for the EXPORT_BUILD_DIR option for more information. 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.11.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.11.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, you can either use `MacPorts `_ or `Homebrew `_ to install Ceres Solver. If using `MacPorts `_, then .. code-block:: bash sudo port install ceres-solver will install the latest version. If using `Homebrew `_ and assuming that you have the ``homebrew/science`` [#f1]_ tap enabled, then .. 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.11.0.tar.gz mkdir ceres-bin cd ceres-bin cmake ../ceres-solver-1.11.0 make -j3 make test # Optionally install Ceres, it can also be exported using CMake which # allows Ceres to be used without requiring installation, see the # documentation for the EXPORT_BUILD_DIR option for more information. make install Like the Linux build, you should now be able to run ``bin/simple_bundle_adjuster``. .. rubric:: Footnotes .. [#f1] Ceres and many of its dependencies are in `homebrew/science `_ tap. So, if you don't have this tap enabled, then you will need to enable it as follows before executing any of the commands in this section. .. code-block:: bash brew tap homebrew/science .. _section-windows: Windows ======= .. NOTE:: If you find the following CMake difficult to set up, then you may be interested in a `Microsoft Visual Studio wrapper `_ for Ceres Solver by Tal Ben-Nun. 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 7.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 \ -DCMAKE_TOOLCHAIN_FILE=../ceres-solver/cmake/iOS.cmake \ -DEIGEN_INCLUDE_DIR=/path/to/eigen/header \ -DIOS_PLATFORM= \ ``PLATFORM`` can be: ``OS``, ``SIMULATOR`` or ``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