diff --git a/docs/source/building.rst b/docs/source/building.rst index cc2acd960..0eb0f06ca 100644 --- a/docs/source/building.rst +++ b/docs/source/building.rst @@ -34,20 +34,25 @@ optional. For details on customizing the build process, see - `Google Log `_ 0.3.1 or later. **Recommended** - Ceres has a minimal replacement of ``glog`` called ``miniglog``, - enabled with the ``MINIGLOG`` build option. ``miniglog`` replaces - the requirement for ``glog``. We advise using full ``glog`` due to - performance compromises in ``miniglog``. ``miniglog`` is needed on - Android. + .. 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``. - `Google Flags `_. Needed to build examples and tests. - `SuiteSparse `_. Needed for - analyzing and solving sparse systems. Ceres useses the AMD, CAMD, - COLAMD and CHOLMOD libraries. - **Optional; strongly recomended for bundle adjustment** + solving large sparse linear systems. **Optional; strongly recomended + for large scale bundle adjustment** - `CXSparse `_. Similar to ``SuiteSparse`` but simpler and slower. CXSparse has @@ -56,21 +61,34 @@ optional. For details on customizing the build process, see - `BLAS `_ and `LAPACK `_ routines are needed by - SuiteSparse, and optionally used by Ceres directly for some operations. - We recommend `ATLAS `_, - which includes BLAS and LAPACK routines. It is also possible to use - `OpenBLAS `_ . However, one needs - to be careful to `turn off the threading + ``SuiteSparse``, and optionally used by Ceres directly for some + operations. + + On ``UNIX`` OSes other than Mac OS X we recommend `ATLAS + `_, which includes ``BLAS`` and + ``LAPACK`` routines. It is also possible to use `OpenBLAS + `_ . However, one needs to be + careful to `turn off the threading `_ inside ``OpenBLAS`` as it conflicts with use of threads in Ceres. - **Optional but required for SuiteSparse** + + MAC OS X ships with an optimized ``LAPACK`` and ``BLAS`` + implementation as part of the ``Accelerate`` framework. The Ceres + build system will automatically detect and use it. + + For Windows things are much more complicated. `LAPACK For + Windows `_ + has detailed instructions.. + + **Optional but required for** ``SuiteSparse``. .. _section-linux: -Building on Linux -================= -We will use `Ubuntu `_ as our example -platform. Start by installing all the dependencies. +Linux +===== + +We will use `Ubuntu `_ as our example linux +distribution. .. NOTE:: @@ -81,6 +99,9 @@ platform. Start by installing all the dependencies. 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 @@ -110,7 +131,7 @@ platform. Start by installing all the dependencies. # perform a source install of SuiteSparse (and uninstall the Ubuntu # package if it is currently installed. -We are now ready to build and test Ceres. +We are now ready to build, test, and install Ceres. .. code-block:: bash @@ -120,6 +141,7 @@ We are now ready to build and test Ceres. cmake ../ceres-solver-1.9.0 make -j3 make test + make install You can also try running the command line bundling application with one of the included problems, which comes from the University of Washington's BAL @@ -187,8 +209,8 @@ this. .. section-osx: -Building on Mac OS X -==================== +Mac OS X +======== .. NOTE:: Ceres will not compile using Xcode 4.5.x (Clang version 4.1) due to a bug in that version of @@ -230,7 +252,7 @@ framework. # SuiteSparse and CXSparse brew install suite-sparse -We are now ready to build and test Ceres. +We are now ready to build, test, and install Ceres. .. code-block:: bash @@ -240,28 +262,30 @@ We are now ready to build and test Ceres. cmake ../ceres-solver-1.9.0 make -j3 make test + make install Like the Linux build, you should now be able to run ``bin/simple_bundle_adjuster``. .. _section-windows: -Building on Windows with Visual Studio -====================================== +Windows +======= 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. +that the Windows port is less featureful and less tested than the +Linux or Mac OS X versions due to the lack of an officially supported +way of building SuiteSparse and CXSparse. There are however a number +of unofficial ways of building these libraries. Building on Windows +also a bit more involved since there is no automated way to install +dependencies. .. NOTE:: Using ``google-glog`` & ``miniglog`` with windows.h. - The windows.h header if used with GDI (Graphics Device Interface) defines - ``ERROR``, which conflicts with the definition of ``ERROR`` as a LogSeverity - level in ``google-glog`` and ``miniglog``. There are at least two possible - fixes to this problem: + The windows.h header if used with GDI (Graphics Device Interface) + defines ``ERROR``, which conflicts with the definition of ``ERROR`` + as a LogSeverity level in ``google-glog`` and ``miniglog``. There + are at least two possible fixes to this problem: #. Use ``google-glog`` and define ``GLOG_NO_ABBREVIATED_SEVERITIES`` when building Ceres and your own project, as documented @@ -357,8 +381,8 @@ Notes: .. _section-android: -Building on Android -=================== +Android +======= Download the ``Android NDK`` version ``r9d`` or later. Run ``ndk-build`` from inside the ``jni`` directory. Use the @@ -366,8 +390,9 @@ Download the ``Android NDK`` version ``r9d`` or later. Run .. _section-ios: -Building on iOS -=============== +iOS +=== + .. NOTE:: You need iOS version 6.0 or higher to build Ceres Solver. diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index aed509a94..b169dbfb4 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -26,8 +26,8 @@ no merges. We now describe how to set up your development environment and submit a change list for review via Gerrit. -Setting up your Development Environment -======================================= +Setting up your Environment +=========================== 1. Download and configure ``git``. @@ -97,8 +97,8 @@ Setting up your Development Environment name. -Submitting a change to Ceres Solver -=================================== +Submitting a change +=================== 1. Make your changes against master or whatever branch you like. Commit your changes as one patch. When you commit, the Gerrit