Add increased inline threshold (iff Clang) to exported Ceres target.

- When compiled with Clang, Ceres and all of the examples are compiled
  with an increased inlining-threshold, as the default value can result
  in poor Eigen performance.
- Previously, client code using Ceres would typically not use an
  increased inlining-threshold (unless the user has specifically added
  it themselves).  However, increasing the inlining threshold can result
  in significant performance improvements in auto-diffed CostFunctions.
- This patch adds the inlining-threshold flags to the interface flags
  for the Ceres CMake target s/t any client code using Ceres (via
  CMake), and compiled with Clang, will now be compiled with the same
  increased inlining threshold as used by Ceres itself.

Change-Id: I31e8f1abfda140d22e85bb48aa57f028a68a415e

docs/source/faqs.rst

@@ -33,6 +33,34 @@ Building
    NDK. It has worse performance than the full fledged glog library
    and is much harder to control and use.
 
+#. Increase the inlining threshold in Clang for Eigen.
+
+   By default, the inlining threshold (evaluated on a heuristic used by LLVM to
+   guess how expensive a function will be to inline) can hobble Eigen, resulting in
+   poor performance.
+
+   Ceres itself will always be compiled with an increased inline threshold
+   (currently 600) when compiled with Clang.  This increased threshold is also
+   added to the interface flags for the exported Ceres CMake target provided
+   that the CMake version is >= 2.8.12 (from which this was supported).  This
+   means that **any user code that links against Ceres using CMake >= 2.8.12
+   (and is compiled with Clang, irrespective of what Ceres was compiled with)
+   will automatically be compiled with the same increased inlining threshold
+   used to compile Ceres**.
+
+   If you are using CMake < 2.8.12 and Clang in your own code which uses Ceres
+   we recommend that you increase the inlining threshold yourself using:
+
+.. code-block:: cmake
+
+    # Use a larger inlining threshold for Clang, since it can hobble Eigen,
+    # resulting in reduced performance. The -Qunused-arguments is needed because
+    # CMake passes the inline threshold to the linker and clang complains about
+    # it (and dies, if compiling with -Werror).
+    if (CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+      set(CMAKE_CXX_FLAGS
+          "${CMAKE_CXX_FLAGS} -Qunused-arguments -mllvm -inline-threshold=600")
+    endif()
 
 Modeling
 ========