log4cplus is a simple to use C++ logging API providing thread-safe, flexible, and arbitrarily granular control over log management and configuration. It is modelled after the Java log4j API.
% log4cplus README
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.
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.
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).
log4cplus version 3.0 and beyond require C++23. log4cplus has been
ported to and tested on the following platforms:
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:
--disable-threads-library=stlport4-library=stlport4 and with -library=Cstd.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.
--enable-debuggingThis 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-warningsThis option is enabled by default. It adds platform / compiler
dependent warning options to compiler command line.
--enable-so-versionThis 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-versionThis 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-optionsThis 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-profilingThis option is disabled by default. This option adds profiling
information generation compiler option -pg to GCC and Sun CC /
Solaris Studio builds.
--enable-threadsThis 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-testsThis option is enabled by default. It enables compilation of test executables.
--enable-unit-testsThis 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-initializationThis 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-ltoThis option is disabled by default. It enables LTO (Link-Time Optimization)
builds.
--with-wchar_t-supportThis 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-localeThis 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-localeThis 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-iconvThis 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-qtThis 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-qt5This 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.
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 2.5.x has a problem[1] 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.
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"
log4cplus uses C11 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.
On Windows, the standard C++ file streams open files in a way that the
underlying Win32 file HANDLE is not opened with the FILE_SHARE_DELETE
flag. This flag, besides shared delete, allows renaming files that have
handles open to them. This issue manifests as error code 13 when the file
needs to be rolled over while it is still open by another process.
This is also bug #167 on
SourceForge.
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:
TlsAlloc(), etc., functions__declspec(thread)While method (2) generates faster code, it has
some limitations prior to Windows Vista. 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) errors. This is because Windows prior to Windows Vista do not
extend the TLS for libraries loaded at run time using LoadLibrary().
To allow using the best available method, log4cplus enables the
method (2) by checking _WIN32_WINNT >= 0x0600 condition, when
compiling log4cplus targeted to Windows Vista or later.
If you are linking your application with the DLL variant of log4cplus, define
LOG4CPLUS_BUILD_DLL preprocessor symbol. This changes definition of
LOG4CPLUS_EXPORT symbol to __declspec(dllimport).
log4cplus uses thread–local storage (TLS, see “Windows and TLS” for
details). On the Android platform, when log4cplus is being compiled using
the android/android.toolchain.cmake, you might get errors featuring the
__emutls symbol:
global-init.cxx:268:46: error: log4cplus::internal::__emutls_t._ZN9log4cplus8internal3ptdE causes a section type conflict with log4cplus::internal::ptd
To work around this issue, invoke CMake with
-DANDROID_FUNCTION_LEVEL_LINKING:BOOL=OFF option.
log4cplus is not safe to be used from asynchronous signals’
handlers. This is a property of most threaded programmes in general.
If you are going to use log4cplus in threaded application and if you
want to use log4cplus from signal handlers then your only option is
to block signals in all threads but one that will handle all signals.
On POSIX platforms, this is possible using the sigwait() call.
log4cplus enables this approach by blocking all signals in any
threads created through its threads helpers.
IBM’s XL C/C++ compiler executable has many variants. To compile
log4cplus with threading support specify one of the compiler
variants that support threading using the CXX variable on
configure script command line. E.g.:
$ ../configure --enable-threads CXX=xlC_r
There appears to be a reentrancy problem with AIX 5.3 and xlC 8 which
can result into a deadlock condition in some circumstances. It is
unknown whether the problem manifests with other versions of either
the OS or the compiler, too. The problem was initially reported in a
bug report #103.
The core of the problem is that IBM’s/xlC’s standard C++ IOStreams
implementation uses global non recursive lock to protect some of its
state. The application in the bug report was trying to do logging
using log4cplus from inside overflow() member function of a class
derived from std::streambuf class. log4cplus itself uses
std::ostringstream. This resulted into an attempt to recursively
lock the global non recursive lock and a deadlock.
Some older version of this operating system might have problems
linking log4cplus due to missing __tls_get_addr in their
unpatched state.
Solaris Studio compilers’ default standard C++ library is very
non-standard. It seems that it is not conforming enough in, e.g., Sun
C++ 5.12 Linux_i386 2011/11/16 (missing std::time_t, etc.), but it
works well enough on Solaris with Sun C++ 5.8 2005/10/13. Thus
log4cplus adds -library=stlport4 to the CXXFLAGS environment
variable, unless a switch matching -library=(stlport4|stdcxx4|Cstd)
is already present there. If you want to override the default
supplied by log4cplus, just set it into CXXFLAGS on configure
script command line.
Solaris Studio supports the __func__ symbol which can be used by
log4cplus to record function name in logged events. To enable this
feature, add -features=extensions switch to CXXFLAGS for
configure script. Subsequently, you will have to add this switch to
your application’s build flags as well.
The Autotools and our configure.ac combination do not handle the Solaris
Studio compiler on Linux well enough and need a little help with the
configuration of POSIX threads:
$ COMMON_FLAGS="-L/lib/x86_64-linux-gnu/ \
-L/usr/lib/x86_64-linux-gnu/ -mt=yes -O"
$ ../configure --enable-threads=yes \
CC=/opt/solarisstudio12.3/bin/cc \
CXX=/opt/solarisstudio12.3/bin/CC \
CFLAGS="$COMMON_FLAGS" \
CXXFLAGS="$COMMON_FLAGS" \
LDFLAGS="-lpthread"
aCCIt is necessary to turn on C++98 mode of aCC by providing the -AA
flag:
$ ../configure --enable-threads=yes CXXFLAGS="-AA"
aCC on IA64There is a problem on IA64 HP-UX with aCC (HP C/aC++ B3910B
A.06.20). The problem manifests as
unsatisfied symbols during linking of loggingserver:
ld: Unsatisfied symbol "virtual table of loggingserver::ClientThread" in file loggingserver.o
The problem appears to be a deficiency in aCC and its support of
__declspec(dllexport). To work around this issue, add
--disable-symbols-visibility-options to configure script command
line:
$ ../configure --disable-symbols-visibility-options \
--enable-threads=yes CXXFLAGS="-AA"
Haiku is supported with GCC 4+. The default GCC version in Haiku is
set to version 2 (based on GCC 2.95.x). To change the default GCC
version to 4, please run the setgcc gcc4 command. This is to
avoid linking errors like this:
main.cpp:(.text.startup+0x54a): undefined reference to `_Unwind_Resume'
Running the command switches the current GCC version to version 4.
This change is permanent and global. See also the Haiku ticket
#8368.
In order to use log4cplus in Qt4 programs it is necessary to set the
following option: Treat WChar_t As Built-in Type: No (/Zc:wchar_t-)
Set this option for the log4cplus project and the Qt4DebugAppender
project in MS Visual Studio. Remember to use the Unicode versions of
log4cplus libraries with Qt. It is also necessary to make a clear
distinction between debug and release builds of the Qt project and
log4cplus. Do not use the log4cplus release library with the debug
version of a Qt program and vice versa.
To register the Qt4DebugAppender library at runtime, call this
function: log4cplus::Qt4DebugAppender::registerAppender()
Add these lines to the qmake project file to use log4cplus and
Qt4DebugAppender:
INCLUDEPATH += C:\log4cplus\include
win32 {
CONFIG(debug, debug|release) {
LIBS += -LC:\log4cplus\msvc14\Win32\bin.Debug_Unicode -llog4cplusUD
LIBS += -LC:\log4cplus\msvc14\Win32\bin.Debug_Unicode -llog4cplus-Qt4DebugAppender
} else {
LIBS += -LC:\log4cplus\msvc14\Win32\bin.Release_Unicode -llog4cplusU
LIBS += -LC:\log4cplus\msvc14\Win32\bin.Release_Unicode -llog4cplus-Qt4DebugAppender
}
}
You might encounter the following error during compilation with
--with-qt option:
qglobal.h:943: error: ISO C++ does not support 'long long'
This is caused by -pedantic option that log4cplus adds to
CXXFLAGS when compiling with GCC. To work around this issue, add
-Wno-long-long GCC option to CXXFLAGS.
OpenBSD 5.2 and earlier have a bug in wcsftime() function in
handling of %% and %N where N is not a supported formatter. This
is fixed in OpenBSD 5.3 and later. This shows as failing
timeformat_test when log4cplus is compiled with -DUNICODE in
CXXFLAGS.
iOS support is based on CMake build. Use the scripts in iOS directory. The
iOS.cmake toolchain file was originally taken from ios-cmake project.
To build the library for iOS, being in current folder, perform the steps
below. For ARMv7 architecture:
$ ./scripts/cmake_ios_armv7.sh
$ cmake --build ./build_armv7 --config "Release"
$ cmake --build ./build_armv7 --config "Debug"
For i386 architecture:
$ ./scripts/cmake_ios_i386.sh
$ cmake --build ./build_i386 --config "Release"
$ cmake --build ./build_i386 --config "Debug"
Some versions of the iOS and/or its SDK have problems with thread-local storage
(TLS) and getting through CMake’s environment detection phase. To work around
these issues, make these changes:
Edit the iOS.cmake file and add these two lines.
set (CMAKE_CXX_COMPILER_WORKS TRUE)
set (CMAKE_C_COMPILER_WORKS TRUE)
Add these lines, customizing them accordingly:
set(MACOSX_BUNDLE_GUI_IDENTIFIER com.example)
set(CMAKE_MACOSX_BUNDLE YES)
set(CMAKE_XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer")
set(IPHONEOS_ARCHS arm64)
If you have issues with TLS, also comment out these lines:
set(LOG4CPLUS_HAVE_TLS_SUPPORT 1)
set(LOG4CPLUS_THREAD_LOCAL_VAR "__thread")
LOG4CPLUS_*_FMT() and UNICODEBeware, the %s specifier does not work the same way on Unix–like
platforms as it does on Windows with Visual Studio. With Visual Studio
the %s specifier changes its meaning by printing a wchar_t string
when used with wprintf() and a char string when used with
printf(). On the other hand, Unix-like platforms keep the meaning of
printing char strings when used with both wprintf() and
printf(). It is necessary to use the %ls (C99) specifier or the %S
(SUSv2) specifier to print wchar_t strings on Unix-like platforms.
The common ground for both platforms appears to be using %ls and a
wchar_t string to print strings with an unmodified format string on
both Unix-like platforms and Windows. The conversion of wchar_t back
to char then depends on the C locale.
log4cplus does not support too old or broken C++ compilers. Since log4cplus
version 3.0.0, it means it does not support any platform or compiler without
decent C++23 support.
For successful resolution of reported bugs, it is necessary to provide enough information:
configure script parameters and environmentconfig.log and defines.hxx files.Release, Debug,RelWithDebInfo) and non–default CMAKE_* variables values.Release,Release_Unicode, Debug, Debug_Unicode) and Visual Studio version.log4cplus client application
log4cplus.lib, log4cplusUSD.lib, liblog4cplus.dll.a, etc., onwchar_t or not?This library is licensed under the Apache Public License 2.0 and the
two-clause BSD license. Please read the included LICENSE file for
details.
log4cplus (bug tracker, files, wiki) is hosted on GitHub. See also the
Contributions
topic on the wiki.
Anybody can contribute to log4cplus development.
If you are contributing a source code change, use a reasonable
form: a merge request of a Git branch.
Please use common sense. Follow the style of the surrounding code. You can
use the following Emacs style, which is based on Microsoft’s style, as a
guideline:
;; Custom MS like indentation style.
(c-add-style "microsoft"
'("stroustrup"
(c-offsets-alist
(innamespace . -)
(inline-open . 0)
(inher-cont . c-lineup-multi-inher)
(arglist-cont-nonempty . +)
(template-args-cont . +))))
log4cplus supports multiple build systems (GNU Autoconf/Automake/Libtool aka
Autotools, CMake and Visual Studio solution and project files).
Autotools is considered the primary build system on Unix–like
platforms. However, CMake should still be usable on Unix–like platforms as
well.
On Windows, it depends on the compiler and toolchain that you want to use. When
using Visual Studio, use Visual Studio solution and project files. However,
the CMake build system should still work and produce useful results. When using
some form of MinGW64 toolchain, the CMake build system is considered primary
and the Autotools-based build system is unsupported. Use the MinGW Makefiles
option and build with mingw-make (or similar). The MSYS Makefiles option is
untested and unsupported.
The Makefile.am files for this build system are hand-written. Some of them,
however, are generated from Makefile.am.tpl and Makefile.am.def by
GNU Autogen. This is to make adding new files to the source easier.
To regenerate Makefile.am files, configure script, testsuite script or
any other part of the Autotools build system, use the scripts/doautoreconf.sh
script from the source root directory. It will invoke all the necessary tools in
the correct order.
log4cplus closely follows Autoconf’s, Automake’s and Libtool’s development
and its master branch files are always generated using the latest available
version of the tools.