Add fixes for multiple definitions of ERROR on Windows to docs.
- Explain the various ways to fix the problem of multiple definitions
of ERROR from glog / miniglog vs windows.h.
- Add note about use of CMAKE_LIBRARY_PATH to aid FindBLAS & FindLAPACK.
- Fix minor style typo in code-block for sample Ceres output.
Change-Id: I21742614f4c5a8fe1ac8f66811b7777a72bcc503
diff --git a/docs/source/building.rst b/docs/source/building.rst
index 2c187b9..cc2acd9 100644
--- a/docs/source/building.rst
+++ b/docs/source/building.rst
@@ -134,6 +134,7 @@
this.
.. code-block:: bash
+
iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time
0 4.185660e+06 0.00e+00 1.09e+08 0.00e+00 0.00e+00 1.00e+04 0 7.59e-02 3.37e-01
1 1.062590e+05 4.08e+06 8.99e+06 5.36e+02 9.82e-01 3.00e+04 1 1.65e-01 5.03e-01
@@ -255,6 +256,24 @@
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:
+
+ #. Use ``google-glog`` and define ``GLOG_NO_ABBREVIATED_SEVERITIES``
+ when building Ceres and your own project, as documented
+ `here <http://google-glog.googlecode.com/svn/trunk/doc/glog.html>`__.
+ Note that this fix will not work for ``miniglog``,
+ but use of ``miniglog`` is strongly discouraged on any platform for which
+ ``google-glog`` is available (which includes Windows).
+ #. If you do not require GDI, then define ``NOGDI`` **before** including
+ windows.h. This solution should work for both ``google-glog`` and
+ ``miniglog`` and is documented for ``google-glog``
+ `here <https://code.google.com/p/google-glog/issues/detail?id=33>`__.
+
#. Make a toplevel directory for deps & build & src somewhere: ``ceres/``
#. Get dependencies; unpack them as subdirectories in ``ceres/``
(``ceres/eigen``, ``ceres/glog``, etc)
@@ -504,16 +523,23 @@
Building using custom BLAS & LAPACK installs
----------------------------------------------
-If you are building on an exotic system, then the standard find package
-scripts for ``BLAS`` & ``LAPACK`` which ship with ``CMake`` might not
-work. In this case, one option would be to write your own custom versions for
-your environment and then set ``CMAKE_MODULE_PATH`` to the directory
-containing these custom scripts when invoking ``CMake`` 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 ``SuiteSparse``, the
-versions of ``BLAS`` & ``LAPACK`` used by ``SuiteSparse`` and Ceres should be
-the same.
+If the standard find package scripts for ``BLAS`` & ``LAPACK`` which ship with
+``CMake`` fail to find the desired libraries on your system, try setting
+``CMAKE_LIBRARY_PATH`` to the path(s) to the directories containing the
+``BLAS`` & ``LAPACK`` libraries when invoking ``CMake`` to build Ceres via
+``-D<VAR>=<VALUE>``. This should result in the libraries being found for any
+common variant of each.
+
+If you are building on an exotic system, or setting ``CMAKE_LIBRARY_PATH``
+does not work, or is not appropriate for some other reason, one option would be
+to write your own custom versions of ``FindBLAS.cmake`` &
+``FindLAPACK.cmake`` specific to your environment. In this case you must set
+``CMAKE_MODULE_PATH`` to the directory containing these custom scripts when
+invoking ``CMake`` 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 ``SuiteSparse``, the versions of ``BLAS`` & ``LAPACK``
+used by ``SuiteSparse`` and Ceres should be the same.
.. _section-using-ceres:
