Log for C++

Introduction

Log4cpp is library of C++ classes for flexible logging to files, syslog, IDSA and other destinations. It is modeled after the Log4j Java library, staying as close to their API as is reasonable.

Download

Sources are available from SourceForges download page.
We do not supply binaries yet, because of the numerous incompatible ABIs (e.g. g++ 2.95 vs 2.96 vs 3.0 vs 3.2) and different package formats.
An older version of log4cpp (0.2.5) is available in Debian stable, see http://packages.debian.org/stable/libs/liblog4cpp0.html.
FreeBSD users can find log4cpp (0.2.7) in the ports collection, see http://www.freebsd.org/ports/devel.html
The people of the Datagrid Project Central Repository have published the source and binary RPMs they use theirselves. These are for RedHat Linux 6.2.
Log4cpp includes support for building RPMs, so building your own from the source tar-ball is as simple as

rpm -ta log4cpp-x.y.z.tar.gz

Building Log4cpp

As of version 0.2.0 log4cpp can be build using autoconf on platforms that support it. Simply do:

./configure
make
make check
make install

This will install log4cpp under /usr/local. To install in another localation specify --prefix=<location> when running configure.

Options for ./configure

--with-idsa

Include support for logging to IDSA (http://jade.cs.uct.ac.za/idsa/index.html). This will give you an IdsaAppender Appender class.

--with-omnithreads[=<path-to-omniORB>]

Enable multi-threading support using omniORB4's omniThreads MT abstraction library (http://www.omniorb.org). configure expects the omnithread header files to reside in <path-to-omniORB>/include and the library in <path-to-omniORB</lib, i.e. not in a platform specific subdirectory. Create symlinks where necessary.
NB. omniORB4 is required: omniORB3 will not suffice as it lacks sufficient support for thread specific data. At the moment (August 2002) omniORB4 is in beta, however most parts and specifically the threading library appear to be quite stable.

--with-pthreads

Enable multi-threading support using the 'pthread' POSIX threads library. This option is mutually exclusive with --with-omnithreads.

--enable-doxyen

Enables generation of API documentation by Dimitri van Heeschs Doxygen tool (http://www.doxygen.org/). Defaults to yes if doxygen can be found in the search path.

--enable-html-docs

If doxygen is enabled, have it generate HTML formatted documentation.

--enable-latex-docs

If doxygen is enabled, have it generate LaTeX formatted documentation.

--enable-dot

Let Doxygen use the 'dot' tool of GraphViz (http://www.graphviz.org) todraw its graphs.

Build notes for specific platforms

*nix - g++ compiler

Log4cpp should build whitout modification on any decent *nix system with g++ and GNU make. The primary development platform is RedHat Linux 7.3, which has g++ 2.96-rh, but the aim is to be compatible with from g++ 2.95 and up. When g++ 3.x has been widely adopted we may drop support for older g++ versions.

Solaris - Sun CC compiler

Compilation with Suns CC compiler requires setting some enviroment variables. Also static libraries appear not to work. In short do:

CC=CC CXX=CC LD="CC -KPIC" ./configure --disable-static

Win32 - MSVC++ 6

Use the workspace and project files in subdirectory msvc6. You may need to adjust include/log4cpp/config-win32.h and the project files to your particular needs.

Win32 - MSVC++ 5

Building log4cpp with MSVC++ 5 is not supported and will not be, unless someone can find a way to do so without mutilating the source code.

Win32 - Borland C++ Builder 5

Use the project and make files in subdirectory bcb5.

Win32 - Cygwin

Use './configure; make; make install'.
Be warned that there have been very few success or failure reports for this platform, so either it works very smoothly or noone actively uses log4cpp with Cygwin :-)

OpenVMS

Edit include/log4cpp/config-openvms.h if you need different settings.
This has been tested on OpenVMS Alpha v7.3 and Compaq C++ V6.3-020 only.

1) Copy the src and include directory (including all its contents and subdirectories) onto your OpenVMS system.

2) Compile each source file (*.CPP and *.C in the src directory) one by one by the following command,

cxx /include=("/a1\$dkb0/user/tony/project/log4cpp/include") /define=(__USE_STD_IOSTREAM,__OPENVMS__) /repository=a1$dkb0:[user.tony.project.log4cpp.repository] APPENDER.CPP
cxx /include=("/a1\$dkb0/user/tony/project/log4cpp/include") /define=(__USE_STD_IOSTREAM,__OPENVMS__) /repository=a1$dkb0:[user.tony.project.log4cpp.repository] APPENDERSKELETON.CPP

...etc
Please substitute a correct path for your include directory. A unix-style directory name is requied in the /include parameter. In this example, the pathis A1$DKBO:[USER.TONY.PROJECT.LOG4CPP.INCLUDE]
A repository directory is also specified here as A1$DKB0:[USER.TONY.PROJECT.LOG4CPP.REPOSITORY].

