source: trunk/doc/Logging.txt@ 5013

/* $Id: Logging.txt,v 1.1 2000-07-09 22:27:52 phaller Exp $ */

                Odin Logging
                ~~~~~~~~~~~~

1.0 Standard logging feature
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The alpha 5 binaries and daily build zipfiles can generate logfiles to show 
what a win32 application is doing. This can be very useful to determine
why certain applications don't run correctly.

The major disadvantage of loggging is the overhead. Therefor it has been 
disabled by default in the alpha 5 release and daily builds.
To enable logging set the environment variable WIN32LOG_ENABLED:
   SET WIN32LOG_ENABLED=1

To disable logging again, you must clear this variable:
   SET WIN32LOG_ENABLED=


2.0 Extended logging features (new as of February 16th)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Disabling or enabling logging for all the Odin dlls isn't always useful.
To make logging more flexible, you can now disable or enable separate
source files for each dll (NOTE: Only implemented in kernel32, user32 & gdi32
for now)

Each dll that supports this feature has a file called dbglocal.cpp in it's
source directory. It contains a listing of all the sources files for that dll
(DbgFileNames) and an array with boolean values for each of those files.
To add this feature to a dll, you must do the following:
        - Write a custom dbglocal.cpp & dbglocal.h.
        - Every source file must include dbglocal.h with the correct debug constant:
                #define DBG_LOCALLOG    DBG_directory
                #include "dbglocal.h"
        - Initterm.cpp must call ParseLogStatus when the dll is loaded

Each dprintf now first checks if logging is enabled for this sourefile before
calling WriteLog. (NOTE: dbglocal must be included *after* misc.h)

When building a debug version of a dll, logging is enabled for all source files
by default.

2.1 Examples of custom logging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Disable logging for kernel32, but enable it for profile.cpp & wprocess.cpp
        set dbg_kernel32=-dll +profile +wprocess


Enable logging for kernel32, but disable it for profile.cpp & wprocess.cpp
        set dbg_kernel32=+dll -profile -wprocess