This is an automated email from the ASF dual-hosted git repository. swebb2066 pushed a commit to branch promote_build_documentation in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit b4cacf577d9fac980651d7733a9b5aab6df93c87 Author: Stephen Webb <[email protected]> AuthorDate: Sun Aug 13 16:26:30 2023 +1000 Create a 'Build' top level nav-panel documentation section --- src/site/markdown/{3-development.md => 4-build.md} | 8 ++-- .../{3-development.md => 6-development.md} | 6 +-- src/site/markdown/development/build-cmake.md | 34 ++++--------- src/site/markdown/development/dependencies.md | 55 +++++++++++++++------- src/site/markdown/library-design.md | 2 +- 5 files changed, 51 insertions(+), 54 deletions(-) diff --git a/src/site/markdown/3-development.md b/src/site/markdown/4-build.md similarity index 87% copy from src/site/markdown/3-development.md copy to src/site/markdown/4-build.md index 98994336..f7a8ff3d 100644 --- a/src/site/markdown/3-development.md +++ b/src/site/markdown/4-build.md @@ -1,4 +1,4 @@ -Development {#development-overview} +Build {#build} === <!-- Note: License header cannot be first, as doxygen does not generate @@ -21,11 +21,9 @@ Development {#development-overview} limitations under the License. --> -See the following pages for development information: +See the following pages for information on building Log4cxx: -* @subpage source-repository -* @subpage dependencies * @subpage building +* @subpage dependencies * @subpage build-cmake * @subpage build-vcpkg -* @subpage library-design diff --git a/src/site/markdown/3-development.md b/src/site/markdown/6-development.md similarity index 88% rename from src/site/markdown/3-development.md rename to src/site/markdown/6-development.md index 98994336..a1bf9a8d 100644 --- a/src/site/markdown/3-development.md +++ b/src/site/markdown/6-development.md @@ -1,4 +1,4 @@ -Development {#development-overview} +Develop {#development-overview} === <!-- Note: License header cannot be first, as doxygen does not generate @@ -24,8 +24,4 @@ Development {#development-overview} See the following pages for development information: * @subpage source-repository -* @subpage dependencies -* @subpage building -* @subpage build-cmake -* @subpage build-vcpkg * @subpage library-design diff --git a/src/site/markdown/development/build-cmake.md b/src/site/markdown/development/build-cmake.md index e8601183..31f9272d 100644 --- a/src/site/markdown/development/build-cmake.md +++ b/src/site/markdown/development/build-cmake.md @@ -1,4 +1,4 @@ -Build with CMake {#build-cmake} +Building with CMake {#build-cmake} === <!-- Note: License header cannot be first, as doxygen does not generate @@ -20,8 +20,7 @@ Build with CMake {#build-cmake} See the License for the specific language governing permissions and limitations under the License. --> - -# Building Apache Log4cxx with CMake +[TOC] ## Quick start: @@ -43,22 +42,22 @@ $ sudo make install 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. +extracted into apr-1.7.4, libexpat(from github) and apr-util-1.6.3 in %HOMEPATH%/Libraries. ~~~ $ cd %HOMEPATH%/Libraries $ cmake -S libexpat/expat -B buildtrees/expat -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed $ cmake --build buildtrees/expat --target install --config Release -$ cmake -S apr-1.7.0 -B buildtrees/apr -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed +$ cmake -S apr-1.7.4 -B buildtrees/apr -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed $ 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 -S apr-util-1.6.3 -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 ~~~ -## ccmake options +## CMake options | Option | Usage | |------------------------|-------| @@ -73,21 +72,6 @@ $ cmake --build buildtrees/Log4cxx --target install --config Release | -DPREFER_BOOST=on | Prefer the Boost version of dependent libraries over standard library | | -DLOG4CXX_QT_SUPPORT=ON | Enable QString API and log4cxx::qt namespace methods, requires QtCore, choice of ON, OFF (default). | -## 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: @@ -107,9 +91,9 @@ $ sudo apt-get install libssl-dev libapr1-dev libaprutil1-dev gzip zip CMake can be built from source by typing: ~~~ -$ wget https://github.com/Kitware/CMake/releases/download/v3.16.4/cmake-3.16.4.tar.gz -$ tar xf cmake-3.16.4.tar.gz -$ cd cmake-3.16.4 +$ wget https://github.com/Kitware/CMake/releases/download/v3.27.2/cmake-3.27.2.tar.gz +$ tar xf cmake-3.27.2.tar.gz +$ cd cmake-3.27.2 $ ./bootstrap $ make $ sudo make install diff --git a/src/site/markdown/development/dependencies.md b/src/site/markdown/development/dependencies.md index 3b6641f0..91206d01 100644 --- a/src/site/markdown/development/dependencies.md +++ b/src/site/markdown/development/dependencies.md @@ -1,4 +1,4 @@ -Dependencies {#dependencies} +Log4cxx Dependencies {#dependencies} === <!-- Note: License header cannot be first, as doxygen does not generate @@ -20,26 +20,19 @@ Dependencies {#dependencies} See the License for the specific language governing permissions and limitations under the License. --> - - -# Log4cxx Dependencies +[TOC] As of version 0.12.0, Log4cxx requires a minimum C++ version of C++11. -If C++17 is not available, then Log4cxx requires Boost Thread in order -to build, which in turn requires chrono and date\_time. -log4cxx requires the following software to build and/or run correctly: +Log4cxx requires the following software to build and/or run correctly: |Dependency Name|Version|Dependency Type|Homepage| |---------------|-------|---------------|--------| |Apache Portable Runtime(APR)|>=1.5.4|Compile/Runtime|https://apr.apache.org |APR-Util |>=1.5.4|Compile/Runtime|https://apr.apache.org -|Boost |any? |Compile/runtime. Not required if your compiler supports C++17|https://boost.org |gzip |any |Test/Runtime(optional)|https://gzip.org |sed |any |Test|N/A |zip |any |Test/Runtime(optional)|N/A -|log4j |1.2.14 |Test |https://http://logging.apache.org/log4j/2.x/ -|java |>=6 |Test |https://adoptopenjdk.net ## APR+APR-Util @@ -58,15 +51,41 @@ MinGW, cygwin, or MSYS2. `gzip` and `zip` only needed during runtime if you are compressing the log files, for example by setting a rollover policy which ends in `.gz` or `.zip`. -## log4j+Java +# Optional Dependencies + +The following table lists CMake options that require additional dependencies. + +|CMake option |Dependency Name|Version| Dependency Type | Homepage| +|---------------|---------------| :---: |---------------|--------| +|LOG4CXX_MULTIPROCESS_ROLLING_FILE_APPENDER |Boost | any | Compile/runtime. Not required if your compiler supports C++17 | https://boost.org +|ENABLE_FMT_LAYOUT | {fmt} | 9+ | Compile/runtime | https://github.com/fmtlib/fmt +|LOG4CXX_ENABLE_ODBC | unixodbc | any | Compile/runtime (not on Windows) | https://www.unixodbc.org/ +|LOG4CXX_ENABLE_ESMTP | libesmtp | any | Compile/runtime (not on Windows) | +|LOG4CXX_QT_SUPPORT |Qt | 5 | Compile/runtime | https://www.qt.io/download +|LOG4CXX_CFSTRING | Mac OS/X Core Foundation | any | Compile/runtime | https://developer.apple.com/documentation/corefoundation + +## A note on C++ version and Boost + +By default, Log4cxx requests C++20 features. 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 libraries will be used +instead. If you would prefer to use Boost, there are two options you have: -log4j and Java are needed to run some tests to ensure that log4cxx has binary compatability with -log4j. Note that the correct binary for log4j will be downloaded and used automatically if CMAKE is -used to build the project, otherwise one needs to get that manually. Java needs to be installed on -the system already in all cases, but with CMAKE again, if it's not, the corresponding tests are -skipped entirely automatically. +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. # Licenses(direct dependencies only) -**Apache License, Version 2.0**: log4cxx, APR, APR-util -**Boost License, Version 1.0**: boost +| Dependency | License | +|------------|---------| +| APR, APR-util | **Apache License, Version 2.0** | +| Boost | **Boost License, Version 1.0** | +| {fmt} | **MIT** | +| unixodbc | **LGPL** | +| Qt | Refer https://www.qt.io/licensing/ | +| Mac OS/X Core Foundation | **APSL 2.0** | \ No newline at end of file diff --git a/src/site/markdown/library-design.md b/src/site/markdown/library-design.md index 9d673c5f..5f4649e9 100644 --- a/src/site/markdown/library-design.md +++ b/src/site/markdown/library-design.md @@ -1,4 +1,4 @@ -# Library Design Notes {#library-design} +Library Design Notes {#library-design} === <!-- Note: License header cannot be first, as doxygen does not generate
