% log4cplus README
Short Description
log4cplus is a simple to use C++ 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 at log4cplus SourceForge project pages or log4cplus wiki on SourceForge. Please submit bugs, patches, feature requests, etc., there.
Mission statement
The aim of this project is to develop log4j--like logging framework for use in (primarily) 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, beside from log4j (e.g., from log4net, log4cxx, log4cpp).
Platform support
log4cplus version 2.0 and beyond require C++11. log4cplus has been ported to and tested on the following platforms:
- Linux/AMD64 with GCC 4.8.1 (Ubuntu/Linaro 4.8.1-10ubuntu9)
- Windows/AMD64 with GCC version 4.8.2 (x86_64-posix-seh-rev3, Built by MinGW-W64 project) using CMake build system
The testing on the above listed platforms has been done at some point in time with some version of source. Continuous testing is done only on Linux platform offered by Travis CI service.
The following platforms were supported by the 1.x series of log4cplus. They either do not have a reasonable C++11 capable compiler or have not been checked with log4cplus 2.x, yet:
- Windows 7 with MS Visual Studio 2013
- Linux/AMD64 with Clang version 3.2-1~exp9ubuntu1 (tags/RELEASE_32/final) (based on LLVM 3.2)
- Linux/AMD64 with Intel(R) C++ Intel(R) 64 Compiler XE for applications running on Intel(R) 64, Version 12.1 Build 20120410
- FreeBSD/AMD64
- OpenSolaris with
-library=stlport4
- Solaris with
-library=stlport4
and with-library=Cstd
. - Solaris 5.10/Sparc
- NetBSD 6.0/AMD64
- OpenBSD 5.2/AMD64
- 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
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 know deficiencies is Solaris Studio on
Linux. See one of the later note for details.
--with-working-locale
This is one of three locale and wchar_t
char
conversion related
options. It is disabled by default.
It is know 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 second of 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 third of 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 system provided iconv()
or library provided libiconv()
are
detected and accepted. Also 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.
Notes
Compilation
On Unix--like platforms, log4cplus can be compiled using either autotools based build system or using 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 2010 solution
and projects (msvc10/log4cplus.sln
). This solution and associated
project files should update just fine to Visual Studio 2012 out of the
box. See also scripts/msvc10_to_msvc11.cmd
and
scripts/msvc10_to_msvc12.cmd
helper scripts that create
msvc11/log4cplus.sln
and msvc12/log4cplus.sln
respectively when
invoked on msvc10/log4cplus.sln
from source root directory.
MinGW is supported by autotools based build system. 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/MinGW
Some version of GCC (3.4.x and probably some of 4.x series too) on Windows (both MinGW and Cygwin) produces lots of warnings of the form:
warning: inline function 'void foo()' is declared as dllimport: attribute ignored
This can be worked around by adding -Wno-attributes
option to GCC
command. Unfortunately, not all affected version of GCC have this
option.
MinGW and MSVCRT version
log4cplus can use functions like _vsnprintf_s()
(Microsoft's
secure version of vsnprintf()
). MinGW tool--chains (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 tool--chains but without using
Microsoft's secure functions by defining __MSVCRT_VERSION__
to value
less than 0x900
and vice versa.
$ ../configure CPPFLAGS="-D__MSVCRT_VERSION__=0x700"
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:
- using
TlsAlloc()
, etc., functions - using
__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.
Android, TLS and CMake
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.
Threads and signals
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
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
AIX reentrancy problem
There appears to be a reentracy 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.
Solaris / SunOS
Some older version of this operating system might have problems
linking log4cplus due to missing __tls_get_addr
in their
unpatched state.
Solaris Studio
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.
Solaris Studio on GNU/Linux
The autotools and our configure.ac
combo does not handle Solaris
Studio compiler on Linux well enough and needs a little help with
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"
aCC
HP-UX with It is necessary to turn on C++98 mode of aCC
by providing the -AA
flag:
$ ../configure --enable-threads=yes CXXFLAGS="-AA"
aCC
on IA64
HP-UX with There 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
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 version 4, please run 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 Haiku ticket #8368.
Qt4 / Win32 / MSVC
In order to use log4cplus in Qt4 programs it is necessary to set
following option: Treat WChar_t As Built in Type: No (/Zc:wchar_t-)
Set this option for log4cplus project and Qt4DebugAppender
project
in MS Visual Studio. Remember to use Unicode versions of log4cplus
libraries with Qt. It is also necessary to make clear distinction
between debug and release builds of Qt project and log4cplus. Do
not use log4cplus release library with debug version of Qt program
and vice versa.
For registering Qt4DebugAppender library at runtime, call this
function: log4cplus::Qt4DebugAppender::registerAppender()
Add these lines to qmake project file for using log4cplus and
Qt4DebugAppender
:
INCLUDEPATH += C:\log4cplus\include
win32 {
CONFIG(debug, debug|release) {
LIBS += -LC:\log4cplus\msvc10\Win32\bin.Debug_Unicode -llog4cplusUD
LIBS += -LC:\log4cplus\msvc10\Win32\bin.Debug_Unicode -llog4cplus-Qt4DebugAppender
} else {
LIBS += -LC:\log4cplus\msvc10\Win32\bin.Release_Unicode -llog4cplusU
LIBS += -LC:\log4cplus\msvc10\Win32\bin.Release_Unicode -llog4cplus-Qt4DebugAppender
}
}
Qt / GCC
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
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
log4cplus build for iOS is based on iOS.cmake
toolchain file, originally
taken from https://code.google.com/p/ios-cmake/.
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"
LOG4CPLUS_*_FMT()
and UNICODE
Beware, 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 conveniently by printing
wchar_t
string when used with wprintf()
and char
strings when
used with printf()
. On the other hand, Unix--like platforms keeps
the meaning of printing char
strings when used with both wprintf()
and printf()
. It is necessary to use %ls
(C99) specifier or %S
(SUSv2) specifier to print wchar_t
strings on Unix--like platforms.
The common ground for both platforms appears to be use of %ls
and
wchar_t
string to print strings with unmodified formatting string
argument on both Unix--like platforms and Windows. The conversion of
wchar_t
back to char
then depends on C locale.
Unsupported compilers
log4cplus does not support too old or broken C++ compilers:
- Visual C++ prior to 7.1
- GCC prior to 3.2
- Older versions of Borland/CodeGear/Embarcadero C++ compilers
Unsupported platforms
log4cplus requires some minimal set of C and/or C++ library functions. Some systems/platforms fail to provide these functions and thus log4cplus cannot be supported there:
- Windows CE -- missing implementations of
<time.h>
functions
License
This library is licensed under the Apache Public License 2.0 and two clause BSD license. Please read the included LICENSE file for details.
Contributions
log4cplus (bug tracker, files, wiki) is hosted on SourceForge, except for log4cplus source, which is hosted on Github. This allows the project to integrate with Travis CI service offered by Github.
Patches
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 or a patch file attached to a ticket in Bugs tracker or sent to log4cplus-devel mailing list. Unless it is obvious, always state what branch or release tarball is your patch based upon.
Formatting
Please use common sense. Follow the style of surrounding code. You can use the following Emacs style that is based on Microsoft's style as a guide line:
;; 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 . +))))