3) Create a static library, LOG4CPP.OLB

lib/create log4cpp

4) Put all compiled OBJ files into the LOG4CPP.OLB

lib/insert log4cpp appender
lib/insert log4cpp appenderskeleton

...etc

5) Link a program with log4cpp.olb. e.g:

cxx /include=("/a1\$dkb0/user/tony/project/log4cpp/include") /define=(__USE_STD_IOSTREAM,__OPENVMS__) testlog4cpp.cxx

cxxlink /repository=a1$dkb0:[user.tony.project.log4cpp.repository] testlog4cpp,log4cpp/library

Releases

WARNING: releases from the development branch are a 'work in progress' and may fail to build, crash or redecorate your desktop.

0.3.2rc2 - development branch (12 August 2002)

Added support for POSIX threads.

Added PropertyConfigurator.

Rearranged documentation.

Fixed various bugs.

0.3.2rc1 - development branch (19 June 2002)

Support for Win32 threads added.

Added NTEventLogAppender.

Added Win32DebugAppender.

Fixed NDC context problem if depth > 2.

Added aclocal support.

0.3.1 - development branch (4 April 2002)

Added RollingFileAppender class.

Fixed bug #572467: invalidated iterator usage.

Fixed bug #527475: format string bug.

Fixed bug #530332: missing 'std::' specifiers.

Handled feature requests #536668, #527760, #527381.

0.3.0 - development branch (18 Februari 2002)

Added experimental support for multi threaded applications. This implementation uses omniORB4s threading library. Other threading libraries, such as Boosts, may be used as well, but this has not been implemented yet.

0.2.7 - stable branch (27 Januari 2002)

