<commit_before>.. _chapter-building:

=======================
Building & Installation
=======================

Getting the source code
=======================
.. _section-source:

You can start with the `latest stable release
<http://ceres-solver.org/ceres-solver-1.10.0.tar.gz>`_ . Or if you want
the latest version, you can clone the git repository

.. code-block:: bash

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

.. _section-dependencies:

Dependencies
============

Ceres relies on a number of open source libraries, some of which are
optional. For details on customizing the build process, see
:ref:`section-customizing` .

- `Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_
  3.2.1 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 <http://www.cmake.org>`_ 2.8.0 or later.
  **Required on all platforms except for Android.**

- `Google Log <http://code.google.com/p/google-glog>`_ 0.3.1 or
  later. **Recommended**

  .. NOTE::

    Ceres has a minimal replacement of ``glog`` called ``miniglog``
    that can be enabled with the ``MINIGLOG`` build
    option. ``miniglog`` is needed on Android as ``glog`` currently
    does not build using the NDK. It can however be used on other
    platforms too.

    **We do not advise using** ``miniglog`` **on platforms other than
    Android due to the various performance and functionality
    compromises in** ``miniglog``.

  .. NOTE ::

     If you are compiling ``glog`` from source, please note that currently,
     the unit tests for ``glog`` (which are enabled by default) do not compile
     against a default build of ``gflags`` 2.1 as the gflags namespace changed
     from ``google::`` to ``gflags::``.  A patch to fix this is available from
     `here <https://code.google.com/p/google-glog/issues/detail?id=194>`_.

- `Google Flags <http://code.google.com/p/gflags>`_. Needed to build
  examples and tests.

- `SuiteSparse
  <http://www.cise.ufl.edu/research/sparse/SuiteSparse/>`_. Needed for
  solving large sparse linear systems. **Optional; strongly recomended
  for large scale bundle adjustment**

- `CXSparse <http://www.cise.ufl.edu/research/sparse/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 <http://www.netlib.org/blas/>`_ and `LAPACK
  <http://www.netlib.org/lapack/>`_ routines are needed by
  ``SuiteSparse``, and optionally used by Ceres directly for some
  operations.

  On ``UNIX`` OSes other than Mac OS X we recommend `ATLAS
  <http://math-atlas.sourceforge.net/>`_, which includes ``BLAS`` and
  ``LAPACK`` routines. It is also possible to use `OpenBLAS
  <https://github.com/xianyi/OpenBLAS>`_ . However, one needs to be
  careful to `turn off the threading
  <https://github.com/xianyi/OpenBLAS/wiki/faq#wiki-multi-threaded>`_
  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 <http://icl.cs.utk.edu/lapack-for-windows/lapack/>`_
  has detailed instructions..

  **Optional but required for** ``SuiteSparse``.

.. _section-linux:

Linux
=====

We will use `Ubuntu <http://www.ubuntu.com>`_ as our example linux
distribution.

.. NOTE::

 Up to at least Ubuntu 13.10, the SuiteSparse package in the official
 package repository (built from SuiteSparse v3.4.0) **cannot** be used
 to build Ceres as a *shared* library.  Thus if you want to build
 Ceres as a shared library using SuiteSparse, you must perform a
 source install of SuiteSparse.  It is recommended that you use the
 current version of SuiteSparse (4.2.1 at the time of writing).


Start by installing all the dependencies.

.. code-block:: bash

     # CMake
     sudo apt-get install cmake
     # gflags
     tar -xvzf gflags-2.0.tar.gz
     cd gflags-2.0
     ./configure --prefix=/usr/local
     make
     sudo make install.
     # google-glog must be configured to use the previously installed gflags
     tar -xvzf glog-0.3.2.tar.gz
     cd glog-0.3.2
     ./configure --with-gflags=/usr/local/
     make
     sudo make install
     # BLAS & LAPACK
     sudo apt-get install libatlas-base-dev
     # Eigen3
     sudo apt-get install libeigen3-dev
     # SuiteSparse and CXSparse (optional)
     # - If you want to build Ceres as a *static* library (the default)
     #   you can use the SuiteSparse package in the main Ubuntu package
     #   repository:
     sudo apt-get install libsuitesparse-dev
     # - However, if you want to build Ceres as a *shared* library, you must
     #   perform a source install of SuiteSparse (and uninstall the Ubuntu
     #   package if it is currently installed.

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

.. code-block:: bash

 tar zxf ceres-solver-1.10.0.tar.gz
 mkdir ceres-bin
 cd ceres-bin
 cmake ../ceres-solver-1.10.0
 make -j3<commit_msg>Update Ubuntu 14.04 installation instructions.<commit_after>.. _chapter-building:

=======================
Building & Installation
=======================

Getting the source code
=======================
.. _section-source:

You can start with the `latest stable release
<http://ceres-solver.org/ceres-solver-1.10.0.tar.gz>`_ . Or if you want
the latest version, you can clone the git repository

.. code-block:: bash

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

.. _section-dependencies:

Dependencies
============

Ceres relies on a number of open source libraries, some of which are
optional. For details on customizing the build process, see
:ref:`section-customizing` .

- `Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_
  3.2.1 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 <http://www.cmake.org>`_ 2.8.0 or later.
  **Required on all platforms except for Android.**

- `Google Log <http://code.google.com/p/google-glog>`_ 0.3.1 or
  later. **Recommended**

  .. NOTE::

    Ceres has a minimal replacement of ``glog`` called ``miniglog``
    that can be enabled with the ``MINIGLOG`` build
    option. ``miniglog`` is needed on Android as ``glog`` currently
    does not build using the NDK. It can however be used on other
    platforms too.

    **We do not advise using** ``miniglog`` **on platforms other than
    Android due to the various performance and functionality
    compromises in** ``miniglog``.

  .. NOTE ::

     If you are compiling ``glog`` from source, please note that currently,
     the unit tests for ``glog`` (which are enabled by default) do not compile
     against a default build of ``gflags`` 2.1 as the gflags namespace changed
     from ``google::`` to ``gflags::``.  A patch to fix this is available from
     `here <https://code.google.com/p/google-glog/issues/detail?id=194>`_.

- `Google Flags <http://code.google.com/p/gflags>`_. Needed to build
  examples and tests.

- `SuiteSparse
  <http://www.cise.ufl.edu/research/sparse/SuiteSparse/>`_. Needed for
  solving large sparse linear systems. **Optional; strongly recomended
  for large scale bundle adjustment**

- `CXSparse <http://www.cise.ufl.edu/research/sparse/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 <http://www.netlib.org/blas/>`_ and `LAPACK
  <http://www.netlib.org/lapack/>`_ routines are needed by
  ``SuiteSparse``, and optionally used by Ceres directly for some
  operations.

  On ``UNIX`` OSes other than Mac OS X we recommend `ATLAS
  <http://math-atlas.sourceforge.net/>`_, which includes ``BLAS`` and
  ``LAPACK`` routines. It is also possible to use `OpenBLAS
  <https://github.com/xianyi/OpenBLAS>`_ . However, one needs to be
  careful to `turn off the threading
  <https://github.com/xianyi/OpenBLAS/wiki/faq#wiki-multi-threaded>`_
  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 <http://icl.cs.utk.edu/lapack-for-windows/lapack/>`_
  has detailed instructions..

  **Optional but required for** ``SuiteSparse``.

.. _section-linux:

Linux
=====

We will use `Ubuntu <http://www.ubuntu.com>`_ 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
 https://bugs.launchpad.net/ubuntu/+source/suitesparse/+bug/1333214).
 It is recommended that you use the current version of SuiteSparse
 (4.2.1 at the time of writing).


Start by installing all the dependencies.

.. code-block:: bash

     # CMake
     sudo apt-get install cmake
     # google-glog + gflags
     sudo apt-get install libgoogle-glog-dev
     # BLAS & LAPACK
     sudo apt-get install libatlas-base-dev
     # Eigen3
     sudo apt-get install libeigen3-dev
     # SuiteSparse and CXSparse (optional)
     # - If you want to build Ceres as a *static* library (the default)
     #   you can use the SuiteSparse package in the main Ubuntu package
     #   repository:
     sudo apt-get install libsuitesparse-dev
     # - However, if you want to build Ceres as a *shared* library, you must
     #   add the following PPA:
     sudo add-apt-repository ppa:bzindovic/suitesparse-bugfix-1319687
     sudo apt-get update
     sudo apt-get install libsuitesparse-dev

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

.. code-block:: bash

 tar zxf ceres-solver-1.10.0.tar.gz
 mkdir ceres-bin
 cd ceres-bin
 cmake ../ceres-solver-1.10.0
 make -j3
{'fraction_non_alphanumeric': 0.12235316661876018, 'fraction_numerical': 0.010156175146114783, 'mean_word_length': 3.3293239319784322, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 9, 'lorem ipsum': 0, 'www.': 12, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2849214', 'n_tokens_mistral': 3408, 'n_tokens_neox': 3185, 'n_words': 1203}