Switch around how searching for boost works and add documentation (#109)

CMakeLists.txt

@@ -225,6 +225,7 @@ message(STATUS "")
 message(STATUS "log4cxx configuration summary:")
 message(STATUS "")
 
+message(STATUS "  C++ standard: ................... : ${CMAKE_CXX_STANDARD}")
 message(STATUS "  Build shared library ............ : ${BUILD_SHARED_LIBS}")
 message(STATUS "  Build tests ..................... : ${BUILD_TESTING}")
 message(STATUS "  Build site ...................... : ${BUILD_SITE}")
@@ -242,7 +243,13 @@ message(STATUS "  Using libESMTP .................. : ${HAS_LIBESMTP}")
 message(STATUS "  ODBC library .................... : ${HAS_ODBC}")
 message(STATUS "  syslog .......................... : ${HAS_SYSLOG}")
 message(STATUS "  Qt support ...................... : ${LOG4CXX_QT_SUPPORT}")
+message(STATUS "C++ version and Boost settings:")
+message(STATUS "  Prefer boost: ................... : ${PREFER_BOOST}")
+message(STATUS "  thread implementation ........... : ${THREAD_IMPL}")
+message(STATUS "  mutex implementation ............ : ${MUTEX_IMPL}")
+message(STATUS "  shared_ptr implementation ....... : ${SMART_PTR_IMPL}")
 message(STATUS "  shared_mutex implementation ..... : ${SHARED_MUTEX_IMPL}")
+message(STATUS "  atomic implementation ........... : ${ATOMIC_IMPL}")
 
 if(BUILD_TESTING)
 message(STATUS "Applications required for tests:")

src/cmake/boost-fallback/boost-fallback.cmake

@@ -55,9 +55,9 @@ try_compile(STD_SHARED_PTR_FOUND "${CMAKE_BINARY_DIR}/boost-fallback-compile-tes
 try_compile(STD_ATOMIC_FOUND "${CMAKE_BINARY_DIR}/boost-fallback-compile-tests"
     "${CMAKE_CURRENT_LIST_DIR}/test-stdatomic.cpp")
 
-# search for boost only in case needed for legacy c++ standard < c++17
-if(NOT ${STD_THREAD_FOUND} OR NOT ${STD_MUTEX_FOUND} OR NOT ${STD_SHARED_MUTEX_FOUND} OR NOT ${STD_SHARED_PTR_FOUND} OR NOT ${STD_ATOMIC_FOUND})
-find_package(Boost COMPONENTS thread)
+# We need to have all three boost components in order to run our tests
+# Boost thread requires chrono and atomic to work
+find_package(Boost COMPONENTS thread chrono atomic)
 if( ${Boost_FOUND} )
     try_compile(Boost_SHARED_PTR_FOUND "${CMAKE_BINARY_DIR}/boost-fallback-compile-tests"
         "${CMAKE_CURRENT_LIST_DIR}/test-boostsharedptr.cpp")
@@ -69,7 +69,6 @@ if( ${Boost_FOUND} )
     try_compile(Boost_ATOMIC_FOUND "${CMAKE_BINARY_DIR}/boost-fallback-compile-tests"
         "${CMAKE_CURRENT_LIST_DIR}/test-boostatomic.cpp")
 endif( ${Boost_FOUND} )
-endif()
 
 # Link the target with the appropriate boost libraries(if required)
 function(boostfallback_link target)

src/main/include/CMakeLists.txt

@@ -142,40 +142,41 @@ endforeach()
 # Check for standard headers that we need, fall back to boost if they're not found
 include(${LOG4CXX_SOURCE_DIR}/src/cmake/boost-fallback/boost-fallback.cmake)
 set(NAMESPACE_ALIAS log4cxx)
+option(PREFER_BOOST "Prefer Boost over std:: equivalents" OFF)
 
-if( ${STD_THREAD_FOUND} )
+if( ${STD_THREAD_FOUND} AND NOT ${PREFER_BOOST} )
     set( THREAD_IMPL "std::thread" )
 elseif( ${Boost_THREAD_FOUND} )
     set( THREAD_IMPL "boost::thread" )
 else()
     set( THREAD_IMPL "NONE" )
 endif()
 
-if( ${STD_MUTEX_FOUND} )
+if( ${STD_MUTEX_FOUND} AND NOT ${PREFER_BOOST} )
     set( MUTEX_IMPL "std::mutex" )
 elseif( ${Boost_MUTEX_FOUND} )
     set( MUTEX_IMPL "boost::mutex" )
 else()
     set( MUTEX_IMPL "NONE" )
 endif()
 
-if( ${STD_SHARED_PTR_FOUND} )
+if( ${STD_SHARED_PTR_FOUND} AND NOT ${PREFER_BOOST} )
     set( SMART_PTR_IMPL "std::shared_ptr" )
 elseif( ${Boost_SHARED_PTR_FOUND} )
     set( SMART_PTR_IMPL "boost::shared_ptr" )
 else()
     set( SMART_PTR_IMPL "NONE" )
 endif()
 
-if( ${STD_SHARED_MUTEX_FOUND} )
+if( ${STD_SHARED_MUTEX_FOUND} AND NOT ${PREFER_BOOST} )
     set( SHARED_MUTEX_IMPL "std::shared_mutex" )
 elseif( ${Boost_SHARED_MUTEX_FOUND} )
     set( SHARED_MUTEX_IMPL "boost::shared_mutex" )
 else()
     set( SHARED_MUTEX_IMPL "NONE" )
 endif()
 
-if( ${STD_ATOMIC_FOUND} )
+if( ${STD_ATOMIC_FOUND} AND NOT ${PREFER_BOOST} )
     set( ATOMIC_IMPL "std::atomic" )
 elseif( ${Boost_ATOMIC_FOUND} )
     set( ATOMIC_IMPL "boost::atomic" )

src/site/markdown/development/build-cmake.md

@@ -21,39 +21,28 @@ Build with CMake {#build-cmake}
  limitations under the License.
 -->
 
-# Building Apache log4cxx with CMake
+# Building Apache Log4cxx with CMake
 
-* Quick start:
+## Quick start:
 
-  Building and testing log4cxx on a Unix platform with packaged APR and APR-Util.
+  Building and testing Log4cxx on a Unix platform with packaged APR and APR-Util.
 
   Make sure cmake 3.13+, g++ and make are available, install or
   build apr 1.x, apr-util 1.x, gzip and zip.
 
+Linux example:
 ~~~
 $ apt-get install build-essential libapr1-dev libaprutil1-dev gzip zip
-$ cd apache-log4cxx-x.x.x
+$ cd apache-Log4cxx-x.x.x
 $ mkdir build
 $ cd build
 $ ccmake ..
 $ make
 $ sudo make install
 ~~~
 
-* ccmake options
-
-| Option                 | Usage |
-|------------------------|-------|
-| -DLOG4CXX_WCHAR_T=no   | Enable wchar_t API methods, choice of yes (default), no.                                    |
-| -DLOG4CXX_UNICHAR=yes  | Enable UniChar API methods, choice of yes, no (default).                                    |
-| -DLOG4CXX_CFSTRING=yes | Enable CFString API methods, requires Mac OS/X CoreFoundation, choice of yes, no (default). |
-| -DBUILD_TESTING=off    | Do not build tests.  Tests are built by default                                             |
-| -DBUILD_SHARED_LIBS=off| Build log4cxx as a static library. A dynamically linked log4cxx library is built by default. Any compilation unit that includes a log4cxx header must define LOG4CXX_STATIC.             |
-| -DAPU_STATIC=yes       | Link to the APR-Util static library. By default, the log4cxx shared library is linked to the APR-Util shared library. If BUILD_SHARED_LIBS=off, the static APR-Util library is used.     |
-| -DAPR_STATIC=yes       | Link to the APR static library. By default, the log4cxx shared library is linked to the APR shared library. If BUILD_SHARED_LIBS=off, the static APR library is always used.        |
-|-DLOG4CXX_TEST_PROGRAM_PATH=path| An extra path to prepend to the PATH for test programs.  Log4cxx requires zip, sed, and grep on the PATH in order for the tests to work properly.                          |
-
-Building and testing log4cxx on a Microsoft Windows with APR, Expat and APR-Util built from source
+Windows Example:
+Building and testing Log4cxx on a Microsoft Windows with APR, Expat and APR-Util built from source
 extracted into apr-1.7.0, libexpat(from github) and apr-util-1.6.1 in %HOMEPATH%\Libraries.
 
 ~~~
@@ -65,10 +54,39 @@ $ cmake --build buildtrees\apr --target install --config Release
 $ set CMAKE_PREFIX_PATH=%HOMEPATH%\Libraries\installed
 $ cmake -S apr-util-1.6.1 -B buildtrees\apr-util -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
 $ cmake --build buildtrees\apr-util --target install --config Release
-$ cmake -S apache-log4cxx-x.x.x -B buildtrees\log4cxx -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
-$ cmake --build buildtrees\log4cxx --target install --config Release
+$ cmake -S apache-Log4cxx-x.x.x -B buildtrees\Log4cxx -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
+$ cmake --build buildtrees\Log4cxx --target install --config Release
 ~~~
 
+## ccmake options
+
+| Option                 | Usage |
+|------------------------|-------|
+| -DLOG4CXX_WCHAR_T=no   | Enable wchar_t API methods, choice of yes (default), no.                                    |
+| -DLOG4CXX_UNICHAR=yes  | Enable UniChar API methods, choice of yes, no (default).                                    |
+| -DLOG4CXX_CFSTRING=yes | Enable CFString API methods, requires Mac OS/X CoreFoundation, choice of yes, no (default). |
+| -DBUILD_TESTING=off    | Do not build tests.  Tests are built by default                                             |
+| -DBUILD_SHARED_LIBS=off| Build Log4cxx as a static library. A dynamically linked Log4cxx library is built by default. Any compilation unit that includes a Log4cxx header must define LOG4CXX_STATIC.             |
+| -DAPU_STATIC=yes       | Link to the APR-Util static library. By default, the Log4cxx shared library is linked to the APR-Util shared library. If BUILD_SHARED_LIBS=off, the static APR-Util library is used.     |
+| -DAPR_STATIC=yes       | Link to the APR static library. By default, the Log4cxx shared library is linked to the APR shared library. If BUILD_SHARED_LIBS=off, the static APR library is always used.        |
+|-DLOG4CXX_TEST_PROGRAM_PATH=path| An extra path to prepend to the PATH for test programs.  Log4cxx requires zip, sed, and grep on the PATH in order for the tests to work properly.                          |
+| -DPREFER_BOOST=on      | Prefer the Boost version of dependent libraries over standard library |
+
+## A note on C++ version and Boost
+
+By default, Log4cxx attempts to use at least C++17 to compile.  This is to
+avoid 3rd party dependencies as much as possible.  If C++17 is not
+available, a search for Boost will be taken and those libaries will be used
+instead.  If you would prefer to use Boost, there are two options you have:
+
+1. Pass `-DPREFER_BOOST=ON` to CMake when compiling.  This will ignore the
+ results of the tests that check for the standard version of components that
+ are required.  Note that this will switch all components, regardless of the
+ C++ version in effect at compile time.
+2. Revert to an earlier standard using `-DCMAKE_CXX_STANDARD=11` for example.
+ This will still to check for standard versions of required components, but
+ it will fall back to using Boost for newer components added in C++17.
+
 # Platform specific notes:
 
 ## Mac OS/X:
@@ -124,12 +142,12 @@ LOG4CXX_TEST_PROGRAM_PATH=C:/msys64/usr/bin in your build settings.
 For vcpkg, follow the directions at https://github.com/microsoft/vcpkg#quick-start-windows and then install
 the dependencies needed using `vcpkg install apr apr-util`.
 
-# Using log4cxx in a CMake build
+# Using Log4cxx in a CMake build
 
 A log4cxxConfig.cmake and log4cxxConfigVersion.cmake is installed to allow use of find_package()
 in your CMakeLists.txt.
 
-Below are example cmake commands that compile and link "myApplication" with log4cxx.
+Below are example cmake commands that compile and link "myApplication" with Log4cxx.
 
 ~~~
 find_package(log4cxx 0.11)