--- /dev/null
+
+ XScreenSaver
+
+ a handy guide for creating useful bug reports
+
+ --------
+
+ It's hard to imagine, but sometimes, xscreensaver has bugs. This
+ document gives some hints for isolating them; the more information
+ you can give me about the problem, the better the odds that I'll be
+ able to fix it. But, if you don't have time to go through these
+ steps, please report the bug anyway -- even vague bug reports can
+ be better than no bug report at all.
+
+ --------
+STEP ZERO:
+
+ What are you doing here? Go read README, and then the man page.
+
+STEP ZERO, PART TWO:
+
+ Do you have the most recent version? Go make sure.
+ http://www.jwz.org/xscreensaver/.
+
+COMPILATION PROBLEMS:
+
+ If you get an error running the `configure' script, the first thing
+ you should try is deleting the `config.cache' file, and running again.
+ If that doesn't fix it, the information I'll need to see to make
+ sense of the problem is the following:
+
+ * everything printed to stderr/stdout when you first ran
+ ./configure;
+
+ * the contents of the `config.log' file.
+
+ Make sure you blow away the config.cache file before regenerating
+ this info, or else the `config.log' file will be mostly empty/useless.
+
+ Experience seems to show that the most common configure problem is
+ that sites have gcc installed, but installed improperly. The
+ configure script will always try to use gcc in preference to another
+ compiler if gcc exists, so if gcc exists but is broken, it won't
+ work. Your options are:
+
+ * get someone to fix the gcc installation;
+
+ * rearrange your $PATH so that the broken gcc is not on it;
+
+ * or pass $CC in the environment, like so:
+
+ csh: setenv CC cc ; ./configure
+ sh: CC=cc ; ./configure
+
+ Before doing this, you'll need to nuke `config.cache'.
+
+ If you get errors about not being able to find Motif or Athena (the
+ Xm/ or Xaw/ header files), and you can't find them on your system,
+ then your system is horked and your vendor is lame. Perhaps the
+ problem is that you don't have some kind of ``development option''
+ installed. Xt/ and Xaw/ (Athena) are free and available on all
+ systems; Xm/ (Motif) is available on all commercial systems except
+ SunOS 4.x and some early releases of Solaris. For Linux and other
+ free Unixes systems, a Motif clone is available from
+ http://www.lesstif.org/.
+
+RUN-TIME PROBLEMS:
+
+ For runtime errors, it's important to keep in mind that there are
+ two parts to xscreensaver: there is the screensaver driver process
+ (the daemon that detects idleness, deals with locking, and launches
+ the demos); and there are the demos themselves (independent programs
+ that draw pretty pictures.)
+
+ * Compile with `make CFLAGS=-g' (so that if you get a core
+ dump, there will be debugging info in it.)
+
+ * What platform are you running on? What does the included
+ `./config.guess' shell script print?
+
+ * Is the problem in the driver (`xscreensaver'), the GUI
+ (`xscreensaver-demo'), or in the graphics hacks?
+
+ * If the problem is in the GUI, was the it built using
+ Motif, Lesstif, or Athena? Which version?
+
+ * If the problem is in one (or more) of the hacks, which ones?
+ If you're not sure, try running `xscreensaver-demo' to go
+ through the list of them and see which work and which don't.
+
+ * Does the problem occur when running that hack by hand, in
+ its own window (i.e., when started with no command-line args)?
+
+ * Does the problem occur when running that hack by hand, on
+ the root window (i.e., when started with the `-root' option)?
+
+ * IMPORTANT: What visual are you using? Send the output of
+ the `xdpyinfo' command.
+
+ * Does the problem go away if you give the program a different
+ `-visual' argument? (For example, `-visual pseudocolor' or
+ `-visual truecolor'.)
+
+ * IMPORTANT: What exactly goes wrong? No, I don't know what
+ you mean by "crash". Does it print an "X Error" and exit?
+ Does it dump core? Does it go into a loop?
+
+ * If it dumps core, what does the core file say? Run the
+ program under a debugger, and show me the stack trace.
+ To extract a stack trace from a core file with gdb, do this:
+
+ gdb ./the-program ./core
+ bt
+
+ To extract a stack trace from a core file with dbx, do this:
+
+ dbx ./the-program ./core
+ where
+
+ If the bottom few lines of the output don't include the functions
+ `main_loop()' and `main()', then something's wrong: are you sure
+ the core file came from that program?
+
+ * If it gets an X error, where did it come from? Run
+ xscreensaver with the `-sync' command-line option. When `-sync'
+ is used, X errors will cause xscreensaver to dump a core file.
+ Look at the core file with a debugger and show me the stack trace,
+ as above: I need to know where in xscreensaver that X error came
+ from.
+
+ If the problem is with the xscreensaver process itself, or if you
+ can't figure out which demo is causing the problem, or if you can't
+ reproduce the problem in isolation, then you will need to turn on
+ and examine the debugging output of the driver process.
+
+ * Start `xscreensaver' with the command-line arguments
+
+ -verbose -no-capture
+
+ This will cause it to write a lot of debugging info to the stderr
+ of the xscreensaver process (the `-verbose' option turns on the
+ diagnostics; the `-no-capture' option prevents the data from being
+ displayed on the screensaver window as well.)
+
+ You also might want to use the `-timestamp' option, which will
+ cause the xscreensaver messages to include the time at which
+ they were printed.
+
+ * If the problem is intermittent, you might want to capture the
+ log information to a file and examine it later. For example,
+ you could start it from your login script like this (csh syntax):
+
+ ( cd ~/src/xscreensaver/ ; \
+ xscreensaver -sync -verbose -timestamp -no-capture \
+ >>&LOG & )
+
+ * Hackers only: If you're feeling adventurous enough to run gdb
+ on the xscreensaver driver process itself, make sure you've
+ read the commentary at the top of xscreensaver.c.
+
+-----------------------------------------------------------------------------
+ http://www.jwz.org/xscreensaver/
+ Jamie Zawinski <jwz@jwz.org>
+-----------------------------------------------------------------------------
projects / xscreensaver / blobdiff