This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/master by this push:
new 5c461377 Clarify the roles of LOG4CXX_FORMAT_NAMESPACE and
LOG4CXX_FORMAT_NS macros (#640)
5c461377 is described below
commit 5c4613778999d37a8738c367a952552af48c16e4
Author: Stephen Webb <[email protected]>
AuthorDate: Fri May 1 12:55:54 2026 +1000
Clarify the roles of LOG4CXX_FORMAT_NAMESPACE and LOG4CXX_FORMAT_NS macros
(#640)
* Add a section to the dependencies page
* Add dependency for async logging using {fmt}
---
src/site/markdown/development/build-cmake.md.in | 2 +-
src/site/markdown/development/dependencies.md | 54 +++++++++++++++++++------
src/site/markdown/macros-influencing-log4cxx.md | 9 ++++-
3 files changed, 49 insertions(+), 16 deletions(-)
diff --git a/src/site/markdown/development/build-cmake.md.in
b/src/site/markdown/development/build-cmake.md.in
index d75e9954..e7271dc4 100644
--- a/src/site/markdown/development/build-cmake.md.in
+++ b/src/site/markdown/development/build-cmake.md.in
@@ -39,7 +39,7 @@ Building with CMake {#build-cmake}
| PREFER_BOOST=on | Prefer the Boost version of dependent libraries over
standard library |
| LOG4CXX_QT_SUPPORT=ON | Enable QString API and log4cxx::qt namespace
methods, requires QtCore, choice of ON, OFF (default). |
| LOG4CXX_EVENTS_AT_EXIT=ON | Prevent static data cleanup to allow event
logging during application exit. |
-| LOG4CXX_FORMAT_NAMESPACE=std | Make the `LOG4CXX_[level]_FMT` macros use
[std::format](https://en.cppreference.com/w/cpp/utility/format/format) by
default. |
+| LOG4CXX_FORMAT_NAMESPACE=std | Set LOG4CXX_FORMAT_NS=std when not provided
in
[target_compile_definitions](https://cmake.org/cmake/help/latest/command/target_compile_definitions.html).
LOG4CXX_FORMAT_NS is used in `LOG4CXX_[level]_FMT` logging macros. |
# Examples
diff --git a/src/site/markdown/development/dependencies.md
b/src/site/markdown/development/dependencies.md
index acf980e5..e961057d 100644
--- a/src/site/markdown/development/dependencies.md
+++ b/src/site/markdown/development/dependencies.md
@@ -36,20 +36,40 @@ Log4cxx requires the following software to build and/or run
correctly:
## APR+APR-Util
-The Apache Portable Runtime(APR) provides the cross-platform backend for
log4cxx.
+The Apache Portable Runtime(APR) provides the cross-platform backend for
Log4cxx.
Both APR and APR-util need to be installed and available on your system.
## sed+gzip+zip
-These applications are needed during test of log4cxx. `gzip`and `sed` are
generally installed
-by default on Linux. `zip` may not be installed by default; check your
distribution's
+These applications are needed to test Log4cxx. *gzip* and *sed* are generally
installed
+by default on Linux. *zip* may not be installed by default; check your
distribution's
documentation for information on how to install these applications.
For Windows, you will have to install those tools through a system such as
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`.
+*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*.
+
+## Using std::format instead of fmt::format
+
+The *LOG4CXX_XXXXX_FMT* logging macros use the macro *LOG4CXX_FORMAT_NS*
+to select the *format* function version.
+
+Use the CMake option *LOG4CXX_FORMAT_NAMESPACE=std*
+to set the default value for *LOG4CXX_FORMAT_NS* to *std*.
+If *LOG4CXX_FORMAT_NAMESPACE* is not specified when Log4cxx is built,
+the default value for *LOG4CXX_FORMAT_NS* is *fmt*.
+
+Setting *LOG4CXX_FORMAT_NAMESPACE=std* when building Log4cxx
+does not prevent an application from using the {fmt} library.
+An application developer can choose the implementation
+by adding *LOG4CXX_FORMAT_NS=std* or *LOG4CXX_FORMAT_NS=fmt* to the
+[target_compile_definitions](https://cmake.org/cmake/help/latest/command/target_compile_definitions.html)
+command in their CMakeLists.txt.
+If that preprocessor macro is absent,
+the *LOG4CXX_XXXXX_FMT* logging macros will expand
+to the default value of *LOG4CXX_FORMAT_NS* defined when Log4cxx was built.
# Optional Dependencies
@@ -58,12 +78,20 @@ 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_ASYNC | {fmt} | 9+ | Compile/runtime |
https://github.com/fmtlib/fmt |
|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 |
+## Default CMake option values
+
+All the above CMake options default to OFF except for the {fmt} library
options.
+
+If the {fmt} library is found (by *find_package(fmt 7.1 QUIET)*) when Log4cxx
is built,
+the options *ENABLE_FMT_ASYNC* and *ENABLE_FMT_LAYOUT* default to *ON*.
+
## A note on C++ version and Boost
By default, Log4cxx requests C++20 features. This is to
@@ -71,11 +99,11 @@ 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
+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.
+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.
@@ -83,10 +111,10 @@ instead. If you would prefer to use Boost, there are two
options you have:
| Dependency | License |
|------------|---------|
-| APR, APR-util | **Apache License, Version 2.0** |
-| Boost | **Boost License, Version 1.0** |
-| {fmt} | **MIT** |
-| unixodbc | **LGPL** |
-| libesmtp | **LGPL** |
+| 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
+| Mac OS/X Core Foundation | *APSL 2.0* |
\ No newline at end of file
diff --git a/src/site/markdown/macros-influencing-log4cxx.md
b/src/site/markdown/macros-influencing-log4cxx.md
index f85033ff..a84e0add 100644
--- a/src/site/markdown/macros-influencing-log4cxx.md
+++ b/src/site/markdown/macros-influencing-log4cxx.md
@@ -24,8 +24,13 @@ Preprocessor Macros Influencing Log4cxx
{#macros-influencing-log4cxx}
The following macros can be defined in client code to influence how log
messages
are set or not.
-These macros may be set on a per-file basis(in which case they must be before
any
-Log4cxx includes), or they may be set globally via your build system.
+These macros may be set on a per-file basis
+(in which case they must be before any Log4cxx includes),
+or they may be set using your build system,
+for example, by using the
+[target_compile_definitions](https://cmake.org/cmake/help/latest/command/target_compile_definitions.html)
+cmake command.
+
| Macro | Usage |
| ----- | ----- |
