HACKING

Lesstif is a complicated system, but not overwhelming.   We've
collected some tips on hacking LessTif here for your debugging and
hacking pleasure. There are some features that are compiled in by
default to make finding problems a little easier. Most can be turned off
with configure options. One such feature is editres support. If you don't
know what this is I suggest you search the web for editres.

There is a good section in BUG-REPORTING describing tracking down bugs in
_any_ X based app.

Don't forget about "cvs log"!!!! The comments on previous commits can be
very helpfull, especially if you're new to the game.

DEBUGSOURCES:

DEBUGSOURCES is an environment variable you can set to get debugging
output on a particular collection of source files.  DEBUGSOURCES=all will
give you more information than you ever wanted about what lesstif is
doing internally.  You can also set DEBUGSOURCES to a single file, or a
list of files.
 
If your shell is sh, bash, or ksh, you can for example 
set DEBUGSOURCES by

DEBUGSOURCES=MainW.c:FileSB.c
export DEBUGSOURCES

If your shell is csh or tcsh, you can set DEBUGSOURCES by

setenv DEBUGSOURCES "MainW.c:FileSB.c"

DEBUG_FILE:

The amount of diagnostics generated by DEBUGSOURCES can exceed the
line buffering of typical terminal settings.  The environmental
variable DEBUG_FILE can be used to direct the output to a file
instead of stdout.

An alternate method is to run the tests as follows:

DEBUGSOURCES=MainW.c:FileSB.c ./test1 2>&1 | tee debug.log

The advantage of this is that you also get to see the messages on the screen
as well as in a file.

DEBUGSOURCES is not limited to file names. In reality it can be any string
that matches what is in the source XdbDebug call. For example, 
DEBUGSOURCES=FOCUS will print debug info related to menu focus events, 
regardless of the file the statement is in. There are some more in there also.
Usually relating to specific problems involving many different files. To find
out what is available try:

grep XdbDebug *.c | grep -v __FILE__



Testing patches:

Lesstif has an extensive test tree under test.  Since even the most
seemingly trivial change can often have unexpected consequences, we
reccommend running the "testall" script under test before and after
applying a patch, to make sure that you haven't broken anything else with
your fix.

In these test programs, there is data that is labeled "expected".
Where do these values come from?

I guess I should answer this. They come from Jon :) Okay, sometimes I make them
also. The PrintDetails call that you see in the test code will print out the
Expected data in a format that can be cut'n pasted into the source, if the
second arg is NULL. So, we have Motif generate the Expected data for us. The
values are _very_ dependant on the default font in use. As long as you match
the font that is used to generate the Expected values the results are usually
right on. In a few cases we haven't been able to get an exact match. If we are
off by just a pixel or so, the application resource "*geometrySlop" can be set
to a value that will accept the error, and report sucess. In the cases where
the slop is not 0, it is also printed out with the results. The most recent
test results can also be viewed by pointing your web browser to

http://www.lesstif.org/test-results

In the test/common directory there is a library that is linked with each of
the test programs. In here you will find a replacement for XtAppMainLoop. Our
version allows the test apps to exit with a status that indicates sucess or
failure. This is where the PrintDetails function referred to above lives.
Nothing in this library relies on Motif, so that they function the same
whether the test apps are linked with LessTif or Motif.

This is probably also a good time to mention that all of the tests can 
be compiled and linked with Motif as well as LessTif. By typing

make motif-tests

in any of the test directories all the tests in that directory will be 
compiled and linked with Motif, assuming it is available. Therefore test1 will
be the test compiled and linked with LessTif, test1.motif will be the same
code compiled and linked with Motif. You can also build individual tests with

make test1.motif

The test library also includes a bunch of functions to simulate button,
presses, pointer movement, and other things necessary for automated testing.

The best thing about the tests is that they tell you whether everything it
was meant to test worked. For an example, take a look at rowcolumn/test51.
Try remembering to do all that everytime you make a change!!!!

Really, the best way to fix a bug, and have it stay fixed, is to write a test
and have it included in the test tree. Once a test has passed, a change to the
library will not be accepted if it causes a previously passing test to fail.
Well, it won't be accepted easily anyway :)

