
				xcrash README

			Last modified: October 20, 1993


xcrash DESCRIPTION:
====== ============

This program was developed in an attempt to increase reliability in
the area of X servers.  I have used a number different X servers and
have found a few problems with memory leaks and crashes. 
This is especially true when using many different line types, styles, etc.
If a dashed line does not draw dashed correctly, it is a problem
which needs to be fixed.  If drawing a dashed line crashes the server,
it is a critical problem which can stop development.  If it crashes
for a customer...  well, there goes the drawing of the nuclear reactor.

This program draws randomized primitives in an X window looking for these
problems.  It can be used in development of X servers to find bugs which
were introduced by fixes or features.  It can also be used by the
purchaser of an X server to see how robust it is or is going to be in the
area of drawing primitives (one of the main functions of an X server).

There are a number of test suites for the X server. Unisoft's is one 
which can be used for a "full" evaluation.  The T7 test suite (which in
an earlier version of this README I mistakenly attributed to Unisoft),
could also be used for this purpose.  This program does not attempt to
replace those suites.  xcrash does not check the primitives to see if they
are being drawn correctly.  It only looks for critical server failures.
Therefore, for full server validation, this program is only a small
(but important) part.

There is a shell script "xcrashmon" included with this package which can
be used in development of an X server.  It will bring up an X server and
runs tests waiting for a server crash.  If the server crashes, the script
causing the crash is saved off so it can be replayed later to see what the
problem is.  After the script is saved off, xcrashmon will do a dbx/where
if there is a core file and then start the process over.  The xcrashmon
script will probably need be modified to suit your system since currently,
it is only modified to support the Sun and RS/6000.

xcrash has a -nasty mode.  This mode has shows problems in a large number
of servers.  Primitives will be drawn "way off" screen.  Because of the
way most servers clip primitives, your machine may swap itself to death
when this is run.

There is a man page included in this package.  To read it, you can use
(on many systems):

	% nroff -man xcrash.man | more

MAKING AND RUNNING xcrash:
====== === ======= =======

To make xcrash on a system which has X setup nicely use:

	% xmkmf -a
	% make

For those awful systems which dont have xmkmf (and sometimes not even
imake!) you can try the following:

	% cc xcrash.c -L/usr/lib/X11 -lX11 -o xcrash

If that doesn't work, try finding a UNIX guru (possibly yourself) to track
down the problem.

When that completes, try the command:

	% xcrash -help

If you get no error messages, things have probably built correctly.

Now you will probably want to run it.  First, make sure you have nothing
important currently running under X.  If you do, it will be lost if the
server crashes.

To see if your server has basic functionality try:

	% xcrash -tests 10000

This will generate 10000-20000 random X primitive draw calls to your server.
Half of the screen (on the left hand size) should fill with garbage.  If your
server stays up through this test, it probably has basic functionality
in the area of primitive drawing.  Check to see how much memory the
server process is using.  This may hint to memory leaks or other problems
(although on most machines the server process will have increased in size
since it was started).

If it stayed up for that run, see if your server is 'golden' with:

	% xcrash -nasty -tests 10000

If it makes it through this without crashing and things looks like they
are drawing correctly, you are probably in very good shape in the
basic primitve area (better than I've seen).

If your server crashes, you can record and playback a session like this:
	
	% xcrash -v -tests 10 > out1
	% xcrash -in out1 

This will record and play back 10 tests.  If your server crashes during that
time, you have a script (out1) which you can send to someone to show them
the problem.

PROBLEMS WITH xcrash:
======== ==== =======

Problems with compilation of xcrash:

1]	The srandom() and random() functions are used to get random values.
	I know that these are different on some systems, but I can't
	remember which and I don't have them around.  If you have
	problems in this area, replace the calls to srand and rand
	with anything on your system that will seed the random number
	generator and generate a random number.

2]	The time() function is used by the program and may be different
	on some systems.  It is used to seed the random number generator.
	If you have a problem with this function, just pull it out and
	use the -seed parameter on the program line.

3]	The code is not ANSI because I needed to support non-ansi
	compilers.

BUGS in xcrash:
==== == =======

To compare a single test against another server, that server should
match some of the basic properties of the one which created the
test (same number of bitplanes, etc).  The program should handle this
in some way.

If you have and suggestions, problems, fixes, or additions to
xcrash you are welcome to mail me at ess@netcom.com.

I will attempt to respond.  For bugs, fixes, etc. please include the version
number (you can find this by running verbose mode), machine you are running
on, operating system, X11 release and patch numbers in your message.

Bugs found in your server (crashes, dumps, hangs, etc), should be directed
to whoever you got the X server from.

CREDITS:
========

Eric Swildens, while contracting at HaL Computer Systems, is the author of
xcrash.

Thanks go to Barrett Blake, Steve Goldsmith, Mike Lindzey, Greg Moore,
and Bob Pendelton of Hal Computer Systems, Inc. who have provided input
in development of the program. 

A big thanks also goes to the people who created and continue to support X.

Another quality product from:	ess@netcom.com
				Eric Swildens
