#
# $Id$
#

INTRODUCTION
============

This file explains how to enable tracing in Harbour.


TRACING
=======

Harbour implements tracing by adding calls to the following macro in
the C code:

  HB_TRACE(level, ("printf-style parameters", arg1, arg2));

The level specified for the HB_TRACE call affects harbour in two ways:
compilation time and run time.


COMPILATION TIME
================

At compilation time, the macro checks whether the preprocessor
constant HB_TR_LEVEL is set to any of the following values:

  #define HB_TR_ALWAYS     0
  #define HB_TR_FATAL      1
  #define HB_TR_ERROR      2
  #define HB_TR_WARNING    3
  #define HB_TR_INFO       4
  #define HB_TR_DEBUG      5

If it is not set to any of these, the macro is set to the value of
HB_TR_DEFAULT, which is currently set (in hbtrace.h) to HB_TR_WARNING.

Whether the user explicitly sets HB_TR_LEVEL or it is set by the
compiler, its effect is as follows: any calls in the code with a level
higher than HB_TR_LEVEL are obliterated from the code; these calls
simply disappear, and there is no effect in the code performance
thereafter.


RUN TIME
========

At run time, the user can set the environment variable HB_TR_LEVEL to
one of

  HB_TR_ALWAYS
  HB_TR_FATAL
  HB_TR_ERROR
  HB_TR_WARNING
  HB_TR_INFO
  HB_TR_DEBUG

with the following effect: any calls to HB_TRACE that were left by the
compiler and which have a level lower or equal to HB_TR_LEVEL will
print its arguments on stderr.


EXAMPLES
========

HB_TR_LEVEL    HB_TR_LEVEL    Description
compilation    run-time
-----------    -----------    ----------------------------------------
HB_TR_INFO     HB_TR_ERROR    All calls with levels HB_DEBUG are
                              erased from the code, so they have no
			      performance effect; only calls with
			      levels HB_TR_ERROR, HB_TR_FATAL and
			      HB_TR_ALWAYS are printed.

HB_TR_WARNING  HB_TR_INFO     All calls with levels HB_INFO and
                              HB_DEBUG are erased from the code, so
			      they have no performance effect; only
			      calls with levels HB_TR_WARNING,
			      HB_TR_ERROR, HB_TR_FATAL and
			      HB_TR_ALWAYS are printed. Notice how
			      setting HB_TR_INFO at run-time has no
			      effect, since the code was compiled with
			      a lower tracing level.

For example, I compile Harbour on WinNT with gcc (MINGW32), so I
usually set the C_USR environment variable like this:

  export C_USR='-DHARBOUR_USE_WIN_GTAPI -DHB_TR_LEVEL=HB_TR_INFO'

and make sure I have all the tracing for the INFO, WARNING, ERROR,
FATAL and ALWAYS levels. If I get too much information, at run-time I
can set an environment variable like this:

  export HB_TR_LEVEL=HB_TR_WARNING

and get rid of all the tracing for the INFO level. In this case, all
the calls to the tracing function for the INFO level will be done
anyway, so there will be a performance hit.


USAGE
=====

When Harbour is compiled/run with some level of tracing and then used
to compile a regular Harbour application, the app will output LOTS of
tracing information to stderr.  If you are using a sensible command
shell (such as bash) you can redirect stderr to a file like this:

  my_app 2>trace.txt


REDIRECTION
===========

The output generated while tracing goes to stderr by default. You can
control this at run-time by setting the environment variable
HB_TR_OUTPUT to the name of a file where you would like the tracing
output to be directed. If there is any problem opening the file for
writing, the output reverts to stderr.


TRACING THE PREPROCESSOR AND COMPILER
=====================================

Usually, you will not want tracing enabled in the preprocessor and
compiler; otherwise, you will see the trace output while compiling
Harbour itself.  If you REALLY want to enable tracing in the
preprocessor and/or compiler, you must define, in addition to
HB_TRACE_LEVEL as described above, the following variable, and then
recompile the preprocessor/compiler:

  HB_TRACE_UTILS

The value is of no importance.