<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Installation — Ceres Solver</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="top" title="Ceres Solver" href="index.html"/>
<link rel="next" title="Tutorial" href="tutorial.html"/>
<link rel="prev" title="Why?" href="features.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Ceres Solver
</a>
<div class="version">
1.13
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="features.html">Why?</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Installation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#getting-the-source-code">Getting the source code</a></li>
<li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="#linux">Linux</a></li>
<li class="toctree-l2"><a class="reference internal" href="#mac-os-x">Mac OS X</a></li>
<li class="toctree-l2"><a class="reference internal" href="#windows">Windows</a></li>
<li class="toctree-l2"><a class="reference internal" href="#android">Android</a></li>
<li class="toctree-l2"><a class="reference internal" href="#ios">iOS</a></li>
<li class="toctree-l2"><a class="reference internal" href="#customizing-the-build">Customizing the build</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#options-controlling-ceres-configuration">Options controlling Ceres configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="#options-controlling-ceres-dependency-locations">Options controlling Ceres dependency locations</a></li>
<li class="toctree-l3"><a class="reference internal" href="#building-using-custom-blas-lapack-installs">Building using custom BLAS & LAPACK installs</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#using-ceres-with-cmake">Using Ceres with CMake</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#specify-ceres-components">Specify Ceres components</a></li>
<li class="toctree-l3"><a class="reference internal" href="#specify-ceres-version">Specify Ceres version</a></li>
<li class="toctree-l3"><a class="reference internal" href="#local-installations">Local installations</a></li>
<li class="toctree-l3"><a class="reference internal" href="#understanding-the-cmake-package-system">Understanding the CMake Package System</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#installing-a-project-with-cmake-vs-exporting-its-build-directory">Installing a project with CMake vs Exporting its build directory</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#installing-exporting-a-project-that-uses-ceres">Installing / Exporting a project that uses Ceres</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="derivatives.html">On Derivatives</a></li>
<li class="toctree-l1"><a class="reference internal" href="nnls_modeling.html">Modeling Non-linear Least Squares</a></li>
<li class="toctree-l1"><a class="reference internal" href="nnls_solving.html">Solving Non-linear Least Squares</a></li>
<li class="toctree-l1"><a class="reference internal" href="nnls_covariance.html">Covariance Estimation</a></li>
<li class="toctree-l1"><a class="reference internal" href="gradient_solver.html">General Unconstrained Minimization</a></li>
<li class="toctree-l1"><a class="reference internal" href="faqs.html">FAQS, Tips & Tricks</a></li>
<li class="toctree-l1"><a class="reference internal" href="users.html">Users</a></li>
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="version_history.html">Version History</a></li>
<li class="toctree-l1"><a class="reference internal" href="bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Ceres Solver</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>Installation</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="installation">
<span id="chapter-installation"></span><h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h1>
<div class="section" id="getting-the-source-code">
<h2>Getting the source code<a class="headerlink" href="#getting-the-source-code" title="Permalink to this headline">¶</a></h2>
<p id="section-source">You can start with the <a class="reference external" href="http://ceres-solver.org/ceres-solver-1.13.0.tar.gz">latest stable release</a> . Or if you want
the latest version, you can clone the git repository</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>git clone https://ceres-solver.googlesource.com/ceres-solver
</pre></div>
</div>
</div>
<div class="section" id="dependencies">
<span id="section-dependencies"></span><h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2>
<p>Ceres relies on a number of open source libraries, some of which are
optional. For details on customizing the build process, see
<a class="reference internal" href="#section-customizing"><span class="std std-ref">Customizing the build</span></a> .</p>
<ul>
<li><p class="first"><a class="reference external" href="http://eigen.tuxfamily.org/index.php?title=Main_Page">Eigen</a>
3.2.2 or later <strong>strongly</strong> recommended, 3.1.0 or later <strong>required</strong>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Ceres can also use Eigen as a sparse linear algebra
library. Please see the documentation for <code class="docutils literal"><span class="pre">EIGENSPARSE</span></code> for
more details.</p>
</div>
</li>
<li><p class="first"><a class="reference external" href="http://www.cmake.org">CMake</a> 2.8.0 or later.
<strong>Required on all platforms except for Android.</strong></p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/google/glog">glog</a> 0.3.1 or
later. <strong>Recommended</strong></p>
<p><code class="docutils literal"><span class="pre">glog</span></code> 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. <a class="reference external" href="https://github.com/google/glog">glog</a> allows you to
control its behaviour from the command line. Starting with
<code class="docutils literal"><span class="pre">-logtostderr</span></code> you can add <code class="docutils literal"><span class="pre">-v=N</span></code> for increasing values of <code class="docutils literal"><span class="pre">N</span></code>
to get more and more verbose and detailed information about Ceres
internals.</p>
<p>Unfortunately, the current version of <a class="reference external" href="https://github.com/google/glog">google-glog</a> does not build using the Android
NDK. So, Ceres also ships with a minimal replacement of <code class="docutils literal"><span class="pre">glog</span></code>
called <code class="docutils literal"><span class="pre">miniglog</span></code> that can be enabled with the <code class="docutils literal"><span class="pre">MINIGLOG</span></code> build
option.</p>
<p>So, in an attempt to reduce dependencies, it is tempting to use
<cite>miniglog</cite> on platforms other than Android. While there is nothing
preventing the user from doing so, we strongly recommend against
it. <code class="docutils literal"><span class="pre">miniglog</span></code> has worse performance than <code class="docutils literal"><span class="pre">glog</span></code> and is much
harder to control and use.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you are compiling <code class="docutils literal"><span class="pre">glog</span></code> from source, please note that
currently, the unit tests for <code class="docutils literal"><span class="pre">glog</span></code> (which are enabled by
default) do not compile against a default build of <code class="docutils literal"><span class="pre">gflags</span></code> 2.1
as the gflags namespace changed from <code class="docutils literal"><span class="pre">google::</span></code> to
<code class="docutils literal"><span class="pre">gflags::</span></code>. A patch to fix this is available from <a class="reference external" href="https://code.google.com/p/google-glog/issues/detail?id=194">here</a>.</p>
</div>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/gflags/gflags">gflags</a>. Needed to build
examples and tests.</p>
</li>
<li><p class="first"><a class="reference external" href="http://faculty.cse.tamu.edu/davis/suitesparse.html">SuiteSparse</a>. Needed for
solving large sparse linear systems. <strong>Optional; strongly recomended
for large scale bundle adjustment</strong></p>
</li>
<li><p class="first"><a class="reference external" href="http://faculty.cse.tamu.edu/davis/suitesparse.html">CXSparse</a>.
Similar to <code class="docutils literal"><span class="pre">SuiteSparse</span></code> but simpler and slower. CXSparse has
no dependencies on <code class="docutils literal"><span class="pre">LAPACK</span></code> and <code class="docutils literal"><span class="pre">BLAS</span></code>. This makes for a simpler
build process and a smaller binary. <strong>Optional</strong></p>
</li>
<li><p class="first"><a class="reference external" href="http://www.netlib.org/blas/">BLAS</a> and <a class="reference external" href="http://www.netlib.org/lapack/">LAPACK</a> routines are needed by
<code class="docutils literal"><span class="pre">SuiteSparse</span></code>, and optionally used by Ceres directly for some
operations.</p>
<p>On <code class="docutils literal"><span class="pre">UNIX</span></code> OSes other than Mac OS X we recommend <a class="reference external" href="http://math-atlas.sourceforge.net/">ATLAS</a>, which includes <code class="docutils literal"><span class="pre">BLAS</span></code> and
<code class="docutils literal"><span class="pre">LAPACK</span></code> routines. It is also possible to use <a class="reference external" href="https://github.com/xianyi/OpenBLAS">OpenBLAS</a> . However, one needs to be
careful to <a class="reference external" href="https://github.com/xianyi/OpenBLAS/wiki/faq#wiki-multi-threaded">turn off the threading</a>
inside <code class="docutils literal"><span class="pre">OpenBLAS</span></code> as it conflicts with use of threads in Ceres.</p>
<p>Mac OS X ships with an optimized <code class="docutils literal"><span class="pre">LAPACK</span></code> and <code class="docutils literal"><span class="pre">BLAS</span></code>
implementation as part of the <code class="docutils literal"><span class="pre">Accelerate</span></code> framework. The Ceres
build system will automatically detect and use it.</p>
<p>For Windows things are much more complicated. <a class="reference external" href="http://icl.cs.utk.edu/lapack-for-windows/lapack/">LAPACK For
Windows</a>
has detailed instructions..</p>
<p><strong>Optional but required for</strong> <code class="docutils literal"><span class="pre">SuiteSparse</span></code>.</p>
</li>
</ul>
</div>
<div class="section" id="linux">
<span id="section-linux"></span><h2>Linux<a class="headerlink" href="#linux" title="Permalink to this headline">¶</a></h2>
<p>We will use <a class="reference external" href="http://www.ubuntu.com">Ubuntu</a> as our example linux
distribution.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Up to at least Ubuntu 14.04, the SuiteSparse package in the official
package repository (built from SuiteSparse v3.4.0) <strong>cannot</strong> be used
to build Ceres as a <em>shared</em> 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 <a class="reference external" href="https://bugs.launchpad.net/ubuntu/+source/suitesparse/+bug/1333214">bug report
here</a>).
It is recommended that you use the current version of SuiteSparse
(4.2.1 at the time of writing).</p>
</div>
<p>Start by installing all the dependencies.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="c1"># CMake</span>
sudo apt-get install cmake
<span class="c1"># google-glog + gflags</span>
sudo apt-get install libgoogle-glog-dev
<span class="c1"># BLAS & LAPACK</span>
sudo apt-get install libatlas-base-dev
<span class="c1"># Eigen3</span>
sudo apt-get install libeigen3-dev
<span class="c1"># SuiteSparse and CXSparse (optional)</span>
<span class="c1"># - If you want to build Ceres as a *static* library (the default)</span>
<span class="c1"># you can use the SuiteSparse package in the main Ubuntu package</span>
<span class="c1"># repository:</span>
sudo apt-get install libsuitesparse-dev
<span class="c1"># - However, if you want to build Ceres as a *shared* library, you must</span>
<span class="c1"># add the following PPA:</span>
sudo add-apt-repository ppa:bzindovic/suitesparse-bugfix-1319687
sudo apt-get update
sudo apt-get install libsuitesparse-dev
</pre></div>
</div>
<p>We are now ready to build, test, and install Ceres.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>tar zxf ceres-solver-1.13.0.tar.gz
mkdir ceres-bin
<span class="nb">cd</span> ceres-bin
cmake ../ceres-solver-1.13.0
make -j3
make <span class="nb">test</span>
<span class="c1"># Optionally install Ceres, it can also be exported using CMake which</span>
<span class="c1"># allows Ceres to be used without requiring installation, see the documentation</span>
<span class="c1"># for the EXPORT_BUILD_DIR option for more information.</span>
make install
</pre></div>
</div>
<p>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 <a class="reference internal" href="bibliography.html#agarwal" id="id2">[Agarwal]</a>.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>bin/simple_bundle_adjuster ../ceres-solver-1.13.0/data/problem-16-22106-pre.txt
</pre></div>
</div>
<p>This runs Ceres for a maximum of 10 iterations using the
<code class="docutils literal"><span class="pre">DENSE_SCHUR</span></code> linear solver. The output should look something like
this.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>iter cost cost_change <span class="p">|</span>gradient<span class="p">|</span> <span class="p">|</span>step<span class="p">|</span> tr_ratio tr_radius ls_iter iter_time total_time
<span class="m">0</span> 4.185660e+06 0.00e+00 1.09e+08 0.00e+00 0.00e+00 1.00e+04 <span class="m">0</span> 7.59e-02 3.37e-01
<span class="m">1</span> 1.062590e+05 4.08e+06 8.99e+06 5.36e+02 9.82e-01 3.00e+04 <span class="m">1</span> 1.65e-01 5.03e-01
<span class="m">2</span> 4.992817e+04 5.63e+04 8.32e+06 3.19e+02 6.52e-01 3.09e+04 <span class="m">1</span> 1.45e-01 6.48e-01
<span class="m">3</span> 1.899774e+04 3.09e+04 1.60e+06 1.24e+02 9.77e-01 9.26e+04 <span class="m">1</span> 1.43e-01 7.92e-01
<span class="m">4</span> 1.808729e+04 9.10e+02 3.97e+05 6.39e+01 9.51e-01 2.78e+05 <span class="m">1</span> 1.45e-01 9.36e-01
<span class="m">5</span> 1.803399e+04 5.33e+01 1.48e+04 1.23e+01 9.99e-01 8.33e+05 <span class="m">1</span> 1.45e-01 1.08e+00
<span class="m">6</span> 1.803390e+04 9.02e-02 6.35e+01 8.00e-01 1.00e+00 2.50e+06 <span class="m">1</span> 1.50e-01 1.23e+00
Ceres Solver v1.13.0 Solve Report
----------------------------------
Original Reduced
Parameter blocks <span class="m">22122</span> 22122
Parameters <span class="m">66462</span> 66462
Residual blocks <span class="m">83718</span> 83718
Residual <span class="m">167436</span> 167436
Minimizer TRUST_REGION
Dense linear algebra library EIGEN
Trust region strategy LEVENBERG_MARQUARDT
Given Used
Linear solver DENSE_SCHUR DENSE_SCHUR
Threads <span class="m">1</span> 1
Linear solver threads <span class="m">1</span> 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 <span class="o">(</span>in seconds<span class="o">)</span>:
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 <span class="o">(</span>Function tolerance reached. <span class="p">|</span>cost_change<span class="p">|</span>/cost: 1.769766e-09 <<span class="o">=</span> 1.000000e-06<span class="o">)</span>
</pre></div>
</div>
</div>
<div class="section" id="mac-os-x">
<h2>Mac OS X<a class="headerlink" href="#mac-os-x" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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.</p>
</div>
<p>On OS X, you can either use <a class="reference external" href="https://www.macports.org/">MacPorts</a> or
<a class="reference external" href="http://mxcl.github.com/homebrew/">Homebrew</a> to install Ceres Solver.</p>
<p>If using <a class="reference external" href="https://www.macports.org/">MacPorts</a>, then</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>sudo port install ceres-solver
</pre></div>
</div>
<p>will install the latest version.</p>
<p>If using <a class="reference external" href="http://mxcl.github.com/homebrew/">Homebrew</a> and assuming
that you have the <code class="docutils literal"><span class="pre">homebrew/science</span></code> <a class="footnote-reference" href="#f1" id="id5">[1]</a> tap enabled, then</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>brew install ceres-solver
</pre></div>
</div>
<p>will install the latest stable version along with all the required
dependencies and</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>brew install ceres-solver --HEAD
</pre></div>
</div>
<p>will install the latest version in the git repo.</p>
<p>You can also install each of the dependencies by hand using <a class="reference external" href="http://mxcl.github.com/homebrew/">Homebrew</a>. There is no need to install
<code class="docutils literal"><span class="pre">BLAS</span></code> or <code class="docutils literal"><span class="pre">LAPACK</span></code> separately as OS X ships with optimized
<code class="docutils literal"><span class="pre">BLAS</span></code> and <code class="docutils literal"><span class="pre">LAPACK</span></code> routines as part of the <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Performance/Conceptual/vecLib/Reference/reference.html">vecLib</a>
framework.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="c1"># CMake</span>
brew install cmake
<span class="c1"># google-glog and gflags</span>
brew install glog
<span class="c1"># Eigen3</span>
brew install eigen
<span class="c1"># SuiteSparse and CXSparse</span>
brew install suite-sparse
</pre></div>
</div>
<p>We are now ready to build, test, and install Ceres.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>tar zxf ceres-solver-1.13.0.tar.gz
mkdir ceres-bin
<span class="nb">cd</span> ceres-bin
cmake ../ceres-solver-1.13.0
make -j3
make <span class="nb">test</span>
<span class="c1"># Optionally install Ceres, it can also be exported using CMake which</span>
<span class="c1"># allows Ceres to be used without requiring installation, see the</span>
<span class="c1"># documentation for the EXPORT_BUILD_DIR option for more information.</span>
make install
</pre></div>
</div>
<p>Like the Linux build, you should now be able to run
<code class="docutils literal"><span class="pre">bin/simple_bundle_adjuster</span></code>.</p>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="f1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[1]</a></td><td><p class="first">Ceres and many of its dependencies are in <a class="reference external" href="https://github.com/Homebrew/homebrew-science">homebrew/science</a> 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.</p>
<div class="last highlight-bash"><div class="highlight"><pre><span></span>brew tap homebrew/science
</pre></div>
</div>
</td></tr>
</tbody>
</table>
</div>
<div class="section" id="windows">
<span id="section-windows"></span><h2>Windows<a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you find the following CMake difficult to set up, then you may
be interested in a <a class="reference external" href="https://github.com/tbennun/ceres-windows">Microsoft Visual Studio wrapper</a> for Ceres Solver by Tal
Ben-Nun.</p>
</div>
<p>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.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Using <code class="docutils literal"><span class="pre">google-glog</span></code> & <code class="docutils literal"><span class="pre">miniglog</span></code> with windows.h.</p>
<p>The windows.h header if used with GDI (Graphics Device Interface)
defines <code class="docutils literal"><span class="pre">ERROR</span></code>, which conflicts with the definition of <code class="docutils literal"><span class="pre">ERROR</span></code>
as a LogSeverity level in <code class="docutils literal"><span class="pre">google-glog</span></code> and <code class="docutils literal"><span class="pre">miniglog</span></code>. There
are at least two possible fixes to this problem:</p>
<ol class="last arabic simple">
<li>Use <code class="docutils literal"><span class="pre">google-glog</span></code> and define <code class="docutils literal"><span class="pre">GLOG_NO_ABBREVIATED_SEVERITIES</span></code>
when building Ceres and your own project, as documented <a class="reference external" href="http://google-glog.googlecode.com/svn/trunk/doc/glog.html">here</a>.
Note that this fix will not work for <code class="docutils literal"><span class="pre">miniglog</span></code>, but use of
<code class="docutils literal"><span class="pre">miniglog</span></code> is strongly discouraged on any platform for which
<code class="docutils literal"><span class="pre">google-glog</span></code> is available (which includes Windows).</li>
<li>If you do not require GDI, then define <code class="docutils literal"><span class="pre">NOGDI</span></code> <strong>before</strong>
including windows.h. This solution should work for both
<code class="docutils literal"><span class="pre">google-glog</span></code> and <code class="docutils literal"><span class="pre">miniglog</span></code> and is documented for
<code class="docutils literal"><span class="pre">google-glog</span></code> <a class="reference external" href="https://code.google.com/p/google-glog/issues/detail?id=33">here</a>.</li>
</ol>
</div>
<ol class="arabic">
<li><p class="first">Make a toplevel directory for deps & build & src somewhere: <code class="docutils literal"><span class="pre">ceres/</span></code></p>
</li>
<li><p class="first">Get dependencies; unpack them as subdirectories in <code class="docutils literal"><span class="pre">ceres/</span></code>
(<code class="docutils literal"><span class="pre">ceres/eigen</span></code>, <code class="docutils literal"><span class="pre">ceres/glog</span></code>, etc)</p>
<ol class="arabic simple">
<li><code class="docutils literal"><span class="pre">Eigen</span></code> 3.1 (needed on Windows; 3.0.x will not work). There is
no need to build anything; just unpack the source tarball.</li>
<li><code class="docutils literal"><span class="pre">google-glog</span></code> Open up the Visual Studio solution and build it.</li>
<li><code class="docutils literal"><span class="pre">gflags</span></code> Open up the Visual Studio solution and build it.</li>
<li>(Experimental) <code class="docutils literal"><span class="pre">SuiteSparse</span></code> Previously SuiteSparse was not
available on Windows, recently it has become possible to build
it on Windows using the <a class="reference external" href="https://github.com/jlblancoc/suitesparse-metis-for-windows">suitesparse-metis-for-windows</a>
project. If you wish to use <code class="docutils literal"><span class="pre">SuiteSparse</span></code>, follow their
instructions for obtaining and building it.</li>
<li>(Experimental) <code class="docutils literal"><span class="pre">CXSparse</span></code> Previously CXSparse was not
available on Windows, there are now several ports that enable it
to be, including: <a class="reference external" href="https://github.com/PetterS/CXSparse">[1]</a>
and <a class="reference external" href="https://github.com/TheFrenchLeaf/CXSparse">[2]</a>. If you
wish to use <code class="docutils literal"><span class="pre">CXSparse</span></code>, follow their instructions for
obtaining and building it.</li>
</ol>
</li>
<li><p class="first">Unpack the Ceres tarball into <code class="docutils literal"><span class="pre">ceres</span></code>. For the tarball, you
should get a directory inside <code class="docutils literal"><span class="pre">ceres</span></code> similar to
<code class="docutils literal"><span class="pre">ceres-solver-1.3.0</span></code>. Alternately, checkout Ceres via <code class="docutils literal"><span class="pre">git</span></code> to
get <code class="docutils literal"><span class="pre">ceres-solver.git</span></code> inside <code class="docutils literal"><span class="pre">ceres</span></code>.</p>
</li>
<li><p class="first">Install <code class="docutils literal"><span class="pre">CMake</span></code>,</p>
</li>
<li><p class="first">Make a dir <code class="docutils literal"><span class="pre">ceres/ceres-bin</span></code> (for an out-of-tree build)</p>
</li>
<li><p class="first">Run <code class="docutils literal"><span class="pre">CMake</span></code>; select the <code class="docutils literal"><span class="pre">ceres-solver-X.Y.Z</span></code> or
<code class="docutils literal"><span class="pre">ceres-solver.git</span></code> directory for the CMake file. Then select the
<code class="docutils literal"><span class="pre">ceres-bin</span></code> for the build dir.</p>
</li>
<li><p class="first">Try running <code class="docutils literal"><span class="pre">Configure</span></code>. It won’t work. It’ll show a bunch of options.
You’ll need to set:</p>
<ol class="arabic simple">
<li><code class="docutils literal"><span class="pre">EIGEN_INCLUDE_DIR_HINTS</span></code></li>
<li><code class="docutils literal"><span class="pre">GLOG_INCLUDE_DIR_HINTS</span></code></li>
<li><code class="docutils literal"><span class="pre">GLOG_LIBRARY_DIR_HINTS</span></code></li>
<li><code class="docutils literal"><span class="pre">GFLAGS_INCLUDE_DIR_HINTS</span></code></li>
<li><code class="docutils literal"><span class="pre">GFLAGS_LIBRARY_DIR_HINTS</span></code></li>
<li>(Optional) <code class="docutils literal"><span class="pre">SUITESPARSE_INCLUDE_DIR_HINTS</span></code></li>
<li>(Optional) <code class="docutils literal"><span class="pre">SUITESPARSE_LIBRARY_DIR_HINTS</span></code></li>
<li>(Optional) <code class="docutils literal"><span class="pre">CXSPARSE_INCLUDE_DIR_HINTS</span></code></li>
<li>(Optional) <code class="docutils literal"><span class="pre">CXSPARSE_LIBRARY_DIR_HINTS</span></code></li>
</ol>
<p>to the appropriate directories where you unpacked/built them. If
any of the variables are not visible in the <code class="docutils literal"><span class="pre">CMake</span></code> GUI, create a
new entry for them. We recommend using the
<code class="docutils literal"><span class="pre"><NAME>_(INCLUDE/LIBRARY)_DIR_HINTS</span></code> variables rather than
setting the <code class="docutils literal"><span class="pre"><NAME>_INCLUDE_DIR</span></code> & <code class="docutils literal"><span class="pre"><NAME>_LIBRARY</span></code> variables
directly to keep all of the validity checking, and to avoid having
to specify the library files manually.</p>
</li>
<li><p class="first">You may have to tweak some more settings to generate a MSVC
project. After each adjustment, try pressing Configure & Generate
until it generates successfully.</p>
</li>
<li><p class="first">Open the solution and build it in MSVC</p>
</li>
</ol>
<p>To run the tests, select the <code class="docutils literal"><span class="pre">RUN_TESTS</span></code> target and hit <strong>Build
RUN_TESTS</strong> from the build menu.</p>
<p>Like the Linux build, you should now be able to run
<code class="docutils literal"><span class="pre">bin/simple_bundle_adjuster</span></code>.</p>
<p>Notes:</p>
<ol class="arabic simple">
<li>The default build is Debug; consider switching it to release mode.</li>
<li>Currently <code class="docutils literal"><span class="pre">system_test</span></code> is not working properly.</li>
<li>CMake puts the resulting test binaries in <code class="docutils literal"><span class="pre">ceres-bin/examples/Debug</span></code>
by default.</li>
<li>The solvers supported on Windows are <code class="docutils literal"><span class="pre">DENSE_QR</span></code>, <code class="docutils literal"><span class="pre">DENSE_SCHUR</span></code>,
<code class="docutils literal"><span class="pre">CGNR</span></code>, and <code class="docutils literal"><span class="pre">ITERATIVE_SCHUR</span></code>.</li>
<li>We’re looking for someone to work with upstream <code class="docutils literal"><span class="pre">SuiteSparse</span></code> to
port their build system to something sane like <code class="docutils literal"><span class="pre">CMake</span></code>, and get a
fully supported Windows port.</li>
</ol>
</div>
<div class="section" id="android">
<span id="section-android"></span><h2>Android<a class="headerlink" href="#android" title="Permalink to this headline">¶</a></h2>
<p>Download the <code class="docutils literal"><span class="pre">Android</span> <span class="pre">NDK</span></code> version <code class="docutils literal"><span class="pre">r9d</span></code> or later. Run
<code class="docutils literal"><span class="pre">ndk-build</span></code> from inside the <code class="docutils literal"><span class="pre">jni</span></code> directory. Use the
<code class="docutils literal"><span class="pre">libceres.a</span></code> that gets created.</p>
</div>
<div class="section" id="ios">
<span id="section-ios"></span><h2>iOS<a class="headerlink" href="#ios" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You need iOS version 7.0 or higher to build Ceres Solver.</p>
</div>
<p>To build Ceres for iOS, we need to force <code class="docutils literal"><span class="pre">CMake</span></code> to find the
toolchains from the iOS SDK instead of using the standard ones. For
example:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>cmake <span class="se">\</span>
-DCMAKE_TOOLCHAIN_FILE<span class="o">=</span>../ceres-solver/cmake/iOS.cmake <span class="se">\</span>
-DEIGEN_INCLUDE_DIR<span class="o">=</span>/path/to/eigen/header <span class="se">\</span>
-DIOS_PLATFORM<span class="o">=</span><PLATFORM> <span class="se">\</span>
<PATH_TO_CERES_SOURCE>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">PLATFORM</span></code> can be: <code class="docutils literal"><span class="pre">OS</span></code>, <code class="docutils literal"><span class="pre">SIMULATOR</span></code> or <code class="docutils literal"><span class="pre">SIMULATOR64</span></code>. You can
build for <code class="docutils literal"><span class="pre">OS</span></code> (<code class="docutils literal"><span class="pre">armv7</span></code>, <code class="docutils literal"><span class="pre">armv7s</span></code>, <code class="docutils literal"><span class="pre">arm64</span></code>), <code class="docutils literal"><span class="pre">SIMULATOR</span></code>
(<code class="docutils literal"><span class="pre">i386</span></code>) or <code class="docutils literal"><span class="pre">SIMULATOR64</span></code> (<code class="docutils literal"><span class="pre">x86_64</span></code>) separately and use <code class="docutils literal"><span class="pre">lipo</span></code>
to merge them into one static library. See <code class="docutils literal"><span class="pre">cmake/iOS.cmake</span></code> for
more options.</p>
<p>After building, you will get a <code class="docutils literal"><span class="pre">libceres.a</span></code> library, which you will
need to add to your Xcode project.</p>
<p>The default CMake configuration builds a bare bones version of Ceres
Solver that only depends on Eigen (<code class="docutils literal"><span class="pre">MINIGLOG</span></code> is compiled into Ceres
if it is used), this should be sufficient for solving small to
moderate sized problems (No <code class="docutils literal"><span class="pre">SPARSE_SCHUR</span></code>,
<code class="docutils literal"><span class="pre">SPARSE_NORMAL_CHOLESKY</span></code> linear solvers and no <code class="docutils literal"><span class="pre">CLUSTER_JACOBI</span></code>
and <code class="docutils literal"><span class="pre">CLUSTER_TRIDIAGONAL</span></code> preconditioners).</p>
<p>If you decide to use <code class="docutils literal"><span class="pre">LAPACK</span></code> and <code class="docutils literal"><span class="pre">BLAS</span></code>, then you also need to
add <code class="docutils literal"><span class="pre">Accelerate.framework</span></code> to your Xcode project’s linking
dependency.</p>
</div>
<div class="section" id="customizing-the-build">
<span id="section-customizing"></span><h2>Customizing the build<a class="headerlink" href="#customizing-the-build" title="Permalink to this headline">¶</a></h2>
<p>It is possible to reduce the libraries needed to build Ceres and
customize the build process by setting the appropriate options in
<code class="docutils literal"><span class="pre">CMake</span></code>. These options can either be set in the <code class="docutils literal"><span class="pre">CMake</span></code> GUI, or
via <code class="docutils literal"><span class="pre">-D<OPTION>=<ON/OFF></span></code> when running <code class="docutils literal"><span class="pre">CMake</span></code> from the command
line. In general, you should only modify these options from their
defaults if you know what you are doing.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>If you are setting variables via <code class="docutils literal"><span class="pre">-D<VARIABLE>=<VALUE></span></code> when
calling <code class="docutils literal"><span class="pre">CMake</span></code>, it is important to understand that this forcibly
<strong>overwrites</strong> the variable <code class="docutils literal"><span class="pre"><VARIABLE></span></code> in the <code class="docutils literal"><span class="pre">CMake</span></code> cache at
the start of <em>every configure</em>.</p>
<p>This can lead to confusion if you are invoking the <code class="docutils literal"><span class="pre">CMake</span></code> <a class="reference external" href="http://www.gnu.org/software/ncurses/ncurses.html">curses</a> terminal GUI
(via <code class="docutils literal"><span class="pre">ccmake</span></code>, e.g. <code class="docutils literal"><span class="pre">`ccmake</span> <span class="pre">-D<VARIABLE>=<VALUE></span>
<span class="pre"><PATH_TO_SRC></span></code>). In this case, even if you change the value of
<code class="docutils literal"><span class="pre"><VARIABLE></span></code> in the <code class="docutils literal"><span class="pre">CMake</span></code> GUI, your changes will be
<strong>overwritten</strong> with the value passed via <code class="docutils literal"><span class="pre">-D<VARIABLE>=<VALUE></span></code>
(if one exists) at the start of each configure.</p>
<p class="last">As such, it is generally easier not to pass values to <code class="docutils literal"><span class="pre">CMake</span></code> via
<code class="docutils literal"><span class="pre">-D</span></code> and instead interactively experiment with their values in the
<code class="docutils literal"><span class="pre">CMake</span></code> GUI. If they are not present in the <em>Standard View</em>,
toggle to the <em>Advanced View</em> with <code class="docutils literal"><span class="pre"><t></span></code>.</p>
</div>
<div class="section" id="options-controlling-ceres-configuration">
<h3>Options controlling Ceres configuration<a class="headerlink" href="#options-controlling-ceres-configuration" title="Permalink to this headline">¶</a></h3>
<ol class="arabic">
<li><p class="first"><code class="docutils literal"><span class="pre">LAPACK</span> <span class="pre">[Default:</span> <span class="pre">ON]</span></code>: By default Ceres will use <code class="docutils literal"><span class="pre">LAPACK</span></code> (&
<code class="docutils literal"><span class="pre">BLAS</span></code>) if they are found. Turn this <code class="docutils literal"><span class="pre">OFF</span></code> to build Ceres
without <code class="docutils literal"><span class="pre">LAPACK</span></code>. Turning this <code class="docutils literal"><span class="pre">OFF</span></code> also disables
<code class="docutils literal"><span class="pre">SUITESPARSE</span></code> as it depends on <code class="docutils literal"><span class="pre">LAPACK</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">SUITESPARSE</span> <span class="pre">[Default:</span> <span class="pre">ON]</span></code>: By default, Ceres will link to
<code class="docutils literal"><span class="pre">SuiteSparse</span></code> if it and all of its dependencies are present. Turn
this <code class="docutils literal"><span class="pre">OFF</span></code> to build Ceres without <code class="docutils literal"><span class="pre">SuiteSparse</span></code>. Note that
<code class="docutils literal"><span class="pre">LAPACK</span></code> must be <code class="docutils literal"><span class="pre">ON</span></code> in order to build with <code class="docutils literal"><span class="pre">SuiteSparse</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">CXSPARSE</span> <span class="pre">[Default:</span> <span class="pre">ON]</span></code>: By default, Ceres will link to
<code class="docutils literal"><span class="pre">CXSparse</span></code> if all its dependencies are present. Turn this <code class="docutils literal"><span class="pre">OFF</span></code>
to build Ceres without <code class="docutils literal"><span class="pre">CXSparse</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">EIGENSPARSE</span> <span class="pre">[Default:</span> <span class="pre">OFF]</span></code>: By default, Ceres will not use
Eigen’s sparse Cholesky factorization. The is because this part of
the code is licensed under the <code class="docutils literal"><span class="pre">LGPL</span></code> and since <code class="docutils literal"><span class="pre">Eigen</span></code> is a
header only library, including this code will result in an <code class="docutils literal"><span class="pre">LGPL</span></code>
licensed version of Ceres.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For good performance, use Eigen version 3.2.2 or later.</p>
</div>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">GFLAGS</span> <span class="pre">[Default:</span> <span class="pre">ON]</span></code>: Turn this <code class="docutils literal"><span class="pre">OFF</span></code> to build Ceres without
<code class="docutils literal"><span class="pre">gflags</span></code>. This will also prevent some of the example code from
building.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">MINIGLOG</span> <span class="pre">[Default:</span> <span class="pre">OFF]</span></code>: Ceres includes a stripped-down,
minimal implementation of <code class="docutils literal"><span class="pre">glog</span></code> which can optionally be used as
a substitute for <code class="docutils literal"><span class="pre">glog</span></code>, thus removing <code class="docutils literal"><span class="pre">glog</span></code> as a required
dependency. Turn this <code class="docutils literal"><span class="pre">ON</span></code> to use this minimal <code class="docutils literal"><span class="pre">glog</span></code>
implementation.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">SCHUR_SPECIALIZATIONS</span> <span class="pre">[Default:</span> <span class="pre">ON]</span></code>: If you are concerned about
binary size/compilation time over some small (10-20%) performance
gains in the <code class="docutils literal"><span class="pre">SPARSE_SCHUR</span></code> solver, you can disable some of the
template specializations by turning this <code class="docutils literal"><span class="pre">OFF</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">OPENMP</span> <span class="pre">[Default:</span> <span class="pre">ON]</span></code>: On certain platforms like Android,
multi-threading with <code class="docutils literal"><span class="pre">OpenMP</span></code> is not supported. Turn this <code class="docutils literal"><span class="pre">OFF</span></code>
to disable multi-threading.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">CXX11</span> <span class="pre">[Default:</span> <span class="pre">OFF]</span></code> <em>Non-MSVC compilers only</em>.</p>
<p>Although Ceres does not currently use C++11, it does use
<code class="docutils literal"><span class="pre">shared_ptr</span></code> (required) and <code class="docutils literal"><span class="pre">unordered_map</span></code> (if available);
both of which existed in the previous iterations of what became the
C++11 standard: TR1 & C++0x. As such, Ceres can compile on
pre-C++11 compilers, using the TR1/C++0x versions of <code class="docutils literal"><span class="pre">shared_ptr</span></code>
& <code class="docutils literal"><span class="pre">unordered_map</span></code>.</p>
<p>Note that when using GCC & Clang, compiling against the TR1/C++0x
versions: <code class="docutils literal"><span class="pre">CXX11=OFF</span></code> (the default) <em>does not</em> require
<code class="docutils literal"><span class="pre">-std=c++11</span></code> when compiling Ceres, <em>nor</em> does it require that any
client code using Ceres use <code class="docutils literal"><span class="pre">-std=c++11</span></code>. However, this will
cause compile errors if any client code that uses Ceres also uses
C++11 (mismatched versions of <code class="docutils literal"><span class="pre">shared_ptr</span></code> & <code class="docutils literal"><span class="pre">unordered_map</span></code>).</p>
<p>Enabling this option: <code class="docutils literal"><span class="pre">CXX11=ON</span></code> forces Ceres to use the C++11
versions of <code class="docutils literal"><span class="pre">shared_ptr</span></code> & <code class="docutils literal"><span class="pre">unordered_map</span></code> if they are
available, and thus imposes the requirement that all client code
using Ceres also compile with <code class="docutils literal"><span class="pre">-std=c++11</span></code>. This requirement is
handled automatically through CMake target properties on the
exported Ceres target for CMake >= 2.8.12 (when it was introduced).
Thus, any client code which uses CMake will automatically be
compiled with <code class="docutils literal"><span class="pre">-std=c++11</span></code>. <strong>On CMake versions < 2.8.12, you
are responsible for ensuring that any code which uses Ceres is
compiled with</strong> <code class="docutils literal"><span class="pre">-std=c++11</span></code>.</p>
<p>On OS X 10.9+, Clang will use the C++11 versions of <code class="docutils literal"><span class="pre">shared_ptr</span></code>
& <code class="docutils literal"><span class="pre">unordered_map</span></code> without <code class="docutils literal"><span class="pre">-std=c++11</span></code> and so this option does
not change the versions detected, although enabling it <em>will</em>
require that client code compile with <code class="docutils literal"><span class="pre">-std=c++11</span></code>.</p>
<p>The following table summarises the effects of the <code class="docutils literal"><span class="pre">CXX11</span></code> option:</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="11%" />
<col width="18%" />
<col width="48%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">OS</th>
<th class="head">CXX11</th>
<th class="head">Detected Version</th>
<th class="head">Ceres & client code require <code class="docutils literal"><span class="pre">-std=c++11</span></code></th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>Linux (GCC & Clang)</td>
<td>OFF</td>
<td>tr1</td>
<td><strong>No</strong></td>
</tr>
<tr class="row-odd"><td>Linux (GCC & Clang)</td>
<td>ON</td>
<td>std</td>
<td><strong>Yes</strong></td>
</tr>
<tr class="row-even"><td>OS X 10.9+</td>
<td>OFF</td>
<td>std</td>
<td><strong>No</strong></td>
</tr>
<tr class="row-odd"><td>OS X 10.9+</td>
<td>ON</td>
<td>std</td>
<td><strong>Yes</strong></td>
</tr>
</tbody>
</table>
<p>The <code class="docutils literal"><span class="pre">CXX11</span></code> option does does not exist when using MSVC, as there
any new C++ features available are enabled by default, and there is
no analogue of <code class="docutils literal"><span class="pre">-std=c++11</span></code>. It will however be available on
MinGW & CygWin, which can support <code class="docutils literal"><span class="pre">-std=c++11</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">BUILD_SHARED_LIBS</span> <span class="pre">[Default:</span> <span class="pre">OFF]</span></code>: By default Ceres is built as
a static library, turn this <code class="docutils literal"><span class="pre">ON</span></code> to instead build Ceres as a
shared library.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">EXPORT_BUILD_DIR</span> <span class="pre">[Default:</span> <span class="pre">OFF]</span></code>: By default Ceres is configured
solely for installation, and so must be installed in order for
clients to use it. Turn this <code class="docutils literal"><span class="pre">ON</span></code> to export Ceres’ build
directory location into the <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/manual/cmake-packages.7.html#user-package-registry">user’s local CMake package registry</a>
where it will be detected <strong>without requiring installation</strong> in a
client project using CMake when <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/find_package.html">find_package(Ceres)</a>
is invoked.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">BUILD_DOCUMENTATION</span> <span class="pre">[Default:</span> <span class="pre">OFF]</span></code>: Use this to enable building
the documentation, requires <a class="reference external" href="http://sphinx-doc.org/">Sphinx</a> and
the <a class="reference external" href="https://pypi.python.org/pypi/sphinx-better-theme">sphinx-better-theme</a> package
available from the Python package index. In addition, <code class="docutils literal"><span class="pre">make</span>
<span class="pre">ceres_docs</span></code> can be used to build only the documentation.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">MSVC_USE_STATIC_CRT</span> <span class="pre">[Default:</span> <span class="pre">OFF]</span></code> <em>Windows Only</em>: By default
Ceres will use the Visual Studio default, <em>shared</em> C-Run Time (CRT)
library. Turn this <code class="docutils literal"><span class="pre">ON</span></code> to use the <em>static</em> C-Run Time library
instead.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">LIB_SUFFIX</span> <span class="pre">[Default:</span> <span class="pre">"64"</span> <span class="pre">on</span> <span class="pre">non-Debian/Arch</span> <span class="pre">based</span> <span class="pre">64-bit</span> <span class="pre">Linux,</span>
<span class="pre">otherwise:</span> <span class="pre">""]</span></code>: The suffix to append to the library install
directory, built from:
<code class="docutils literal"><span class="pre">${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX}</span></code>.</p>
<p>The filesystem hierarchy standard recommends that 64-bit systems
install native libraries to lib64 rather than lib. Most Linux
distributions follow this convention, but Debian and Arch based
distros do not. Note that the only generally sensible values for
<code class="docutils literal"><span class="pre">LIB_SUFFIX</span></code> are “” and “64”.</p>
<p>Although by default Ceres will auto-detect non-Debian/Arch based
64-bit Linux distributions and default <code class="docutils literal"><span class="pre">LIB_SUFFIX</span></code> to “64”, this
can always be overridden by manually specifying LIB_SUFFIX using:
<code class="docutils literal"><span class="pre">-DLIB_SUFFIX=<VALUE></span></code> when invoking CMake.</p>
</li>
</ol>
</div>
<div class="section" id="options-controlling-ceres-dependency-locations">
<h3>Options controlling Ceres dependency locations<a class="headerlink" href="#options-controlling-ceres-dependency-locations" title="Permalink to this headline">¶</a></h3>
<p>Ceres uses the <code class="docutils literal"><span class="pre">CMake</span></code> <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/find_package.html">find_package</a>
function to find all of its dependencies using
<code class="docutils literal"><span class="pre">Find<DEPENDENCY_NAME>.cmake</span></code> scripts which are either included in
Ceres (for most dependencies) or are shipped as standard with
<code class="docutils literal"><span class="pre">CMake</span></code> (for <code class="docutils literal"><span class="pre">LAPACK</span></code> & <code class="docutils literal"><span class="pre">BLAS</span></code>). These scripts will search all
of the “standard” install locations for various OSs for each
dependency. However, particularly for Windows, they may fail to find
the library, in this case you will have to manually specify its
installed location. The <code class="docutils literal"><span class="pre">Find<DEPENDENCY_NAME>.cmake</span></code> scripts
shipped with Ceres support two ways for you to do this:</p>
<ol class="arabic">
<li><p class="first">Set the <em>hints</em> variables specifying the <em>directories</em> to search in
preference, but in addition, to the search directories in the
<code class="docutils literal"><span class="pre">Find<DEPENDENCY_NAME>.cmake</span></code> script:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre"><DEPENDENCY_NAME</span> <span class="pre">(CAPS)>_INCLUDE_DIR_HINTS</span></code></li>
<li><code class="docutils literal"><span class="pre"><DEPENDENCY_NAME</span> <span class="pre">(CAPS)>_LIBRARY_DIR_HINTS</span></code></li>
</ul>
<p>These variables should be set via <code class="docutils literal"><span class="pre">-D<VAR>=<VALUE></span></code>
<code class="docutils literal"><span class="pre">CMake</span></code> arguments as they are not visible in the GUI.</p>
</li>
<li><p class="first">Set the variables specifying the <em>explicit</em> include directory
and library file to use:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre"><DEPENDENCY_NAME</span> <span class="pre">(CAPS)>_INCLUDE_DIR</span></code></li>
<li><code class="docutils literal"><span class="pre"><DEPENDENCY_NAME</span> <span class="pre">(CAPS)>_LIBRARY</span></code></li>
</ul>
<p>This bypasses <em>all</em> searching in the
<code class="docutils literal"><span class="pre">Find<DEPENDENCY_NAME>.cmake</span></code> script, but validation is still
performed.</p>
<p>These variables are available to set in the <code class="docutils literal"><span class="pre">CMake</span></code> GUI. They are
visible in the <em>Standard View</em> if the library has not been found
(but the current Ceres configuration requires it), but are always
visible in the <em>Advanced View</em>. They can also be set directly via
<code class="docutils literal"><span class="pre">-D<VAR>=<VALUE></span></code> arguments to <code class="docutils literal"><span class="pre">CMake</span></code>.</p>
</li>
</ol>
</div>
<div class="section" id="building-using-custom-blas-lapack-installs">
<h3>Building using custom BLAS & LAPACK installs<a class="headerlink" href="#building-using-custom-blas-lapack-installs" title="Permalink to this headline">¶</a></h3>
<p>If the standard find package scripts for <code class="docutils literal"><span class="pre">BLAS</span></code> & <code class="docutils literal"><span class="pre">LAPACK</span></code> which
ship with <code class="docutils literal"><span class="pre">CMake</span></code> fail to find the desired libraries on your system,
try setting <code class="docutils literal"><span class="pre">CMAKE_LIBRARY_PATH</span></code> to the path(s) to the directories
containing the <code class="docutils literal"><span class="pre">BLAS</span></code> & <code class="docutils literal"><span class="pre">LAPACK</span></code> libraries when invoking <code class="docutils literal"><span class="pre">CMake</span></code>
to build Ceres via <code class="docutils literal"><span class="pre">-D<VAR>=<VALUE></span></code>. This should result in the
libraries being found for any common variant of each.</p>
<p>If you are building on an exotic system, or setting
<code class="docutils literal"><span class="pre">CMAKE_LIBRARY_PATH</span></code> does not work, or is not appropriate for some
other reason, one option would be to write your own custom versions of
<code class="docutils literal"><span class="pre">FindBLAS.cmake</span></code> & <code class="docutils literal"><span class="pre">FindLAPACK.cmake</span></code> specific to your
environment. In this case you must set <code class="docutils literal"><span class="pre">CMAKE_MODULE_PATH</span></code> to the
directory containing these custom scripts when invoking <code class="docutils literal"><span class="pre">CMake</span></code> to
build Ceres and they will be used in preference to the default
versions. However, in order for this to work, your scripts must
provide the full set of variables provided by the default scripts.
Also, if you are building Ceres with <code class="docutils literal"><span class="pre">SuiteSparse</span></code>, the versions of
<code class="docutils literal"><span class="pre">BLAS</span></code> & <code class="docutils literal"><span class="pre">LAPACK</span></code> used by <code class="docutils literal"><span class="pre">SuiteSparse</span></code> and Ceres should be the
same.</p>
</div>
</div>
<div class="section" id="using-ceres-with-cmake">
<span id="section-using-ceres"></span><h2>Using Ceres with CMake<a class="headerlink" href="#using-ceres-with-cmake" title="Permalink to this headline">¶</a></h2>
<p>In order to use Ceres in client code with CMake using <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/find_package.html">find_package()</a>
then either:</p>
<ol class="arabic">
<li><dl class="first docutils">
<dt>Ceres must have been installed with <code class="docutils literal"><span class="pre">make</span> <span class="pre">install</span></code>. If the</dt>
<dd><p class="first">install location is non-standard (i.e. is not in CMake’s default
search paths) then it will not be detected by default, see:
<a class="reference internal" href="#section-local-installations"><span class="std std-ref">Local installations</span></a>.</p>
<p class="last">Note that if you are using a non-standard install location you
should consider exporting Ceres instead, as this will not require
any extra information to be provided in client code for Ceres to
be detected.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>Or Ceres’ build directory must have been exported by enabling the</dt>
<dd><p class="first last"><code class="docutils literal"><span class="pre">EXPORT_BUILD_DIR</span></code> option when Ceres was configured.</p>
</dd>
</dl>
</li>
</ol>
<p>As an example of how to use Ceres, to compile <a class="reference external" href="https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/helloworld.cc">examples/helloworld.cc</a>
in a separate standalone project, the following CMakeList.txt can be
used:</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="nb">cmake_minimum_required</span><span class="p">(</span><span class="s">VERSION</span> <span class="s">2.8</span><span class="p">)</span>
<span class="nb">project</span><span class="p">(</span><span class="s">helloworld</span><span class="p">)</span>
<span class="nb">find_package</span><span class="p">(</span><span class="s">Ceres</span> <span class="s">REQUIRED</span><span class="p">)</span>
<span class="nb">include_directories</span><span class="p">(</span><span class="o">${</span><span class="nv">CERES_INCLUDE_DIRS</span><span class="o">}</span><span class="p">)</span>
<span class="c"># helloworld</span>
<span class="nb">add_executable</span><span class="p">(</span><span class="s">helloworld</span> <span class="s">helloworld.cc</span><span class="p">)</span>
<span class="nb">target_link_libraries</span><span class="p">(</span><span class="s">helloworld</span> <span class="o">${</span><span class="nv">CERES_LIBRARIES</span><span class="o">}</span><span class="p">)</span>
</pre></div>
</div>
<p>Irrespective of whether Ceres was installed or exported, if multiple
versions are detected, set: <code class="docutils literal"><span class="pre">Ceres_DIR</span></code> to control which is used.
If Ceres was installed <code class="docutils literal"><span class="pre">Ceres_DIR</span></code> should be the path to the
directory containing the installed <code class="docutils literal"><span class="pre">CeresConfig.cmake</span></code> file
(e.g. <code class="docutils literal"><span class="pre">/usr/local/share/Ceres</span></code>). If Ceres was exported, then
<code class="docutils literal"><span class="pre">Ceres_DIR</span></code> should be the path to the exported Ceres build
directory.</p>
<div class="section" id="specify-ceres-components">
<h3>Specify Ceres components<a class="headerlink" href="#specify-ceres-components" title="Permalink to this headline">¶</a></h3>
<p>You can specify particular Ceres components that you require (in order
for Ceres to be reported as found) when invoking
<code class="docutils literal"><span class="pre">find_package(Ceres)</span></code>. 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
<code class="docutils literal"><span class="pre">find_package(Ceres)</span></code> (the default) any version of Ceres detected
will be reported as found, irrespective of which components it was
built with.</p>
<p>The Ceres components which can be specified are:</p>
<ol class="arabic simple">
<li><code class="docutils literal"><span class="pre">LAPACK</span></code>: Ceres built using LAPACK (<code class="docutils literal"><span class="pre">LAPACK=ON</span></code>).</li>
<li><code class="docutils literal"><span class="pre">SuiteSparse</span></code>: Ceres built with SuiteSparse (<code class="docutils literal"><span class="pre">SUITESPARSE=ON</span></code>).</li>
<li><code class="docutils literal"><span class="pre">CXSparse</span></code>: Ceres built with CXSparse (<code class="docutils literal"><span class="pre">CXSPARSE=ON</span></code>).</li>
<li><code class="docutils literal"><span class="pre">EigenSparse</span></code>: Ceres built with Eigen’s sparse Cholesky factorization
(<code class="docutils literal"><span class="pre">EIGENSPARSE=ON</span></code>).</li>
<li><code class="docutils literal"><span class="pre">SparseLinearAlgebraLibrary</span></code>: Ceres built with <em>at least one</em> sparse linear
algebra library. This is equivalent to <code class="docutils literal"><span class="pre">SuiteSparse</span></code> <strong>OR</strong> <code class="docutils literal"><span class="pre">CXSparse</span></code>
<strong>OR</strong> <code class="docutils literal"><span class="pre">EigenSparse</span></code>.</li>
<li><code class="docutils literal"><span class="pre">SchurSpecializations</span></code>: Ceres built with Schur specializations
(<code class="docutils literal"><span class="pre">SCHUR_SPECIALIZATIONS=ON</span></code>).</li>
<li><code class="docutils literal"><span class="pre">OpenMP</span></code>: Ceres built with OpenMP (<code class="docutils literal"><span class="pre">OPENMP=ON</span></code>).</li>
<li><code class="docutils literal"><span class="pre">C++11</span></code>: Ceres built with C++11 (<code class="docutils literal"><span class="pre">CXX11=ON</span></code>).</li>
</ol>
<p>To specify one/multiple Ceres components use the <code class="docutils literal"><span class="pre">COMPONENTS</span></code> argument to
<a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/find_package.html">find_package()</a> like so:</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="c"># Find a version of Ceres compiled with SuiteSparse & EigenSparse support.</span>
<span class="c">#</span>
<span class="c"># NOTE: This will report Ceres as **not** found if the detected version of</span>
<span class="c"># Ceres was not compiled with both SuiteSparse & EigenSparse.</span>
<span class="c"># Remember, if you have multiple versions of Ceres installed, you</span>
<span class="c"># can use Ceres_DIR to specify which should be used.</span>
<span class="nb">find_package</span><span class="p">(</span><span class="s">Ceres</span> <span class="s">REQUIRED</span> <span class="s">COMPONENTS</span> <span class="s">SuiteSparse</span> <span class="s">EigenSparse</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="specify-ceres-version">
<h3>Specify Ceres version<a class="headerlink" href="#specify-ceres-version" title="Permalink to this headline">¶</a></h3>
<p>Additionally, when CMake has found Ceres it can optionally check the package
version, if it has been specified in the <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/find_package.html">find_package()</a>
call. For example:</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="nb">find_package</span><span class="p">(</span><span class="s">Ceres</span> <span class="s">1.2.3</span> <span class="s">REQUIRED</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="local-installations">
<span id="section-local-installations"></span><h3>Local installations<a class="headerlink" href="#local-installations" title="Permalink to this headline">¶</a></h3>
<p>If Ceres was installed in a non-standard path by specifying
<code class="docutils literal"><span class="pre">-DCMAKE_INSTALL_PREFIX="/some/where/local"</span></code>, then the user should
add the <strong>PATHS</strong> option to the <code class="docutils literal"><span class="pre">find_package()</span></code> command, e.g.,</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="nb">find_package</span><span class="p">(</span><span class="s">Ceres</span> <span class="s">REQUIRED</span> <span class="s">PATHS</span> <span class="s2">"/some/where/local/"</span><span class="p">)</span>
</pre></div>
</div>
<p>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
<code class="docutils literal"><span class="pre">EXPORT_BUILD_DIR</span></code> option instead of a local install, as exported
versions of Ceres will be automatically detected by CMake,
irrespective of their location.</p>
</div>
<div class="section" id="understanding-the-cmake-package-system">
<h3>Understanding the CMake Package System<a class="headerlink" href="#understanding-the-cmake-package-system" title="Permalink to this headline">¶</a></h3>
<p>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:</p>
<ul>
<li><p class="first">The <a class="reference external" href="http://www.cmake.org/cmake-tutorial/">official CMake tutorial</a></p>
<blockquote>
<div><p>Provides a tour of the core features of CMake.</p>
</div></blockquote>
</li>
<li><p class="first"><a class="reference external" href="http://www.cmake.org/Wiki/CMake/Tutorials/How_to_create_a_ProjectConfig.cmake_file">ProjectConfig tutorial</a>
and the <a class="reference external" href="http://www.cmake.org/cmake/help/git-master/manual/cmake-packages.7.html">cmake-packages documentation</a></p>
<blockquote>
<div><p>Cover how to write a <code class="docutils literal"><span class="pre">ProjectConfig.cmake</span></code> file, discussed below,
for your own project when installing or exporting it using CMake.
It also covers how these processes in conjunction with
<code class="docutils literal"><span class="pre">find_package()</span></code> are actually handled by CMake. The
<a class="reference external" href="http://www.cmake.org/Wiki/CMake/Tutorials/How_to_create_a_ProjectConfig.cmake_file">ProjectConfig tutorial</a>
is the older style, currently used by Ceres for compatibility with
older versions of CMake.</p>
</div></blockquote>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p><strong>Targets in CMake.</strong></p>
<p class="last">All libraries and executables built using CMake are represented as
<em>targets</em> created using <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/add_library.html">add_library()</a>
and <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/add_executable.html">add_executable()</a>.
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: <code class="docutils literal"><span class="pre">B</span></code> depends on a
previously declared library target <code class="docutils literal"><span class="pre">A</span></code>, and CMake will
understand that this means that <code class="docutils literal"><span class="pre">B</span></code> also depends on all of the
public dependencies of <code class="docutils literal"><span class="pre">A</span></code>.</p>
</div>
</li>
</ul>
<p>When a project like Ceres is installed using CMake, or its build
directory is exported into the local CMake package registry (see
<a class="reference internal" href="#section-install-vs-export"><span class="std std-ref">Installing a project with CMake vs Exporting its build directory</span></a>), in addition to the public headers
and compiled libraries, a set of CMake-specific project configuration
files are also installed to: <code class="docutils literal"><span class="pre"><INSTALL_ROOT>/share/Ceres</span></code> (if Ceres
is installed), or created in the build directory (if Ceres’ build
directory is exported). When <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/find_package.html">find_package</a> is
invoked, CMake checks various standard install locations (including
<code class="docutils literal"><span class="pre">/usr/local</span></code> 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 <code class="docutils literal"><span class="pre">find_package(Ceres)</span></code>). Specifically it
looks for:</p>
<ul>
<li><p class="first"><code class="docutils literal"><span class="pre"><PROJECT_NAME>Config.cmake</span></code> (or
<code class="docutils literal"><span class="pre"><lower_case_project_name>-config.cmake</span></code>)</p>
<blockquote>
<div><p>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:
<code class="docutils literal"><span class="pre"><PROJECT_NAME>_INCLUDE_DIRS</span></code> & <code class="docutils literal"><span class="pre"><PROJECT_NAME>_LIBRARIES</span></code>
which are used by the caller to import the project.</p>
</div></blockquote>
</li>
</ul>
<p>The <code class="docutils literal"><span class="pre"><PROJECT_NAME>Config.cmake</span></code> typically includes a second file
installed to the same location:</p>
<ul>
<li><p class="first"><code class="docutils literal"><span class="pre"><PROJECT_NAME>Targets.cmake</span></code></p>
<blockquote>
<div><p>Which is autogenerated by CMake as part of the install process and defines
<strong>imported targets</strong> for the project in the caller’s CMake scope.</p>
</div></blockquote>
</li>
</ul>
<p>An <strong>imported target</strong> contains the same information about a library
as a CMake target that was declared locally in the current CMake
project using <code class="docutils literal"><span class="pre">add_library()</span></code>. 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.</p>
<p>Crucially, just like any locally declared CMake target, an imported target is
identified by its <strong>name</strong> when adding it as a dependency to another target.</p>
<p>Thus, if in a project using Ceres you had the following in your CMakeLists.txt:</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="nb">find_package</span><span class="p">(</span><span class="s">Ceres</span> <span class="s">REQUIRED</span><span class="p">)</span>
<span class="nb">message</span><span class="p">(</span><span class="s2">"CERES_LIBRARIES = ${CERES_LIBRARIES}"</span><span class="p">)</span>
</pre></div>
</div>
<p>You would see the output: <code class="docutils literal"><span class="pre">CERES_LIBRARIES</span> <span class="pre">=</span> <span class="pre">ceres</span></code>. <strong>However</strong>,
here <code class="docutils literal"><span class="pre">ceres</span></code> is an <strong>imported target</strong> created when
<code class="docutils literal"><span class="pre">CeresTargets.cmake</span></code> was read as part of <code class="docutils literal"><span class="pre">find_package(Ceres</span>
<span class="pre">REQUIRED)</span></code>. It does <strong>not</strong> refer (directly) to the compiled Ceres
library: <code class="docutils literal"><span class="pre">libceres.a/so/dylib/lib</span></code>. 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 <code class="docutils literal"><span class="pre">libceres.a/so/dylib/lib</span></code> without these other public
dependencies would result in a linker error.</p>
<p>Note that this description applies both to projects that are
<strong>installed</strong> using CMake, and to those whose <strong>build directory is
exported</strong> using <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/export.html">export()</a> (instead
of <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/command/install.html">install()</a>). Ceres
supports both installation and export of its build directory if the
<code class="docutils literal"><span class="pre">EXPORT_BUILD_DIR</span></code> option is enabled, see
<a class="reference internal" href="#section-customizing"><span class="std std-ref">Customizing the build</span></a>.</p>
<div class="section" id="installing-a-project-with-cmake-vs-exporting-its-build-directory">
<span id="section-install-vs-export"></span><h4>Installing a project with CMake vs Exporting its build directory<a class="headerlink" href="#installing-a-project-with-cmake-vs-exporting-its-build-directory" title="Permalink to this headline">¶</a></h4>
<p>When a project is <strong>installed</strong>, 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 <strong>exported</strong>, instead of copying the
compiled libraries and headers, CMake creates an entry for the project
in the <a class="reference external" href="http://www.cmake.org/cmake/help/v3.2/manual/cmake-packages.7.html#user-package-registry">user’s local CMake package registry</a>,
<code class="docutils literal"><span class="pre"><USER_HOME>/.cmake/packages</span></code> on Linux & OS X, which contains the
path to the project’s build directory which will be checked by CMake
during a call to <code class="docutils literal"><span class="pre">find_package()</span></code>. The effect of which is that any
client code uses the compiled libraries and headers in the build
directory directly, <strong>thus not requiring the project to be installed
to be used</strong>.</p>
</div>
</div>
<div class="section" id="installing-exporting-a-project-that-uses-ceres">
<h3>Installing / Exporting a project that uses Ceres<a class="headerlink" href="#installing-exporting-a-project-that-uses-ceres" title="Permalink to this headline">¶</a></h3>
<p>As described in <a class="reference internal" href="#understanding-the-cmake-package-system">Understanding the CMake Package System</a>, the contents of
the <code class="docutils literal"><span class="pre">CERES_LIBRARIES</span></code> variable is the <strong>name</strong> of an imported target which
represents Ceres. If you are installing / exporting your <em>own</em> project which
<em>uses</em> Ceres, it is important to understand that:</p>
<p><strong>Imported targets are not (re)exported when a project which imported them is
exported</strong>.</p>
<p>Thus, when a project <code class="docutils literal"><span class="pre">Foo</span></code> which uses Ceres is exported, its list of
dependencies as seen by another project <code class="docutils literal"><span class="pre">Bar</span></code> which imports <code class="docutils literal"><span class="pre">Foo</span></code>
via: <code class="docutils literal"><span class="pre">find_package(Foo</span> <span class="pre">REQUIRED)</span></code> will contain: <code class="docutils literal"><span class="pre">ceres</span></code>. However,
the definition of <code class="docutils literal"><span class="pre">ceres</span></code> as an imported target is <strong>not
(re)exported</strong> when Foo is exported. Hence, without any additional
steps, when processing <code class="docutils literal"><span class="pre">Bar</span></code>, <code class="docutils literal"><span class="pre">ceres</span></code> will not be defined as an
imported target. Thus, when processing <code class="docutils literal"><span class="pre">Bar</span></code>, CMake will assume
that <code class="docutils literal"><span class="pre">ceres</span></code> refers only to: <code class="docutils literal"><span class="pre">libceres.a/so/dylib/lib</span></code> (the
compiled Ceres library) directly if it is on the current list of
search paths. In which case, no CMake errors will occur, but <code class="docutils literal"><span class="pre">Bar</span></code>
will not link properly, as it does not have the required public link
dependencies of Ceres, which are stored in the imported target
defintion.</p>
<p>The solution to this is for <code class="docutils literal"><span class="pre">Foo</span></code> (i.e., the project that uses
Ceres) to invoke <code class="docutils literal"><span class="pre">find_package(Ceres)</span></code> in <code class="docutils literal"><span class="pre">FooConfig.cmake</span></code>, thus
<code class="docutils literal"><span class="pre">ceres</span></code> will be defined as an imported target when CMake processes
<code class="docutils literal"><span class="pre">Bar</span></code>. An example of the required modifications to
<code class="docutils literal"><span class="pre">FooConfig.cmake</span></code> are show below:</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="c"># Importing Ceres in FooConfig.cmake using CMake 2.8.x style.</span>
<span class="c">#</span>
<span class="c"># When configure_file() is used to generate FooConfig.cmake from</span>
<span class="c"># FooConfig.cmake.in, @Ceres_DIR@ will be replaced with the current</span>
<span class="c"># value of Ceres_DIR being used by Foo. This should be passed as a hint</span>
<span class="c"># when invoking find_package(Ceres) to ensure that the same install of</span>
<span class="c"># Ceres is used as was used to build Foo.</span>
<span class="nb">set</span><span class="p">(</span><span class="s">CERES_DIR_HINTS</span> <span class="s">@Ceres_DIR@</span><span class="p">)</span>
<span class="c"># Forward the QUIET / REQUIRED options.</span>
<span class="nb">if</span> <span class="p">(</span><span class="s">Foo_FIND_QUIETLY</span><span class="p">)</span>
<span class="nb">find_package</span><span class="p">(</span><span class="s">Ceres</span> <span class="s">QUIET</span> <span class="s">HINTS</span> <span class="o">${</span><span class="nv">CERES_DIR_HINTS</span><span class="o">}</span><span class="p">)</span>
<span class="nb">elseif</span> <span class="p">(</span><span class="s">Foo_FIND_REQUIRED</span><span class="p">)</span>
<span class="nb">find_package</span><span class="p">(</span><span class="s">Ceres</span> <span class="s">REQUIRED</span> <span class="s">HINTS</span> <span class="o">${</span><span class="nv">CERES_DIR_HINTS</span><span class="o">}</span><span class="p">)</span>
<span class="nb">else</span> <span class="p">()</span>
<span class="nb">find_package</span><span class="p">(</span><span class="s">Ceres</span> <span class="s">HINTS</span> <span class="o">${</span><span class="nv">CERES_DIR_HINTS</span><span class="o">}</span><span class="p">)</span>
<span class="nb">endif</span><span class="p">()</span>
</pre></div>
</div>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="c"># Importing Ceres in FooConfig.cmake using CMake 3.x style.</span>
<span class="c">#</span>
<span class="c"># In CMake v3.x, the find_dependency() macro exists to forward the REQUIRED</span>
<span class="c"># / QUIET parameters to find_package() when searching for dependencies.</span>
<span class="c">#</span>
<span class="c"># Note that find_dependency() does not take a path hint, so if Ceres was</span>
<span class="c"># installed in a non-standard location, that location must be added to</span>
<span class="c"># CMake's search list before this call.</span>
<span class="nb">include</span><span class="p">(</span><span class="s">CMakeFindDependencyMacro</span><span class="p">)</span>
<span class="nb">find_dependency</span><span class="p">(</span><span class="s">Ceres</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="tutorial.html" class="btn btn-neutral float-right" title="Tutorial" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="features.html" class="btn btn-neutral" title="Why?" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2016 Google Inc.
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'1.13.0',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML">
MathJax.Hub.Config({
"HTML-CSS": {
availableFonts: ["TeX"]
}
});
</script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49769510-1', 'ceres-solver.org');
ga('send', 'pageview');
</script>
</body>
</html>