---

Qmmslog

0.2.1

Introduction

This is a port to Qt/C++ of the Jakarta project's log4j package.

It is an attempt to bring the flexibility of log4j to a multi-platform C++ environment.

If you are unfamiliar with log4j, I quote here from the log4j documentation:

   Inserting log statements into your code is a low-tech method
   for debugging it.  It may also be the only way because
   debuggers are not always available or applicable.  This is
   often the case for distributed applications.

   On the other hand, some people argue that log statements
   pollute source code and decrease legibility. (We believe that
   the contrary is true).

   With log4j it is possible to enable logging at runtime
   without modifying the application binary. The log4j package is
   designed so that these statements can remain in shipped code
   without incurring a heavy performance cost. Logging behavior
   can be controlled by editing a configuration file, without
   touching the application binary.

   Logging equips the developer with detailed context for
   application failures. On the other hand, testing provides
   quality assurance and confidence in the application. Logging
   and testing should not be confused. They are complementary. 
   When logging is wisely used, it can prove to be an essential tool.
 
   One of the distinctive features of log4j is the notion of
   inheritance in loggers. Using a logger hierarchy
   it is possible to control which log statements are output at 
   arbitrarily fine granularity but also great ease. This helps 
   reduce the volume of logged output and minimize the cost of logging.
 

Requirements

Qmmslog now supports both the standard Qt and the multi-threaded version. That is, qmmslog can link against both -lqt and -lqt-mt. If the multithreaded Qt is used, then one must use the compiler flag -DQT_THREAD_SUPPORT.

If you have doxygen installed then the Makefile invokes it to generate docs.

I have tested this package on Gnu/Linux using egcs-2.91.66.

Installation

Typically, one unpacks the tarball in a suitable location with the standard tar xvzf qmmslog.tar.gz.

Since this is alpha software (for now) I provide a Makefile suitable for use under GNU/Linux only. I have not made a .pro (for use with qmake), but will for the upcoming beta release.

I have kept the Makefile as simple and uncryptic as possible with the intention that one can easily modify it to suit. With this out of the way, do the following:

 cd src
 make all
 make install
 

This will compile, create libqmmslog.so, install the .so and all the includes to /usr/local/lib and /usr/local/include respectively, and invoke doxygen to generate documentation. The install step uses sudo, so you need to have the appropriate entry in /etc/sudoers. Documentation is installed in /usr/local/doc/qmmslog by default. I am also assuming that /usr/local/lib is in /etc/ld.so.conf or LD_LIBRARY_PATH.

Examine main.cpp to see how to use this package. Generally, one need only do the following:

 include <qmms/log.hh>
 using namespace Qmms::Log;
 

Note that I use *.hh and not *.h for include files.

You can mail me with questions/comments/rants/flames/money.

Naming Convention

If the original package is log4j, and existing ports of it have already taken the names log4cpp, log4cplus, log4Py, log4Perl, etc., then why have I used qmmslog instead of log4qt?

Answer: Because I'm following trolltech's naming convention. Enough said.

Usage

Not completed yet. Here are a few pointers:

The first line in main() should be one of the following:

 BasicConfigurator::configure()
 

(or)

 PropertyConfigurator::configure()
 

Either of these will initialize the Qmmslog system, the first in a standard but simple way (so that the impatient can just start using it), while the second requires that the user first write a configuration file (default name is .qmmslogrc). Instructions for this are in the doc page for PropertyConfigurator.

As of release 0.2, one can precede the configurator line with the following:

 LogLog::init( bool, bool );
 

This will initialize the Qmmslog internal debugger, so that one can see exactly what Qmmslog is doing (a handy thing at times). If the first bool is true then internal logging is enabled (not much point in setting it false, is there?) and if the second in true then internal debugging runs in quiet mode, where only errors and warns are printed.

The penultimate line in main() (just before return or exit) should be

 Category::shutdown() 
 

which gracefully closes the Qmmslog system. A simple example is main.cpp included with this distribution.

Generating documentation manually

This step assumes that doxygen is installed on the user's system.

From the top-level directory of the distribution (not src!), simply type

doxygen

to generate html, man, and latex docs. To activate links to Qt documentation, one must do the following (after running doxygen):

 cd doc/html
 ./installdox -l qt.tag$QTDIR/doc/html
 

Author:

Max M. Strumia

© 2001 Max M. Strumia. All rights reserved.

This software is published under the terms of the Q Public License the Gnu General Public License and the Apache Public License.

See the directory licenses at the top of this distribution.

---