Create a 'Build' top level nav-panel documentation section (#255)
* Create a 'Build' top level nav-panel documentation section
* Update environments used in testing
* 'Usage' -> 'Use', matching other verbs in the nav-panel
diff --git a/src/site/markdown/1-usage.md b/src/site/markdown/1-usage.md
index ee88b2e..76098f4 100644
--- a/src/site/markdown/1-usage.md
+++ b/src/site/markdown/1-usage.md
@@ -1,4 +1,4 @@
-Usage {#usage-overview}
+Use {#usage-overview}
===
<!--
Note: License header cannot be first, as doxygen does not generate
diff --git a/src/site/markdown/3-development.md b/src/site/markdown/4-build.md
similarity index 86%
copy from src/site/markdown/3-development.md
copy to src/site/markdown/4-build.md
index 9899433..f7a8ff3 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 @@
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 9899433..a1bf9a8 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 @@
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 e860118..31f9272 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 @@
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 @@
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 @@
| -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 @@
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/building.md b/src/site/markdown/development/building.md
index abc696c..6aab32c 100644
--- a/src/site/markdown/development/building.md
+++ b/src/site/markdown/development/building.md
@@ -29,6 +29,17 @@
[Jira](https://issues.apache.org/jira/projects/LOGCXX/issues) or send a
message to the [users mailing list].
+## Covered by Github
+
+These Github provided environments are
+used in continuous integration and unit testing:
+
+* Windows - Visual Studio 2019 and 2022
+* Ubuntu 20.04 - GNU g++ 9.4.0, Clang 11.0.0
+* Ubuntu 22.04 - GNU g++ 11.4.0, Clang 14.0.0
+* MacOS 11 - AppleClang 13.0
+* MacOS 12 - AppleClang 14.0
+
## Covered by the team
The following list provides an overview about the environments some of the
@@ -38,8 +49,9 @@
The following platforms/compilers are expected to work correctly:
-* Windows 10(32 and 64-bit) - MSVC
+* Windows 10(32 and 64-bit) - MSVC 2017, 2019
* Windows 10(32-bit) - Embarcadero C++ Builder XE 4
+* Windows 11(64-bit) - MSVC 2019, 2022
* Debian 10(32 and 64-bit) - gcc 8.3.0, clang-7
* Ubuntu 20.04(32 and 64-bit) - gcc, clang
* Mac OSX - clang
diff --git a/src/site/markdown/development/dependencies.md b/src/site/markdown/development/dependencies.md
index 3b6641f..acf980e 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 @@
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,42 @@
`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
-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.
+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) | https://github.com/libesmtp/libESMTP |
+|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:
+
+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** |
+| libesmtp | **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 9d673c5..5f4649e 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
