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
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 803a7c5..25234ef 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -113,7 +113,21 @@
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 (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 @@
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 @@
"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
diff --git a/docs/source/building.rst b/docs/source/building.rst
index 8582424..2e61ea6 100644
--- a/docs/source/building.rst
+++ b/docs/source/building.rst
@@ -545,6 +545,51 @@
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.