Support for multiple Appenders per Category added (feature request #501360).

Fixed variable scope bug in SyslogAppender (bug #499315)

Fixed memory leak in SyslogAppender and RemoteSyslogAppender (bug #499524)

Fixed compile problem in Filter (bug #)

Fixed config file parse problem in SimpleConfigurator (bug #500766)

Added methods for logging at FATAL level (bug #504314)

Fixed Win32 compile problem (bug #506907)

0.2.6 (11 December 2001)

Preliminary support for OpenVMS added.

PatternLayout, SimpleConfigurator and RemoteSyslogAppender added.

0.2.5 (11 June 2001)

Inclusion of support for Borland C++ Builder.

Library version 1.0.0: this release is not binary compatible with previous ones. (Version update should have been done in 0.2.4).

0.2.2 (04 March 2001)

Inclusion of Win32 platform (MSVC++ 6.0)

0.2.1 (15 Februari 2001)

license change to LGPL.

0.2.0 (10 December 2000)

log4cpp now uses autoconf and automake.

Documentation

API Documentation generated by Doxygen can be found here.
The Solaris Developer Connection features an article by Mo Budlon on using log4cpp 0.2.x, called 'Logging and Tracing in C++ Simplified'. Recommended reading if you trying to figure out how to use log4cpp!

FAQ

1. GENERAL

1.1. What is Log for C++?

Log for C++ is a library of C++ classes for flexible logging to files, syslog and other destinations. It is modeled after the Log for Java library (http://jakarta.apache.org/log4j/), staying as close to their API as is reasonable.

1.2. How is Log for C++ related to Log4j? Is it a straight port?

Log for C++ strives to supply a similar interface for logging in C++ as Log4j provides in Java. However the implementation is not a translation of the Java code. So in that sense it is not a 'port' of Log4j. Of course Log for C++ does owe many of its concepts to log4j.

1.3. What is the name of this project, 'Log for C++' or 'log4cpp'?

The 'official' long name of the project is 'Log for C++', but in practice, the short name, 'log4cpp' has proven more convinient.

1.4. Under which license is Log for C++ available?

As of version 0.2.1 Log for C++ is released under the GNU Lesser General Public License (LGPL). Versions before that have been released under the GPL. See the license discussion on the forum at SourceForge for the motivations behind switching from GPL to LGPL.

1.5. Our legal department doesn't like the LGPL, can you release Log for C++ under license XYZ?

No.
Long answer: Technically it may be possible if every contributor agrees, which due to their growing number has become increasingly difficult. But even if that could be overcome it will not happen.
Of course the LGPL does grant you the opportunity to choose the GPL instead of the LGPL, but I bet XYZ != GPL.

2. COMPILATION AND INSTALLATION

3. USAGE

3.1. I've succesfully compiled log4cpp, now how do I use this stuff?

For some small examples using log4cpp, see the 'tests' subdirectory. Also see the documentation section for a pointer for API documentation and more usage information.

3.2. Is log4cpp thread-safe?

4. PROBLEMS AND ERROR MESSAGES

4.1. I get 'Naming collision for 'ERROR' detected. Please read the FAQ for a workaround.'

This is caused by the rudeness of some platforms, which mutilate the namespace with some blunt #defines. To be more precise, the Win32 API includes #defines of 'ERROR' and 'DEBUG'. Since the preprocessor is unaware of C++ naming scopes this results in reserving the words ERROR and DEBUG litterally everywhere. In particular this conflicts with log4cpp::Prioritiy::ERROR and log4cpp::Priority::DEBUG. These latter two names come from log4j, so they are not something we made up ourselves.
They Win32 authors should not have rudelessly claimed these generic names through the preprocessor. There are much better alternatives:

1. If they use it as an integer constant, declare it using a language construct. Either 'enum {ERROR=1};' or 'static const int ERROR=1;' would do fine.
2. Use a less generic name like WIN32API_ERROR to make naming conflicts less likely
3. In case they use it as a flag for conditional compilation, use '#define DEBUG DEBUG' and '#if defined(DEBUG)'. In that case the preprocessor would simply replace all occurrences of 'DEBUG' in the source code with 'DEBUG', in effect leaving everything intact.

Of course the proper solution would be if the offending party would use one of the above methods, but we could have to wait some time for this to actually happen. As an alternative log4cpp can workaround these #defines. The workaround code is enabled by doing #define LOG4CPP_FIX_ERROR_COLLISION 1 before #including any log4cpp header files and after #including all platform headers. For Win32 platforms this #define has already been included in log4cpp/config-win32.h.

Once log4cpp has been updated to the log4j 1.2 API we can get rid of this problem by adopting the new names for log levels.

4.2. I am trying to compile/link the log4cpp package using the SunWorkshop compiler (CC) on a Solaris 7 machine. The library builds, but the testmain code fails to link properly.

A proper solution for this problem has not been found yet (suggestions are welcome), but James Emery reported success with the following workaround:

• Disable building of the static library
• Change the linker from /usr/ucb/ld to CC and enable 'place independent code' (pic).

In short, configure with:

export LD="CC -Kpic" && ./configure --disable-static

4.3. ./configure fails to detect 'snprintf()' on platform XYZ.

./configure does not just check for the presence of a snprintf() function but for C99 compliancy as well. In particular, snprintf() should strictly honour the 'string size' parameter to avoid potential buffer overflow problems. log4cpp falls back to an alternative snprintf() implementation if the OS does not provide a correct one.

Status

As of version 0.3.0 log4cpp has a separate 'stable' and 'development' branches. Releases x.y.z where y is even are considered stable and those where y is odd are experimental (which means that some or all features may be broken).

The latest stable release 0.2.7. New releases of 0.2.x are for bug fixes only, new features will go into 0.3.x and eventually 0.4.x.

People

Coding on Log4cpp was initiated by me (Bastiaan Bakker) late 2000. Since then other people have joined the project or contributed code:

Cedric Le Goater <cedric(at)legoater.com>	autoconf setup, various improvements
Marc Welz <marc(at)jade.cs.uct.ac.za>	IdsaAppender
Lynn Owen <opl(at)agoby.com>	MSVC++ support
Steve Ostlind <s.ostlind(at)pentasafe.com>	MSVC++ support, various fixes
Marcel Harkema <marcel(at)debian.org>	Debian packaging
Uwe Jäger <jaeger(at)varial.de>	Borland C++ Builder support
Walter Stroebel <walter.stroebel(at)lifeline.nl>	RemoteSyslogAppender
Glen Scott <glen_s(at)yahoo.com>	PatternLayout, SimpleConfigurator
Tony Cheung <dragonman(at)asiayeah.com>	OpenVMS support
Alex Tapaccos <ATapaccos(at)redfig.com>	DailyRollingFileAppender
Brendan B. Boerner <bboerner(at)texas.net>	Multiple Appender support for Categories
Paulo Pizarro <paulo.pizarro(at)digitro.com.br>	RollingFileAppender
David Resnick <dresnick(at)mobilespear.com>	NTEventAppender, integration work
Aaron Ingram <ai8(at)yahoo.com>	MSThreads support
Alan Anderson <alan(at)rushmore.com>	Win32DebugAppender, PropertyConfigurator
Emiliano Martin <emilianomc(at)terra.es>	PThreads support

Project Pages

Log4cpp is hosted on SourceForge at http://sourceforge.net/projects/log4cpp/.

Related Projects

Log4cpp is but one of many ports/implementations of the Log4j API. Here's an incomplete list:

log4c	An implementation in C by Cedric Legoater
log4cplus	An indepent C++ implementation by Tad Smith. Worth checking out if you don't like Log4cpp for some reason.

License

As of version 0.2.1 this library is licensed under the Lesser General Public License instead of the General Public License. No further license changes are planned :-).

Log for C++ (short name: log4cpp), a C++ library for flexible logging.
Copyright (C) 2000-2002 LifeLine Networks bv
Copyright (C) 2000-2002 Bastiaan Bakker
Portions Copyright others, see file THANKS and source code.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA