Various small changes.
1. Compact build instructions.
2. Lots of small edits by Simon Fuhrmann.
Change-Id: I8c0c67922021041dcf7f4ecdb6c6e6dd2e2fd7e5
diff --git a/docs/source/building.rst b/docs/source/building.rst
index 3edcac8..36fecf9 100644
--- a/docs/source/building.rst
+++ b/docs/source/building.rst
@@ -4,8 +4,8 @@
Building
========
-Ceres source code and documentation are hosted at
-http://code.google.com/p/ceres-solver/ .
+Ceres source code and documentation are hosted at `code.google.com
+<http://code.google.com/p/ceres-solver/>`_.
.. _section-dependencies:
@@ -41,10 +41,12 @@
dependency.
6. `CXSparse <http://www.cise.ufl.edu/research/sparse/CXSparse/>`_ is
-used for sparse matrix analysis, ordering and factorization. While it
-is similar to SuiteSparse in scope, its performance is a bit worse but
-is a much simpler library to build and does not have any other
-dependencies. This is an optional dependency.
+a sparse matrix library similar in scope to ``SuiteSparse`` but with
+no dependencies on ``LAPACK`` and ``BLAS``. This makes for a simpler
+build process and a smaller binary. The simplicity comes at a cost --
+for all but the most trivial matrices, ``SuiteSparse`` is
+significantly faster than ``CXSparse``.
+
7. `BLAS <http://www.netlib.org/blas/>`_ and `LAPACK
<http://www.netlib.org/lapack/>`_ routines are needed by
@@ -62,73 +64,41 @@
Building on Linux
=================
-We will use `Ubuntu <http://www.ubuntu.com>`_ as our example platform.
+We will use `Ubuntu <http://www.ubuntu.com>`_ as our example
+platform. Start by installing all the dependencies.
-#. ``CMake``
+.. code-block:: bash
- .. code-block:: bash
-
- sudo apt-get install cmake
-
-#. ``gflags`` can either be installed from source via the ``autoconf``
- invocation
-
- .. code-block:: bash
-
+ # CMake
+ sudo apt-hey install cmake
+ # gflags
tar -xvzf gflags-2.0.tar.gz
cd gflags-2.0
./configure --prefix=/usr/local
make
sudo make install.
-
-
- or via the ``deb`` or ``rpm`` packages available on the ``gflags`` website.
-
-#. ``google-glog`` must be configured to use the previously installed
- ``gflags``, rather than the stripped down version that is bundled
- with ``google-glog``. Assuming you have it installed in ``/usr/local`` the
- following ``autoconf`` invocation installs it.
-
- .. code-block:: bash
-
+ # 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
-
-#. ``Eigen``
-
- .. code-block:: bash
-
- sudo apt-get install libeigen3-dev
-
-#. ``SuiteSparse`` and ``CXSparse``
-
- .. code-block:: bash
-
- sudo apt-get install libsuitesparse-dev
-
- This should automatically bring in the necessary ``BLAS`` and
- ``LAPACK`` dependencies. By co-incidence on Ubuntu, this also
- installs ``CXSparse``.
-
-#. ``protobuf``
-
- .. code-block:: bash
-
- sudo apt-get install libprotobuf-dev
-
+ # Eigen3
+ sudo apt-get install libeigen3-dev
+ # SuiteSparse and CXSparse
+ sudo apt-get install libsuitesparse-dev
+ # protobuf
+ sudo apt-get install libprotobuf-dev
We are now ready to build and test Ceres. Note that ``CMake`` requires
the exact path to the ``libglog.a`` and ``libgflag.a``.
.. code-block:: bash
- tar zxf ceres-solver-1.2.1.tar.gz
+ tar zxf ceres-solver-1.5.0.tar.gz
mkdir ceres-bin
cd ceres-bin
- cmake ../ceres-solver-1.2.1
+ cmake ../ceres-solver-1.5.0
make -j3
make test
@@ -139,7 +109,7 @@
.. code-block:: bash
bin/simple_bundle_adjuster \
- ../ceres-solver-1.2.1/data/problem-16-22106-pre.txt \
+ ../ceres-solver-1.5.0/data/problem-16-22106-pre.txt \
This runs Ceres for a maximum of 10 iterations using the
``DENSE_SCHUR`` linear solver. The output should look something like
@@ -200,39 +170,20 @@
====================
On OS X, we recommend using the `homebrew
-<http://mxcl.github.com/homebrew/>`_ package manager.
+<http://mxcl.github.com/homebrew/>`_ package manager. Start by
+installing all the dependencies.
+.. code-block:: bash
-#. ``CMake``
-
- .. code-block:: bash
-
+ # CMake
brew install cmake
-
-#. ``google-glog`` and ``gflags``
-
-Installing ``google-glog`` takes also brings in ``gflags`` as a dependency.
-
- .. code-block:: bash
-
+ # google-glog and gflags
brew install glog
-
-#. ``Eigen3``
-
- .. code-block:: bash
-
+ # Eigen2
brew install eigen
-
-#. ``SuiteSparse`` and ``CXSparse``
-
- .. code-block:: bash
-
+ # SuiteSparse and CXSparse
brew install suite-sparse
-
-#. ``protobuf``
-
- .. code-block:: bash
-
+ # protobuf
brew install protobuf
@@ -240,10 +191,10 @@
.. code-block:: bash
- tar zxf ceres-solver-1.2.1.tar.gz
+ tar zxf ceres-solver-1.5.0.tar.gz
mkdir ceres-bin
cd ceres-bin
- cmake ../ceres-solver-1.2.1
+ cmake ../ceres-solver-1.5.0
make -j3
make test
@@ -267,7 +218,7 @@
(``ceres/eigen``, ``ceres/glog``, etc)
#. ``Eigen`` 3.1 (needed on Windows; 3.0.x will not work). There is
- no need to build anything; just unpack the source tarball.
+ no need to build anything; just unpack the source tarball.
#. ``google-glog`` Open up the Visual Studio solution and build it.
#. ``gflags`` Open up the Visual Studio solution and build it.
@@ -285,7 +236,7 @@
``ceres-solver.git`` directory for the CMake file. Then select the
``ceres-bin`` for the build dir.
-#. Try running "Configure". It won't work. It'll show a bunch of options.
+#. Try running ``Configure``. It won't work. It'll show a bunch of options.
You'll need to set:
#. ``GLOG_INCLUDE``
@@ -339,36 +290,36 @@
customize the build process by passing appropriate flags to
``CMake``. Use these flags only if you really know what you are doing.
-#. ``-DPROTOBUF=OFF`` : ``protobuf`` is a big dependency and if you do not
- care for the tests that depend on it and the logging support it
- enables, you can use this flag to turn it off.
+#. ``-DPROTOBUF=OFF``: ``protobuf`` is a large and complicated
+ dependency. If you do not care for the tests that depend on it and
+ the logging support it enables, you can use this flag to turn it
+ off.
-#. ``-DSUITESPARSE=OFF`` : By default, Ceres will link to
+#. ``-DSUITESPARSE=OFF``: By default, Ceres will link to
``SuiteSparse`` if all its dependencies are present. Use this flag
- to buils Ceres without ``SuiteSparse``. This will also disable
- dependency checking for ``LAPACK`` and ``BLAS`` This saves on
+ to build Ceres without ``SuiteSparse``. This will also disable
+ dependency checking for ``LAPACK`` and ``BLAS``. This saves on
binary size, but the resulting version of Ceres is not suited to
large scale problems due to the lack of a sparse Cholesky solver.
This will reduce Ceres' dependencies down to ``Eigen``, ``gflags``
and ``google-glog``.
-#. ``-DCXSPARSE=OFF`` : By default, Ceres will link to ``CXSparse`` if all
+#. ``-DCXSPARSE=OFF``: By default, Ceres will link to ``CXSparse`` if all
its dependencies are present. Use this flag to buils Ceres without
``CXSparse``. This saves on binary size, but the resulting version
of Ceres is not suited to large scale problems due to the lack of a
sparse Cholesky solver. This will reduce Ceres' dependencies down
to ``Eigen``, ``gflags`` and ``google-glog``.
-#. ``-DGFLAGS=OFF`` : Use this flag to build Ceres without
+#. ``-DGFLAGS=OFF``: Use this flag to build Ceres without
``gflags``. This will also prevent some of the example code from
building.
-#. ``-DSCHUR_SPECIALIZATIONS=OFF`` : If you are concerned about binary
+#. ``-DSCHUR_SPECIALIZATIONS=OFF``: If you are concerned about binary
size/compilation time over some small (10-20%) performance gains in
the ``SPARSE_SCHUR`` solver, you can disable some of the template
specializations by using this flag.
-#. ``-DOPENMP=OFF`` : On certain platforms like Android,
- multithreading with ``OpenMP`` is not supported. Use this flag to
+#. ``-DOPENMP=OFF``: On certain platforms like Android,
+ multi-threading with ``OpenMP`` is not supported. Use this flag to
disable multithreading.
-
