log4cplus

% log4cplus README

Short Description

log4cplus is a simple to use C++23 logging API providing thread--safe, flexible, and arbitrarily granular control over log management and configuration. It is modeled after the Java log4j API.

Latest Project Information

The latest up-to-date information for this project can be found on the GitHub project page or the log4cplus wiki. Please submit bugs, patches, feature requests, and so on on GitHub.

Mission statement

The aim of this project is to develop a log4j-like logging framework for use primarily in C++. One of the major design goals is to avoid huge dependencies (like Boost) in the core functionality and to use standard C++ facilities instead. Where possible, the project takes inspiration from other logging libraries, besides log4j (e.g., from log4net, log4cxx, log4cpp).

Platform support

log4cplus version 3.0 and beyond require C++23. log4cplus has been continuously built and tested by GitHub Actions on these host platforms:

• Ubuntu 24.04 on AMD64 with GCC 14 and on ARM64 with GCC;
• macOS 15 on ARM64 with Apple Clang and LLVM 18;
• Windows Server 2022 on AMD64 and Windows 11 on ARM64 with Visual Studio 2022;
• FreeBSD 13.5, 14.4 and 15.0, plus current OpenBSD, NetBSD and DragonFly BSD runner images, using both CMake and Autotools where supported.

GitHub Actions also performs compile and installation validation for these cross-compiled targets:

• Android API 21 or later with NDK Clang for armeabi-v7a, arm64-v8a, x86 and x86_64. The Android job compiles and links the test suite, validates production installations and links external consumers, but does not execute on an Android device or emulator;
• iOS 15 or later for ARM64 devices and ARM64/x86_64 Simulator targets. The iOS job also creates an unsigned static-library XCFramework. It does not execute the test suite on an iOS device or in Simulator.

Platforms not listed above may still work, but are not continuously validated on the master branch.

The oldest Windows version that is supported by 3.x releases is Windows 10.

The following platforms were supported by the 1.x series of log4cplus. They either do not have a reasonably C++23-capable compiler or have not yet been checked with log4cplus 3.x:

• Minix 3.3.0/i386 with Clang version 3.4 (branches/release_34) with --disable-threads
• Linux/AMD64 with Intel Parallel Studio XE 2015, ICPC version 15.0.1
• OpenSolaris with -library=stlport4
• Solaris with -library=stlport4 and with -library=Cstd.
• Solaris 5.10/Sparc
• MacOS X 10.8
• MacOS X 11.4.2
• HP-UX (hppa2.0w-hp-hpux11.11)
• Haiku R1 Alpha 4.1
• AIX 5.3 with IBM XL C/C++ for AIX

Installation instructions

Generic Autotools installation instructions are in the INSTALL file. The following are log4cplus-specific instructions.

log4cplus uses Git sub-modules. Always use --recurse-submodules option when doing git clone.

Configure script options

--enable-debugging

This option is disabled by default. This option mainly affects GCC builds but it also has some limited effect on non-GCC builds. It turns on debugging information generation, undefines NDEBUG symbol and adds -fstack-check (GCC).

--enable-warnings

This option is enabled by default. It adds platform / compiler dependent warning options to compiler command line.

--enable-so-version

This option is enabled by default. It enables SO version decoration on resulting library file, e.g., the .2.0.0 in liblog4cplus-1.2.so.2.0.0.

--enable-release-version

This option is enabled by default. It enables release version decoration on the resulting library file, e.g., the -1.2 in liblog4cplus-1.2.so.2.0.0.

--enable-symbols-visibility-options

This option is enabled by default. It enables use of compiler and platform specific option for symbols visibility. See also the Visibility page on GCC Wiki.

--enable-profiling

This option is disabled by default. This option adds profiling information generation compiler option -pg to GCC and Sun CC / Solaris Studio builds.

--enable-threads

This option is enabled by default. It turns on detection of necessary compiler and linker flags that enable POSIX threading support.

While this detection usually works well, some platforms still need help with configuration by supplying additional flags to the configure script. One of the known deficiencies is Solaris Studio on Linux. See one of the later notes for details.

--enable-tests

This option is enabled by default. It enables compilation of test executables.

--enable-unit-tests

This option is disabled by default. It enables compilation of unit tests along with their units. These unit tests can then be executed through the unit_tests test executable that is built during compilation.

--enable-implicit-initialization

This option is enabled by default. It enables implicit initialization of log4cplus. When it is turned off, log4cplus has to be explicitly initialized by calling either log4cplus::initialize() or by instantiating log4cplus::Initializer.

--enable-lto

This option is disabled by default. It enables LTO (Link-Time Optimization) builds.

--with-wchar_t-support

This option is enabled by default. When enabled, additional binaries will be built, marked with U suffix in file name and compiled with -DUNICODE=1 flag. In effect, these binaries assume that log4cplus::tchar is wchar_t.

