Pantheios logging library - basic

This article's intended to describe briefly about how to build and use logging library Pantheios

Section 1: build Pantheios
Having built-Pantheios on your system is quite easy. You just need to get Pantheios and Stlsoft from Internet. You can download them from http://pantheios.sourceforge.net/downloads.html . Then extract them. Stlsoft is only-header file library so you don't need to build it. The other one, Pantheios otherwise need to be built. Assume that two directory that you extracted Pantheios and Stlsoft are "/home/username/pantheios-1.x.x" and "/home/username/stlsoft-1.x.x". Now you need to build Pantheios. All makefiles for different compilers (GCC, Visual C++, Intel ...) are contained in pantheios-1.x.x/build. With my compiler, GCC 4.2, i will use makefile from "pantheios-1.x.x/build/gcc42.unix/".

In order to build all components including core, examples and test, use: make build.
In order to build just core libs, use: make build.libs.core.
In order to build test components, use: make test.

After running makefile, all libraries reside in pantheios-1.x.x/lib, all executable files reside in pantheios-1.x.x/bin and pantheios's header files still be in pantheios-1.x.x/include.
Next step is to set environment variable for Pantheios and Stlsoft. You set FASTFORMAT_ROOT environment variable to pantheios-1.x.x
folder (in this example is /home/username/pantheios-1.x.x) and STLSOFT environment variable to stlsoft folder (here is /home/username/stlsoft-1.x.x)
With bash shell, you can type: export FASTFORMAT_ROOT='/home/username/pantheios-1.x.x' and export STLSOFT='/home/username/stlsoft-1.x.x'. Otherwise with C shell (csh, tcsh), you use: setenv FASTFORMAT_ROOT /home/username/pantheios-1.x.x and setenv STLSOFT /home/username/stlsoft-1.x.x.
OK, now you've already had ready-to-use logging tool. Next section is about how to use Pantheios logging library

Section 2: use Pantheios
Before using Pantheios, you should catch overview in architecture of Pantheios. Well, Pantheios is comprised by 4 components: application, core, front end and back end component.
- Application component provides user with APIs for logging, such as log_INFORMATIONAL(), log_DEBUG(), log_NOTICE(), log_WARNING(), log_ERROR(), log_CRITICAL(), log_ALERT(), log_EMERGENCY() (8 types of function). Beside, there are classes named inserter classes for handling data types, such as integer, pointer, real and other extent types.

- Core component is called by application component and is in charge of implementing functionalities. Core component is the one that don't need
user's implementation. On the other hand, the two last components take you more attention.

- Front-end component can be imagined as configuration items where process identity and severity level will be determined. For example, if you use on-stock front-end library "fe.simple", you could log with all severity levels except INFORMATIONAL and DEBUG levels ( correspond to log_INFORMATIONAL() and log_DEBUG() function ) or if you use on-stock front-end library "fe.all", you can log with all 8 log functions above.
User can use on-stock front-end libraries or write one by himself freely.

- Back-end component is a component which transport log statement to properly output like standard output (stdout/stderr), file, syslog ... This component is the last part in processing sequence of Pantheios. Just like front-end library, you can use on-stock back-end libraries or
implement one.
We can summarize processing sequence like this


Front-end and back-end component define required interfaces so any implementation of front-end or back-end must implements that interfaces.
Front-end requires 4 functions: pantheios_fe_init(), pantheios_fe_uninit(), pantheios_fe_processIdentity(), pantheios_fe_isSeverityLogged().
If you use stock front-end library such as fe.simple, these functions are implemented in that library (pantheios.1.fe.simple.gcc42.a if you use Linux and GCC 4.2) and ready to use. Otherwise, if don't like available libraries, you can write one by implementing these 4 functions.
Back-end requires 3 functions: pantheios_be_init(), pantheios_be_uninit(), and pantheios_be_logEntry(). In this article i just consider about using stock back-end, so assume that we want to log to console, then we will use be.fprintf back-end library. be.fprintf library defines 3 required functions by calling other 3 specific functions that are particular to logging to console. That 3 called functions are inside bec.fprintf library (in Pantheios, libraries like be.fprintf named Sole Interface Library and libraries like bec.fprintf named Implementation Library ). With this model, core component just need to know required interfaces and specific back-end or front-end can be plugged easily.
Now we link our program to both lib: be.fprintf and bec.fprintf ( pantheios-1.x.x/lib/pantheios.1.be.fprintf.gcc42.a and pantheios-1.x.x/lib/pantheios.1.bec.fprintf.gcc42.a in my case ) and it will log to console.



Section 3: example
Here is simple example


#include "pantheios/pantheios.hpp" //primary header file, always be included
#include "pantheios/frontends/stock.h"

//Specify process identity
const PAN_CHAR_T PANTHEIOS_FE_PROCESS_IDENTITY[] = "test.exe";

int main(int argc, char** argv){

//Use pantheios::log_xxx() or pantheios::log(xxx, ) with xxx is severity level

try
{
pantheios::log(pantheios::debug, "Entering main(", pantheios::args(argc, argv, pantheios::args::arg0FileOnly), ")");
pantheios::log_DEBUG("debug");
pantheios::log_INFORMATIONAL("informational");
pantheios::log_NOTICE("notice");
pantheios::log_WARNING("warning");
pantheios::log_ERROR("error");
pantheios::log_CRITICAL("critical");
pantheios::log_ALERT("alert");
pantheios::log_EMERGENCY("emergency");

return 1;
}
catch(std::bad_alloc&){
pantheios::log_ALERT("out of memory");
}
catch(std::exception& x){
pantheios::log_CRITICAL("Exception: ", x);
}
catch(...){
pantheios::puts(pantheios::emergency, "Unknown error");
}

return 2;
}


In order to compile this program, we use the following makefile

#########################
#NOTE:
#The core lib is essential part
#We use fe.all front-end lib so we can log with all severity levels
#We use stock fprintf back-end so we link to be.fprintf and bec.fprintf lib
#Util lib may be needed so we link to it
#########################
test.exe: test.o
g++ -o test.exe test.o -L$(FASTFORMAT_ROOT)/lib \
-lpantheios.1.core.gcc42\
-lpantheios.1.be.fprintf.gcc42 -lpantheios.1.bec.fprintf.gcc42\
-lpantheios.1.fe.all.gcc42 -lpantheios.1.util.gcc42

test.o: test.c
g++ test.c -c -I$(FASTFORMAT_ROOT)/include -I$(STLSOFT)/include
clean:
rm test.o test.exe

There are many other useful features introduced by Pantheios, this writing is just basic one. You should refer to Pantheios main page for more tutorial.