# Installation¶

## Getting the source code¶

git clone https://ceres-solver.googlesource.com/ceres-solver


## Dependencies¶

Ceres relies on a number of open source libraries, some of which are optional. For details on customizing the build process, see Customizing the build .

• 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.

• glog 0.3.1 or later. Recommended

glog is used extensively throughout Ceres for logging detailed information about memory allocations and time consumed in various parts of the solve, internal error conditions etc. The Ceres developers use it extensively to observe and analyze Ceres’s performance. glog allows you to control its behaviour from the command line. Starting with -logtostderr you can add -v=N for increasing values of N to get more and more verbose and detailed information about Ceres internals.

Unfortunately, the current version of google-glog does not build using the Android NDK. So, Ceres also ships with a minimal replacement of glog called miniglog that can be enabled with the MINIGLOG build option.

So, in an attempt to reduce dependencies, it is tempting to use miniglog on platforms other than Android. While there is nothing preventing the user from doing so, we strongly recommend against it. miniglog has worse performance than glog and is much harder to control and use.

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.

• gflags. 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.

• TBB is a C++11 template library for parallel programming that optionally can be used as an alternative to OpenMP. Optional

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.

## 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.

# CMake
sudo apt-get install cmake
# 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
sudo apt-get update
sudo apt-get install libsuitesparse-dev


We are now ready to build, test, and install Ceres.

tar zxf ceres-solver-1.14.0.tar.gz
mkdir ceres-bin
cd ceres-bin
cmake ../ceres-solver-1.14.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
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].

bin/simple_bundle_adjuster ../ceres-solver-1.14.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.

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.14.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
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)


## 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

sudo port install ceres-solver


If using Homebrew and assuming that you have the homebrew/science [1] tap enabled, then

brew install ceres-solver


will install the latest stable version along with all the required dependencies and

brew install ceres-solver --HEAD


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.

# CMake
brew install cmake
brew install glog
# Eigen3
brew install eigen
# SuiteSparse and CXSparse
brew install suite-sparse


We are now ready to build, test, and install Ceres.

tar zxf ceres-solver-1.14.0.tar.gz
mkdir ceres-bin
cd ceres-bin
cmake ../ceres-solver-1.14.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
make install


### Building with OpenMP on OS X¶

Up to at least Xcode 8, OpenMP support was disabled in Apple’s version of Clang. However, you can install the latest version of the LLVM toolchain from Homebrew which does support OpenMP, and thus build Ceres with OpenMP support on OS X. To do this, you must install llvm via Homebrew:

# Install latest version of LLVM toolchain.
brew install llvm


As the LLVM formula in Homebrew is keg-only, it will not be installed to /usr/local to avoid conflicts with the standard Apple LLVM toolchain. To build Ceres with the Homebrew LLVM toolchain you should do the following:

tar zxf ceres-solver-1.14.0.tar.gz
mkdir ceres-bin
cd ceres-bin
# Configure the local shell only (not persistent) to use the Homebrew LLVM
# toolchain in favour of the default Apple version.  This is taken
# verbatim from the instructions output by Homebrew when installing the
# llvm formula.
export LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"

# helloworld
target_link_libraries(helloworld ${CERES_LIBRARIES})  Irrespective of whether Ceres was installed or exported, if multiple versions are detected, set: Ceres_DIR to control which is used. If Ceres was installed Ceres_DIR should be the path to the directory containing the installed CeresConfig.cmake file (e.g. /usr/local/share/Ceres). If Ceres was exported, then Ceres_DIR should be the path to the exported Ceres build directory. ### Specify Ceres components¶ You can specify particular Ceres components that you require (in order for Ceres to be reported as found) when invoking find_package(Ceres). This allows you to specify, for example, that you require a version of Ceres built with SuiteSparse support. By definition, if you do not specify any components when calling find_package(Ceres) (the default) any version of Ceres detected will be reported as found, irrespective of which components it was built with. The Ceres components which can be specified are: 1. LAPACK: Ceres built using LAPACK (LAPACK=ON). 2. SuiteSparse: Ceres built with SuiteSparse (SUITESPARSE=ON). 3. CXSparse: Ceres built with CXSparse (CXSPARSE=ON). 4. EigenSparse: Ceres built with Eigen’s sparse Cholesky factorization (EIGENSPARSE=ON). 5. SparseLinearAlgebraLibrary: Ceres built with at least one sparse linear algebra library. This is equivalent to SuiteSparse OR CXSparse OR EigenSparse. 6. SchurSpecializations: Ceres built with Schur specializations (SCHUR_SPECIALIZATIONS=ON). 7. OpenMP: Ceres built with OpenMP (OPENMP=ON). 8. TBB: Ceres built with Intel Thread Building Blocks (TBB) (TBB=ON). 9. Multithreading: Ceres built with a multithreading library. This is equivalent to OpenMP OR TBB. 10. C++11: Ceres built with C++11 (CXX11=ON). To specify one/multiple Ceres components use the COMPONENTS argument to find_package() like so: # Find a version of Ceres compiled with SuiteSparse & EigenSparse support. # # NOTE: This will report Ceres as **not** found if the detected version of # Ceres was not compiled with both SuiteSparse & EigenSparse. # Remember, if you have multiple versions of Ceres installed, you # can use Ceres_DIR to specify which should be used. find_package(Ceres REQUIRED COMPONENTS SuiteSparse EigenSparse)  ### Specify Ceres version¶ Additionally, when CMake has found Ceres it can optionally check the package version, if it has been specified in the find_package() call. For example: find_package(Ceres 1.2.3 REQUIRED)  ### Local installations¶ If Ceres was installed in a non-standard path by specifying -DCMAKE_INSTALL_PREFIX="/some/where/local", then the user should add the PATHS option to the find_package() command, e.g., find_package(Ceres REQUIRED PATHS "/some/where/local/")  Note that this can be used to have multiple versions of Ceres installed. However, particularly if you have only a single version of Ceres which you want to use but do not wish to install to a system location, you should consider exporting Ceres using the EXPORT_BUILD_DIR option instead of a local install, as exported versions of Ceres will be automatically detected by CMake, irrespective of their location. ### Understanding the CMake Package System¶ Although a full tutorial on CMake is outside the scope of this guide, here we cover some of the most common CMake misunderstandings that crop up when using Ceres. For more detailed CMake usage, the following references are very useful: • Provides a tour of the core features of CMake. • Cover how to write a ProjectConfig.cmake file, discussed below, for your own project when installing or exporting it using CMake. It also covers how these processes in conjunction with find_package() are actually handled by CMake. The ProjectConfig tutorial is the older style, currently used by Ceres for compatibility with older versions of CMake. Note Targets in CMake. All libraries and executables built using CMake are represented as targets created using add_library() and add_executable(). Targets encapsulate the rules and dependencies (which can be other targets) required to build or link against an object. This allows CMake to implicitly manage dependency chains. Thus it is sufficient to tell CMake that a library target: B depends on a previously declared library target A, and CMake will understand that this means that B also depends on all of the public dependencies of A. When a project like Ceres is installed using CMake, or its build directory is exported into the local CMake package registry (see Installing a project with CMake vs Exporting its build directory), in addition to the public headers and compiled libraries, a set of CMake-specific project configuration files are also installed to: <INSTALL_ROOT>/share/Ceres (if Ceres is installed), or created in the build directory (if Ceres’ build directory is exported). When find_package is invoked, CMake checks various standard install locations (including /usr/local on Linux & UNIX systems), and the local CMake package registry for CMake configuration files for the project to be found (i.e. Ceres in the case of find_package(Ceres)). Specifically it looks for: • <PROJECT_NAME>Config.cmake (or <lower_case_project_name>-config.cmake) Which is written by the developers of the project, and is configured with the selected options and installed locations when the project is built and defines the CMake variables: <PROJECT_NAME>_INCLUDE_DIRS & <PROJECT_NAME>_LIBRARIES which are used by the caller to import the project. The <PROJECT_NAME>Config.cmake typically includes a second file installed to the same location: • <PROJECT_NAME>Targets.cmake Which is autogenerated by CMake as part of the install process and defines imported targets for the project in the caller’s CMake scope. An imported target contains the same information about a library as a CMake target that was declared locally in the current CMake project using add_library(). However, imported targets refer to objects that have already been built by a different CMake project. Principally, an imported target contains the location of the compiled object and all of its public dependencies required to link against it. Any locally declared target can depend on an imported target, and CMake will manage the dependency chain, just as if the imported target had been declared locally by the current project. Crucially, just like any locally declared CMake target, an imported target is identified by its name when adding it as a dependency to another target. Thus, if in a project using Ceres you had the following in your CMakeLists.txt: find_package(Ceres REQUIRED) message("CERES_LIBRARIES =${CERES_LIBRARIES}")


