Add docs explaining how to build Ceres with OpenMP on OS X.
Change-Id: If45c12876dc58a042bbdf017de77003a161dc16c
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 087f227..be553d8 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -421,7 +421,8 @@
endif (UNIX)
else (OPENMP_FOUND)
message("-- Failed to find OpenMP, disabling. This is expected on "
- "Clang < 3.8, and at least Xcode <= 7.")
+ "Clang < 3.8, and at least Xcode <= 8. See Ceres documentation for "
+ "instructions to build with LLVM from Homebrew to enable OpenMP on OS X.")
update_cache_variable(OPENMP OFF)
list(APPEND CERES_COMPILE_OPTIONS CERES_NO_THREADS)
endif (OPENMP_FOUND)
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 1479aca..3d34ee7 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -301,6 +301,46 @@
# documentation for the EXPORT_BUILD_DIR option for more information.
make install
+Building with OpenMP on OS X
+----------------------------
+
+Up to at least Xcode 8, OpenMP support was disabled in Apple's version of
+Clang. However, you can install the latest version of the LLVM toolchain
+from Homebrew which does support OpenMP, and thus build Ceres with OpenMP
+support on OS X. To do this, you must install llvm via Homebrew:
+
+.. code-block:: bash
+
+ # Install latest version of LLVM toolchain.
+ brew install llvm
+
+As the LLVM formula in Homebrew is keg-only, it will not be installed to
+``/usr/local`` to avoid conflicts with the standard Apple LLVM toolchain.
+To build Ceres with the Homebrew LLVM toolchain you should do the
+following:
+
+.. code-block:: bash
+
+ tar zxf ceres-solver-1.13.0.tar.gz
+ mkdir ceres-bin
+ cd ceres-bin
+ # Configure the local shell only (not persistent) to use the Homebrew LLVM
+ # toolchain in favour of the default Apple version. This is taken
+ # verbatim from the instructions output by Homebrew when installing the
+ # llvm formula.
+ export LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib"
+ export CPPFLAGS="-I/usr/local/opt/llvm/include"
+ export PATH="/usr/local/opt/llvm/bin:$PATH"
+ # Force CMake to use the Homebrew version of Clang. OpenMP will be
+ # automatically enabled if it is detected that the compiler supports it.
+ cmake -DCMAKE_C_COMPILER=/usr/local/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/usr/local/opt/llvm/bin/clang++ ../ceres-solver-1.13.0
+ make -j3
+ make test
+ # Optionally install Ceres. It can also be exported using CMake which
+ # allows Ceres to be used without requiring installation. See the
+ # documentation for the EXPORT_BUILD_DIR option for more information.
+ make install
+
Like the Linux build, you should now be able to run
``bin/simple_bundle_adjuster``.
