4 a handy guide for creating useful bug reports
8 It's hard to imagine, but sometimes, xscreensaver has bugs. This
9 document gives some hints for isolating them; the more information
10 you can give me about the problem, the better the odds that I'll be
11 able to fix it. But, if you don't have time to go through these
12 steps, report the bug anyway -- even vague bug reports can be
13 better than no bug report at all.
18 What are you doing here? Go read README, and then the man page.
22 Do you have the most recent version? Go make sure.
23 http://www.jwz.org/xscreensaver/
27 If you get an error running the `configure' script, the first thing
28 you should try is deleting the `config.cache' file, and running again.
29 If that doesn't fix it, the information I'll need to see to make
30 sense of the problem is the following:
32 * everything printed to stderr/stdout when you first ran
35 * the contents of the `config.log' file.
37 Make sure you blow away the config.cache file before regenerating
38 this info, or else the `config.log' file will be mostly empty/useless.
40 Experience seems to show that the most common configure problem is
41 that sites have gcc installed, but installed improperly. The
42 configure script will always try to use gcc in preference to another
43 compiler if gcc exists, so if gcc exists but is broken, it won't
44 work. Your options are:
46 * get someone to fix the gcc installation;
48 * rearrange your $PATH so that the broken gcc is not on it;
50 * or pass $CC in the environment, like so:
51 csh: setenv CC cc ; ./configure
52 sh: CC=cc ; ./configure
54 Before doing this, you'll need to nuke `config.cache'.
56 If you get errors about not being able to find Motif or Athena (the
57 Xm/ or Xaw/ header files), and you can't find them on your system,
58 then your system is horked and your vendor is lame. Perhaps the
59 problem is that you don't have some kind of ``development option''
60 installed. Xt/ and Xaw/ (Athena) are free and available on all
61 systems; Xm/ (Motif) is available on all commercial systems except
62 SunOS 4.x and some early releases of Solaris. For Linux and other
63 free Unixes systems, a Motif clone is available from
64 http://www.lesstif.org/.
68 For runtime errors, it's important to keep in mind that there are
69 two parts to xscreensaver: there is the screensaver driver process
70 (the daemon that detects idleness, deals with locking, and launches
71 the demos); and there are the demos themselves (independent programs
72 that draw pretty pictures.)
74 * Compile with `make CFLAGS=-g' (so that if you get a core
75 dump, there will be debugging info in it.)
77 * What platform are you running on? What does the included
78 `./config.guess' shell script print?
80 * Is the problem in the driver, or in the graphics hacks?
82 * If the problem is in the driver, was the driver built using
83 Motif, Lesstif, or Athena? Which version?
85 * If the problem is in one (or more) of the hacks, which ones?
86 If you're not sure, try
88 xscreensaver-command -demo
90 to go through the list of them and see which work and which
93 * Does the problem occur when running that hack by hand, in
94 its own window (i.e., when started with no command-line args)?
96 * Does the problem occur when running that hack by hand, on
97 the root window (i.e., when started with the `-root' option)?
99 * IMPORTANT: What visual are you using? Send the output of
100 the `xdpyinfo' command.
102 * Does the problem go away if you give the program a different
103 `-visual' argument? (For example, `-visual pseudocolor' or
104 `-visual truecolor'.)
106 * IMPORTANT: What exactly goes wrong? No, I don't know what
107 you mean by "crash". Does it print an "X Error" and exit?
108 Does it dump core? Does it go into a loop?
110 * If it dumps core, what does the core file say? Run the
111 program under a debugger, and show me the stack trace.
112 (If you don't know how to do that, that's ok.)
114 * If it gets an X error, where did it come from? Run
115 xscreensaver with the `-sync' command-line option; if -sync
116 is used, then X errors will cause xscreensaver to dump a core
117 file. Look at the core file with a debugger and show me the
118 stack trace: were in xscreensaver did that X error come from?
120 If the problem is with the xscreensaver process itself, or if you
121 can't figure out which demo is causing the problem, or if you can't
122 reproduce the problem in isolation, then you will need to turn on
123 and examine the debugging output of the driver process.
125 * Start `xscreensaver' with the command-line arguments
127 -verbose -xrm '*captureStderr:false' -xrm '*captureStdout:false'
129 This will cause it to write a lot of debugging info to the
130 stdout and stderr of the xscreensaver process (the -verbose
131 argument turns on the diagnostics; the remaining arguments
132 prevent the data from being displayed on the screensaver
135 You also might want to use the `-timestamp' option, which will
136 cause the xscreensaver messages to include the time at which
139 * If the problem is intermittent, you might want to capture the
140 log information to a file and examine it later. For example,
141 you could start it from your login script like this (csh syntax):
143 ( cd ~/src/xscreensaver/ ; \
144 xscreensaver -sync -verbose -timestamp \
145 -xrm '*captureStderr:false' -xrm '*captureStdout:false' \
148 * Hackers only: If you're feeling adventurous enough to run gdb
149 on the xscreensaver driver process itself, make sure you've
150 read the commentary at the top of xscreensaver.c.
152 -----------------------------------------------------------------------------
153 http://www.jwz.org/xscreensaver/
154 Jamie Zawinski <jwz@jwz.org>
155 -----------------------------------------------------------------------------