You would see the output: CERES_LIBRARIES = ceres. However, here ceres is an imported target created when CeresTargets.cmake was read as part of find_package(Ceres REQUIRED). It does not refer (directly) to the compiled Ceres library: libceres.a/so/dylib/lib. This distinction is important, as depending on the options selected when it was built, Ceres can have public link dependencies which are encapsulated in the imported target and automatically added to the link step when Ceres is added as a dependency of another target by CMake. In this case, linking only against libceres.a/so/dylib/lib without these other public dependencies would result in a linker error.

Note that this description applies both to projects that are installed using CMake, and to those whose build directory is exported using export() (instead of install()). Ceres supports both installation and export of its build directory if the EXPORT_BUILD_DIR option is enabled, see Customizing the build.

#### Installing a project with CMake vs Exporting its build directory¶

When a project is installed, the compiled libraries and headers are copied from the source & build directory to the install location, and it is these copied files that are used by any client code. When a project’s build directory is exported, instead of copying the compiled libraries and headers, CMake creates an entry for the project in the user’s local CMake package registry, <USER_HOME>/.cmake/packages on Linux & OS X, which contains the path to the project’s build directory which will be checked by CMake during a call to find_package(). The effect of which is that any client code uses the compiled libraries and headers in the build directory directly, thus not requiring the project to be installed to be used.

### Installing / Exporting a project that uses Ceres¶

As described in Understanding the CMake Package System, the contents of the CERES_LIBRARIES variable is the name of an imported target which represents Ceres. If you are installing / exporting your own project which uses Ceres, it is important to understand that:

Imported targets are not (re)exported when a project which imported them is exported.

Thus, when a project Foo which uses Ceres is exported, its list of dependencies as seen by another project Bar which imports Foo via: find_package(Foo REQUIRED) will contain: ceres. However, the definition of ceres as an imported target is not (re)exported when Foo is exported. Hence, without any additional steps, when processing Bar, ceres will not be defined as an imported target. Thus, when processing Bar, CMake will assume that ceres refers only to: libceres.a/so/dylib/lib (the compiled Ceres library) directly if it is on the current list of search paths. In which case, no CMake errors will occur, but Bar will not link properly, as it does not have the required public link dependencies of Ceres, which are stored in the imported target defintion.

The solution to this is for Foo (i.e., the project that uses Ceres) to invoke find_package(Ceres) in FooConfig.cmake, thus ceres will be defined as an imported target when CMake processes Bar. An example of the required modifications to FooConfig.cmake are show below:

# Importing Ceres in FooConfig.cmake using CMake 2.8.x style.
#
# When configure_file() is used to generate FooConfig.cmake from
# FooConfig.cmake.in, @Ceres_DIR@ will be replaced with the current
# value of Ceres_DIR being used by Foo.  This should be passed as a hint
# when invoking find_package(Ceres) to ensure that the same install of
# Ceres is used as was used to build Foo.
set(CERES_DIR_HINTS @Ceres_DIR@)

# Forward the QUIET / REQUIRED options.
if (Foo_FIND_QUIETLY)
find_package(Ceres QUIET HINTS ${CERES_DIR_HINTS}) elseif (Foo_FIND_REQUIRED) find_package(Ceres REQUIRED HINTS${CERES_DIR_HINTS})
else ()
find_package(Ceres HINTS \${CERES_DIR_HINTS})
endif()

# Importing Ceres in FooConfig.cmake using CMake 3.x style.
#
# In CMake v3.x, the find_dependency() macro exists to forward the REQUIRED
# / QUIET parameters to find_package() when searching for dependencies.
#
# Note that find_dependency() does not take a path hint, so if Ceres was
# installed in a non-standard location, that location must be added to
# CMake's search list before this call.
include(CMakeFindDependencyMacro)
find_dependency(Ceres)
`