9c847673278619a8a875084134a74f01d6ab1fec
[xscreensaver] / README.debugging
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                                 --------
16 STEP ZERO:
17
18     What are you doing here?  Go read README, and then the man page.
19
20 STEP ZERO, PART TWO:
21
22     Do you have the most recent version?  Go make sure.
23     http://www.jwz.org/xscreensaver/.
24
25 COMPILATION 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 Gtk or Motif (the
58      gtk/ or Xm/ 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/ is free and available on all systems; Xm/ (Motif)
62     is available on all commercial systems except SunOS 4.x and some
63     early releases of Solaris.  Linux and other free Unixes systems
64     usually come with Gtk, but a Motif clone is also available from
65     http://www.lesstif.org/.
66
67 RUN-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 it built using
85            Motif, Lesstif, or Gtk?  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 went wrong, and the
122            core file is bogus.  If the lines it prints out contain only
123            question marks, then the core file is bogus.  Are you sure the
124            core file came from that program?  Did you compile with -g, as
125            explained above?  If you don't compile with -g, the core file
126            won't have any information in it.
127
128            Never ever ever mail me (or anyone) a core file.  They are huge,
129            and are only meaningful on the machine that generated them, with
130            the exact executable that generated them, neither of which anyone
131            but you has access to.  Don't mail me a core file unless you're
132            also planning on mailing me your computer.
133
134         *  If it gets an X error, where did it come from?  Run
135            xscreensaver with the `-sync' command-line option.  When `-sync'
136            is used, X errors will cause xscreensaver to dump a core file.
137            Look at the core file with a debugger and show me the stack trace,
138            as above: I need to know where in xscreensaver that X error came
139            from.
140
141     If the problem is with the xscreensaver process itself, or if you
142     can't figure out which demo is causing the problem, or if you can't
143     reproduce the problem in isolation, then you will need to turn on
144     and examine the debugging output of the driver process.
145
146         *  Start `xscreensaver' with the command-line arguments
147
148               -verbose -no-capture
149
150            This will cause it to write a lot of debugging info to the stderr
151            of the xscreensaver process (the `-verbose' option turns on the
152            diagnostics; the `-no-capture' option prevents the data from being
153            displayed on the screensaver window as well.)
154
155         *  If the problem is intermittent, you might want to capture the
156            log information to a file and examine it later.  For example,
157            you could start it from your login script like this (csh syntax):
158
159                xscreensaver -sync -verbose -no-capture >>& saverlog &
160
161         *  Hackers only: If you're feeling adventurous enough to run gdb
162            on the xscreensaver driver process itself, make sure you've
163            read the commentary at the top of xscreensaver.c.
164
165 -----------------------------------------------------------------------------
166                                              http://www.jwz.org/xscreensaver/
167                                                  Jamie Zawinski <jwz@jwz.org>
168 -----------------------------------------------------------------------------