git.hungrycats.org Git - xscreensaver/blob - 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 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
  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, or in the graphics hacks?
  82
  83         *  If the problem is in the driver, was the driver built using
  84            Motif, Lesstif, or Athena?  Which version?
  85
  86         *  If the problem is in one (or more) of the hacks, which ones?
  87            If you're not sure, try
  88
  89               xscreensaver-command -demo
  90
  91            to go through the list of them and see which work and which
  92            don't.
  93
  94         *  Does the problem occur when running that hack by hand, in
  95            its own window (i.e., when started with no command-line args)?
  96
  97         *  Does the problem occur when running that hack by hand, on
  98            the root window (i.e., when started with the `-root' option)?
  99
 100         *  IMPORTANT: What visual are you using?  Send the output of
 101            the `xdpyinfo' command.
 102
 103         *  Does the problem go away if you give the program a different
 104            `-visual' argument?  (For example, `-visual pseudocolor' or
 105            `-visual truecolor'.)
 106
 107         *  IMPORTANT: What exactly goes wrong?  No, I don't know what
 108            you mean by "crash".  Does it print an "X Error" and exit?
 109            Does it dump core?  Does it go into a loop?
 110
 111         *  If it dumps core, what does the core file say?  Run the
 112            program under a debugger, and show me the stack trace.
 113            To extract a stack trace from a core file with gdb, do this:
 114
 115               gdb ./the-program ./core
 116               bt
 117
 118            To extract a stack trace from a core file with dbx, do this:
 119
 120               dbx ./the-program ./core
 121               where
 122
 123            If the bottom few lines of the output don't include the functions
 124            `main_loop()' and `main()', then something's wrong: are you sure
 125            the core file came from that program?
 126
 127         *  If it gets an X error, where did it come from?  Run
 128            xscreensaver with the `-sync' command-line option.  When `-sync'
 129            is used, X errors will cause xscreensaver to dump a core file.
 130            Look at the core file with a debugger and show me the stack trace,
 131            as above: I need to know where in xscreensaver that X error came
 132            from.
 133
 134     If the problem is with the xscreensaver process itself, or if you
 135     can't figure out which demo is causing the problem, or if you can't
 136     reproduce the problem in isolation, then you will need to turn on
 137     and examine the debugging output of the driver process.
 138
 139         *  Start `xscreensaver' with the command-line arguments
 140
 141               -verbose -no-capture-stderr
 142
 143            This will cause it to write a lot of debugging info to the stderr
 144            of the xscreensaver process (the `-verbose' option turns on the
 145            diagnostics; the `-no-capture-stderr' option prevents the data
 146            from being displayed on the screensaver window as well.)
 147
 148            You also might want to use the `-timestamp' option, which will
 149            cause the xscreensaver messages to include the time at which
 150            they were printed.
 151
 152         *  If the problem is intermittent, you might want to capture the
 153            log information to a file and examine it later.  For example,
 154            you could start it from your login script like this (csh syntax):
 155
 156               ( cd ~/src/xscreensaver/ ; \
 157                 xscreensaver -sync -verbose -timestamp -no-capture-stderr \
 158                 >>&LOG & )
 159
 160         *  Hackers only: If you're feeling adventurous enough to run gdb
 161            on the xscreensaver driver process itself, make sure you've
 162            read the commentary at the top of xscreensaver.c.
 163
 164 -----------------------------------------------------------------------------
 165                                              http://www.jwz.org/xscreensaver/
 166                                                  Jamie Zawinski <jwz@jwz.org>
 167 -----------------------------------------------------------------------------