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.