--with-working-locale

This is one of three locale and wchar_t↔char conversion related options. It is disabled by default.

It is known to work well with GCC on Linux. Other platforms generally have lesser locale support in their implementations of the C++ standard library. It is known not to work well on any BSDs.

See also docs/unicode.txt.

--with-working-c-locale

This is the second of the wchar_t↔char conversion-related options. It is disabled by default.

It is known to work well on most Unix--like platforms, including recent Cygwin.

--with-iconv

This is the third of the wchar_t↔char conversion-related options. It is disabled by default.

The conversion using iconv() function always uses "UTF-8" and "WCHAR_T" as source/target encoding. It is known to work well on platforms with GNU iconv. Different implementations of iconv() might not support "WCHAR_T" encoding selector.

Either the system-provided iconv() or the library-provided libiconv() is detected and accepted. Both SUSv3 and GNU iconv() function signatures are accepted.

--with-qt

This option is disabled by default. It enables compilation of a separate shared library (liblog4cplusqt4debugappender) that implements Qt4DebugAppender. It requires Qt4 and pkg-config to be installed.

--with-qt5

This option is disabled by default. It enables compilation of a separate shared library (liblog4cplusqt5debugappender) that implements Qt5DebugAppender. It requires Qt5 and pkg-config to be available.

Notes

Compilation

On Unix--like platforms, log4cplus can be compiled using either the Autotools-based build system or the CMake build system. The Autotools-based build system is considered to be primary for Unix--like platforms.

On Windows, the primary build system is Visual Studio solution and projects (msvc14/log4cplus.sln), currently tested with Visual Studio 2022.

Apple embedded platforms, including iOS and iOS Simulator, are supported using CMake 3.20 or later with the Xcode generator.

Android is supported using CMake 3.20 or later with the toolchain file supplied by the Android NDK.

MinGW is supported by the Autotools-based build system. The CMake build system is supported as well, and it should be used to compile log4cplus with older versions of Visual Studio or with less common compiler suites (e.g., Embarcadero, Code::Blocks, etc.).

Cygwin

Cygwin 2.5.x has a problem^pr64697 linking binaries that use language-level thread-local storage and share thread-local variables across translation units. To avoid the issue, language-level thread-local storage is not used on Cygwin and traditional POSIX thread-local storage is used instead.

MinGW and MSVCRT version

log4cplus can use functions like _vsnprintf_s() (Microsoft's secure version of vsnprintf()). MinGW toolchains (by default) link to the system MSVCRT.DLL. Unfortunately, older systems, like Windows XP, ship with MSVCRT.DLL that lacks these functions. It is possible to compile log4cplus with MinGW toolchains but without using Microsoft's secure functions by defining __MSVCRT_VERSION__ to a value less than 0x900 and vice versa.

$ ../configure CPPFLAGS="-D__MSVCRT_VERSION__=0x700"

Windows and Visual Studio

log4cplus uses C++11 thread and synchronization facilities. The synchronization facilities are implemented in Visual Studio C++ standard library in a way that utilizes global variables. Therefore it is impossible (due to "static initialization order fiasco") to use them outside main(). This issue manifests as a deadlock on exit during destruction of log4cplus' thread pool.

To overcome this limitation,

• always use log4cplus::Initializer initializer; as the first thing in main();

• never try to log from static/global objects constructors;

• never try to log from static/global object destructors.

Defining the log4cplus::Initializer instance as the first thing in main() ensures that log4cplus is initialized. More importantly, it ensures that log4cplus shuts down before the execution leaves the main() function. log4cplus will try to automatically initialize at process startup and/or on DLL load, and will not tear down until all log4cplus:Initializer instances are destroyed.

Windows and file Appenders

On Windows, file-based appenders use log4cplus' Win32-backed file stream instead of the standard C++ file streams. The Win32-backed stream opens files using CreateFileW() with read, write, and delete sharing. This allows log files to be renamed or deleted while they are open by another process and lets rolling file appenders roll over files in that situation. It stores file contents as UTF-8.

Older log4cplus releases used the standard C++ file streams on Windows. Those streams did not open the underlying Win32 file HANDLE with FILE_SHARE_DELETE, which could make rollover fail with error code 13 if another process still had the log file open. This was tracked as bug #167 on SourceForge.

Windows and TLS

log4cplus uses thread--local storage (TLS) for NDC, MDC and to optimize use of some temporary objects. On Windows there are two ways to get TLS:

1. using TlsAlloc(), etc., functions
2. using __declspec(thread)

While method (2) generates faster code, it has [some limitations prior to Windows Vista][tlsvista]. If log4cplus.dll is loaded at run time using LoadLibrary() (or as a dependency of such loaded library), then accessing __declspec(thread) variables can cause general protection fault (GPF