Add docs for new CXX11 option & mask option for Windows.

- The CXX11 option has no effect on Windows, as there, any new C++11
  features are enabled by default, as such to avoid confusion we only
  present the option for non-Windows.

Change-Id: I38925ae3bb8c16682d404468ba95c611a519b9b9

CMakeLists.txt

@@ -113,7 +113,21 @@ OPTION(EIGENSPARSE
    depends on the sparse QR factorization algorithm, which is licensed
    under the MPL."
   OFF)
-OPTION(CXX11 "Enable use of C++11 if available (requires client code use C++11)." OFF)
+IF (NOT WIN32)
+  # Ceres does not use C++11 internally, however it does use shared_ptr
+  # (required) and unordered_map (if available), both of which were present in
+  # previous iterations of what became C++11.  GCC & Clang can have both TR1 &
+  # C++11 versions of both shared_ptr & unordered_map and by default on Linux,
+  # we will detect the TR1 versions if they exist, as they do NOT require
+  # -std=c++11 to be passed when compiling Ceres, and any client code that uses
+  # Ceres.  This will result in conflicts if the client code uses C++11.
+  # Enabling this option forces the use of the C++11 versions (& -std=c++11) if
+  # available.
+  #
+  # This option is not available on Windows, as there, any new (C++11 etc)
+  # features available are on by default and there is no analogue to -std=c++11.
+  OPTION(CXX11 "Enable use of C++11 headers if available (requires client code use C++11)." OFF)
+ENDIF(NOT WIN32)
 OPTION(EXPORT_BUILD_DIR
   "Export build directory using CMake (enables external use without install)." OFF)
 OPTION(BUILD_TESTING "Enable tests" ON)
@@ -127,8 +141,7 @@ IF (MSVC)
   IF (BUILD_TESTING AND BUILD_SHARED_LIBS)
     MESSAGE(
       "-- Disabling tests. The flags BUILD_TESTING and BUILD_SHARED_LIBS"
-      " are incompatible with MSVC."
-      )
+      " are incompatible with MSVC.")
     UPDATE_CACHE_VARIABLE(BUILD_TESTING OFF)
   ENDIF (BUILD_TESTING AND BUILD_SHARED_LIBS)
 ENDIF (MSVC)
@@ -482,20 +495,14 @@ ELSE (OPENMP)
   LIST(APPEND CERES_COMPILE_OPTIONS CERES_NO_THREADS)
 ENDIF (OPENMP)
 
-# MSVC supports (in some sense) C++11, but does not use the -std=c++11 flag.
 INCLUDE(CheckCXXCompilerFlag)
 CHECK_CXX_COMPILER_FLAG("-std=c++11" COMPILER_HAS_CXX11_FLAG)
-IF (CXX11)
-  # For some compilers (at least GCC 4.8), shared_ptr & unordered_map exist in
-  # two places, as the TR1 versions are still present.  In order to avoid any
-  # conflicts in user code linking against Ceres which uses C++11, we enable
-  # C++11 (which is required when using the non-TR1 versions) if it is available
-  # before searching for shared_ptr & unordered_map.
-  IF (COMPILER_HAS_CXX11_FLAG)
-    # CMAKE_REQUIRED_FLAGS is used by CheckCXXSourceCompiles.
-    SET(CMAKE_REQUIRED_FLAGS -std=c++11)
-  ENDIF (COMPILER_HAS_CXX11_FLAG)
-ENDIF (CXX11)
+IF (CXX11 AND COMPILER_HAS_CXX11_FLAG)
+  # Update CMAKE_REQUIRED_FLAGS used by CheckCXXSourceCompiles to include
+  # -std=c++11 s/t we will detect the C++11 versions of unordered_map &
+  # shared_ptr if they exist.
+  SET(CMAKE_REQUIRED_FLAGS -std=c++11)
+ENDIF (CXX11 AND COMPILER_HAS_CXX11_FLAG)
 
 INCLUDE(FindUnorderedMap)
 FIND_UNORDERED_MAP()
@@ -529,8 +536,8 @@ ELSE (SHARED_PTR_FOUND)
     "if you expect C++11 to be available.")
 ENDIF (SHARED_PTR_FOUND)
 
-# To ensure that CXX11 accurately captures whether we are using C++11, even on
-# MSVC, check if it is required given where the potentially C++11 features Ceres
+# To ensure that CXX11 accurately reflects whether we are using C++11,
+# check if it is required given where the potentially C++11 features Ceres
 # uses were found, and disable it if C++11 is not being used.
 IF (CXX11)
   IF (NOT HAVE_SHARED_PTR_IN_STD_NAMESPACE AND

docs/source/building.rst

@@ -545,6 +545,51 @@ Options controlling Ceres configuration
    multi-threading with ``OpenMP`` is not supported. Turn this ``OFF``
    to disable multi-threading.
 
+#. ``CXX11 [Default: OFF]`` *Non-Windows platforms only*.
+
+   Although Ceres does not currently use C++11, it does use ``shared_ptr``
+   (required) and ``unordered_map`` (if available); both of which existed in the
+   previous iterations of what became the C++11 standard: TR1 & C++0x.  As such,
+   Ceres can compile on pre-C++11 compilers, using the TR1/C++0x versions of
+   ``shared_ptr`` & ``unordered_map``.
+
+   Note that on Linux (GCC & Clang), compiling against the TR1/C++0x versions:
+   ``CXX11=OFF`` (the default) *does not* require ``-std=c++11`` when compiling
+   Ceres, *nor* does it require that any client code using Ceres use
+   ``-std=c++11``.   However, this will cause compile errors if any client code
+   that uses Ceres also uses C++11 (mismatched versions of ``shared_ptr`` &
+   ``unordered_map``).
+
+   Enabling this option: ``CXX11=ON`` forces Ceres to use the C++11
+   versions of ``shared_ptr`` & ``unordered_map`` if they are available, and
+   thus imposes the requirement that all client code using Ceres also
+   compile with ``-std=c++11``.  This requirement is handled automatically
+   through CMake target properties on the exported Ceres target for CMake >=
+   2.8.12 (when it was introduced).  Thus, any client code which uses CMake will
+   automatically be compiled with ``-std=c++11``.  **On CMake versions <
+   2.8.12, you are responsible for ensuring that any code which uses Ceres is
+   compiled with** ``-std=c++11``.
+
+   On OS X 10.9+, Clang will use the C++11 versions of ``shared_ptr`` &
+   ``unordered_map`` without ``-std=c++11`` and so this option does not change
+   the versions detected, although enabling it *will* require that client code
+   compile with ``-std=c++11``.
+
+   The following table summarises the effects of the ``CXX11`` option:
+
+   ===================  ==========  ================  ======================================
+   OS                   CXX11       Detected Version  Ceres & client code require ``-std=c++11``
+   ===================  ==========  ================  ======================================
+   Linux (GCC & Clang)  OFF         tr1               **No**
+   Linux (GCC & Clang)  ON          std               **Yes**
+   OS X 10.9+           OFF         std               **No**
+   OS X 10.9+           ON          std               **Yes**
+   ===================  ==========  ================  ======================================
+
+   The ``CXX11`` option does does not exist for Windows, as there any new C++
+   features available are enabled by default, and there is no analogue of
+   ``-std=c++11``.
+
 #. ``BUILD_SHARED_LIBS [Default: OFF]``: By default Ceres is built as
    a static library, turn this ``ON`` to instead build Ceres as a
    shared library.