source: trunk/third/xscreensaver/README.debugging @ 12203

Revision 12203, 6.9 KB checked in by ghudson, 26 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r12202, which included commits to RCS files with non-trunk default branches.
Line 
1
2                              XScreenSaver
3
4              a handy guide for creating useful bug reports
5
6                                --------
7
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.
14
15                                --------
16STEP ZERO:
17
18    What are you doing here?  Go read README, and then the man page.
19
20STEP ZERO, PART TWO:
21
22    Do you have the most recent version?  Go make sure.
23    http://www.jwz.org/xscreensaver/.
24
25COMPILATION PROBLEMS:
26
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:
31
32        *  everything printed to stderr/stdout when you first ran
33           ./configure;
34
35        *  the contents of the `config.log' file.
36
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.
39
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:
45
46        *  get someone to fix the gcc installation;
47
48        *  rearrange your $PATH so that the broken gcc is not on it;
49
50        *  or pass $CC in the environment, like so:
51
52              csh:  setenv CC cc ; ./configure
53              sh:   CC=cc ; ./configure
54
55    Before doing this, you'll need to nuke `config.cache'.
56
57    If you get errors about not being able to find Motif or Athena (the
58    Xm/ or Xaw/ header files), and you can't find them on your system,
59    then your system is horked and your vendor is lame.  Perhaps the
60    problem is that you don't have some kind of ``development option''
61    installed.  Xt/ and Xaw/ (Athena) are free and available on all
62    systems; Xm/ (Motif) is available on all commercial systems except
63    SunOS 4.x and some early releases of Solaris.  For Linux and other
64    free Unixes systems, a Motif clone is available from
65    http://www.lesstif.org/.
66
67RUN-TIME PROBLEMS:
68
69    For runtime errors, it's important to keep in mind that there are
70    two parts to xscreensaver: there is the screensaver driver process
71    (the daemon that detects idleness, deals with locking, and launches
72    the demos); and there are the demos themselves (independent programs
73    that draw pretty pictures.)
74
75        *  Compile with `make CFLAGS=-g' (so that if you get a core
76           dump, there will be debugging info in it.)
77
78        *  What platform are you running on?  What does the included
79           `./config.guess' shell script print?
80
81        *  Is the problem in the driver (`xscreensaver'), the GUI
82           (`xscreensaver-demo'), or in the graphics hacks?
83
84        *  If the problem is in the GUI, was the it built using
85           Motif, Lesstif, or Athena?  Which version?
86
87        *  If the problem is in one (or more) of the hacks, which ones?
88           If you're not sure, try running `xscreensaver-demo' to go
89           through the list of them and see which work and which don't.
90
91        *  Does the problem occur when running that hack by hand, in
92           its own window (i.e., when started with no command-line args)?
93
94        *  Does the problem occur when running that hack by hand, on
95           the root window (i.e., when started with the `-root' option)?
96
97        *  IMPORTANT: What visual are you using?  Send the output of
98           the `xdpyinfo' command.
99
100        *  Does the problem go away if you give the program a different
101           `-visual' argument?  (For example, `-visual pseudocolor' or
102           `-visual truecolor'.)
103
104        *  IMPORTANT: What exactly goes wrong?  No, I don't know what
105           you mean by "crash".  Does it print an "X Error" and exit?
106           Does it dump core?  Does it go into a loop?
107
108        *  If it dumps core, what does the core file say?  Run the
109           program under a debugger, and show me the stack trace.
110           To extract a stack trace from a core file with gdb, do this:
111
112              gdb ./the-program ./core
113              bt
114
115           To extract a stack trace from a core file with dbx, do this:
116
117              dbx ./the-program ./core
118              where
119
120           If the bottom few lines of the output don't include the functions
121           `main_loop()' and `main()', then something's wrong: are you sure
122           the core file came from that program?
123
124        *  If it gets an X error, where did it come from?  Run
125           xscreensaver with the `-sync' command-line option.  When `-sync'
126           is used, X errors will cause xscreensaver to dump a core file.
127           Look at the core file with a debugger and show me the stack trace,
128           as above: I need to know where in xscreensaver that X error came
129           from.
130
131    If the problem is with the xscreensaver process itself, or if you
132    can't figure out which demo is causing the problem, or if you can't
133    reproduce the problem in isolation, then you will need to turn on
134    and examine the debugging output of the driver process.
135
136        *  Start `xscreensaver' with the command-line arguments
137
138              -verbose -no-capture
139
140           This will cause it to write a lot of debugging info to the stderr
141           of the xscreensaver process (the `-verbose' option turns on the
142           diagnostics; the `-no-capture' option prevents the data from being
143           displayed on the screensaver window as well.)
144
145           You also might want to use the `-timestamp' option, which will
146           cause the xscreensaver messages to include the time at which
147           they were printed.
148
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):
152
153              ( cd ~/src/xscreensaver/ ; \
154                xscreensaver -sync -verbose -timestamp -no-capture \
155                >>&LOG & )
156
157        *  Hackers only: If you're feeling adventurous enough to run gdb
158           on the xscreensaver driver process itself, make sure you've
159           read the commentary at the top of xscreensaver.c.
160
161-----------------------------------------------------------------------------
162                                             http://www.jwz.org/xscreensaver/
163                                                 Jamie Zawinski <jwz@jwz.org>
164-----------------------------------------------------------------------------
Note: See TracBrowser for help on using the repository browser.