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, please report the bug anyway -- even vague bug reports can
13
be 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:
52
csh: setenv CC cc ; ./configure
55
Before doing this, you'll need to nuke `config.cache'.
57
If you get errors about not being able to find Gtk, then perhaps
58
the problem is that you don't have some kind of ``development
63
For runtime errors, it's important to keep in mind that there are
64
two parts to xscreensaver: there is the screensaver driver process
65
(the daemon that detects idleness, deals with locking, and launches
66
the demos); and there are the demos themselves (independent programs
67
that draw pretty pictures.)
69
* Compile with `make CFLAGS=-g' (so that if you get a core
70
dump, there will be debugging info in it.)
72
* What platform are you running on? What does the included
73
`./config.guess' shell script print?
75
* Is the problem in the driver (`xscreensaver'), the GUI
76
(`xscreensaver-demo'), or in the graphics hacks?
78
* If the problem is in the GUI, was it built using Gtk, Motif,
79
or Lesstif? Which version?
81
* If the problem is in one (or more) of the hacks, which ones?
82
If you're not sure, try running `xscreensaver-demo' to go
83
through the list of them and see which work and which don't.
85
* Does the problem occur when running that hack by hand, in
86
its own window (i.e., when started with no command-line args)?
88
* Does the problem occur when running that hack by hand, on
89
the root window (i.e., when started with the `-root' option)?
91
* IMPORTANT: What visual are you using? Send the output of
92
the `xdpyinfo' command.
94
* Does the problem go away if you give the program a different
95
`-visual' argument? (For example, `-visual pseudocolor' or
98
* IMPORTANT: What exactly goes wrong? No, I don't know what
99
you mean by "crash". Does it print an "X Error" and exit?
100
Does it dump core? Does it go into a loop?
102
* If it dumps core, what does the core file say? Run the
103
program under a debugger, and show me the stack trace.
104
To extract a stack trace from a core file with gdb, do this:
106
gdb ./the-program ./core
109
To extract a stack trace from a core file with dbx, do this:
111
dbx ./the-program ./core
114
If the bottom few lines of the output don't include the functions
115
`main_loop()' and `main()', then something went wrong, and the
116
core file is bogus. If the lines it prints out contain only
117
question marks, then the core file is bogus. Are you sure the
118
core file came from that program? Did you compile with -g, as
119
explained above? If you don't compile with -g, the core file
120
won't have any information in it.
122
Never ever ever mail me (or anyone) a core file. They are huge,
123
and are only meaningful on the machine that generated them, with
124
the exact executable that generated them, neither of which anyone
125
but you has access to. Don't mail me a core file unless you're
126
also planning on mailing me your computer.
128
* If it gets an X error, where did it come from? Run
129
xscreensaver with the `-sync' command-line option. When `-sync'
130
is used, X errors will cause xscreensaver to dump a core file.
131
Look at the core file with a debugger and show me the stack trace,
132
as above: I need to know where in xscreensaver that X error came
135
If the problem is with the xscreensaver process itself, or if you
136
can't figure out which demo is causing the problem, or if you can't
137
reproduce the problem in isolation, then you will need to turn on
138
and examine the debugging output of the driver process.
140
* Start `xscreensaver' with the command-line arguments
144
This will cause it to write a lot of debugging info to the stderr
145
of the xscreensaver process (the `-verbose' option turns on the
146
diagnostics; the `-no-capture' option prevents the data from being
147
displayed on the screensaver window as well.)
149
* If the problem is intermittent, you might want to capture the
150
log information to a file and examine it later. For example,
151
you could start it from your login script like this (csh syntax):
153
xscreensaver -sync -verbose -no-capture >>& saverlog &
155
* Hackers only: If you're feeling adventurous enough to run gdb
156
on the xscreensaver driver process itself, make sure you've
157
read the commentary at the top of xscreensaver.c.
159
-----------------------------------------------------------------------------
160
http://www.jwz.org/xscreensaver/
161
Jamie Zawinski <jwz@jwz.org>
162
-----------------------------------------------------------------------------
added
removed
README.debugging
