% 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 ported to and tested on the following platforms:

• Linux/AMD64 with GCC version 13.2.0 (Ubuntu 13.2.0-23ubuntu4)
• Linux/AMD64 with Clang version 18.1.3 (18.1.3-1ubuntu1)
• Windows/AMD64 with GCC version 4.8.2 (x86_64-posix-seh-rev3, Built by MinGW-W64 project) using CMake build system
• Windows/AMD64 with GCC version 4.9.2 (tdm64-1) using CMake build system
• Windows 7 with MS Visual Studio 2015
• OpenBSD 5.6/AMD64 with GCC version 4.9.0
• FreeBSD 10.1/i386 with Clang version 3.4.1 (tags/RELEASE_34/dot1-final 208032)
• NetBSD 6.1.5/AMD64 with GCC version 4.9.1
• DragonflyBSD 4.0.1/AMD64 with GCC version 4.9.3 20141126 (prerelease) (FreeBSD Ports Collection)
• OpenIndiana Hipster 2016.10 with GCC version 4.9.4

Testing on the above-listed platforms was done at some point in time with some version of the source. Continuous testing is performed only on the Linux platform offered by the [Travis CI][11] service.

The oldest Windows version that is supported by 2.x releases is Windows Vista.

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 2015 solution and projects (msvc14/log4cplus.sln).

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 [log4