
General:
--------

GEAS only produces debugging output when debug mode is turned on
(the --enable-debug argument is supplied to autogen.sh/configure causing
DEBUG to be defined, in the file config.h). Without this, only logging of
successful operations may be logged.

There are two main options for debugging output, which may be controlled
independantly: The first is on screen display, and the second is written to
a log file.


Screen display:
---------------

Various different log messages have a detail level associated with them,
that is set at compile time. At run time (but only, currently, at server
startup) the debugging level to be displayed can be set.

The debug level can be set in either the configuration file, or on the
command line (overriding the configuration file.) Currently the default, if
not set in either of these places, is 'low' detail.

Debug levels are set from low (1) to high (10) where the greater the number,
the greater the amount of debugging information displayed. Also, 0 means
'off', or no debugging information displayed.

In the configuration file, the option 'debuglevel' can be set to a number
between 0 and 10, or the text values 'off', 'low', 'medium' or 'high'.


Debugging Log File:
-------------------

This allows full debugging details to be recorded and reviewed at a later
time, while displaying only more general information directly to the screen.

This is controlled by two options in the configuration file:

debugfile      - Set the file to write debugging information to. if
                 this is not set, then no file will be written.
debugfilelevel - Control how much information is written. (defaults
                 to all, unless no file is being written.)


Using GDB:
==========

For details on using gdb, either examine the manpage or the info file (type
'man gdb' or 'info gdb' at the shell prompt. Type 'info info' for help
on using the 'info' help program.)


Running GEAS in gdb:
--------------------

On the command line, type 'gdb <path>/geas-server'. (The path is not
required if the current directory contains the executable. It can be an
absolute or relative path.)

In order to run GEAS, type 'run' followed by any command line arguments.
eg:
  run
  run -c ./geas.conf
  run -c ./geas.conf -d3


Locating the cause of a crash:
------------------------------

When using gdb, it is possible to follow the stack to identify the precise
order in which various functions were called, along with the arguments to
the functions. This can help determine exactly what had been happening at
the time of a crash.

When GEAS crashes (for example, because of a segmentation fault) gdb will
provide some basic information about what happened. the command 'bt' entered
at the gdb prompt will display a list of functions, starting from the point
where the crash happened. Library functions will often have less
information, but functions in the GEAS source will include the file and line
where they were called.

(Note: when submitting a bug report, the full stack trace will often be
useful, as it may reveal obviously incorrect values, and provide a guide as
to where the error occured.)

Additionally, other gdb features allow examination of all variables and
function arguments. If at all possible, these should be examined to see if
anything appears obviously wrong (eg: dereferencing NULL pointers.)

Commands of particular use:
  up, down      : Move up and down the stack
  display, print: Display the contents of variables

The info file will be of particular use, and has sectrions on running and
stopping a program, examining program data and source files, and controlling
gdb.


Possible problems:
------------------

There have been reports of difficulties using gdb to debug GEAS
(particularly appearing related to the embedded python interpreter).

In most cases, the apparant fault will be that the program immediately
raises an exception and exits. However, typing 'continue' will allow
execution to proceed, although this may need to be entered more than once.

Note that this is different to an error causing the program to crash on
startup.
