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, report the bug anyway -- even vague bug reports can be
  13     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://people.netscape.com/jwz/xscreensaver/
  24
  25 BUILDING:
  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                csh:  setenv CC cc ; ./configure
  52                sh:   CC=cc ; ./configure
  53
  54     Before doing this, you'll need to nuke `config.cache'.
  55
  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.
  63
  64 RUNNING:
  65
  66     For runtime errors, it's important to keep in mind that there are
  67     two parts to xscreensaver: there is the screensaver driver process
  68     (the part that detects idleness, deals with locking, and launches
  69     the demos); and there are the demos themselves (independent programs
  70     that draw pretty pictures.)
  71
  72         *  Compile with `make CFLAGS=-g'.
  73
  74         *  What platform are you running on?  What does the included
  75            `./config.guess' shell script print?
  76
  77         *  Is the problem in the driver, or in the graphics hacks?
  78
  79         *  If the problem is in the driver, was the driver built using
  80            Motif, or Athena?  Which version?
  81
  82         *  If the problem is in one (or more) of the hacks, which ones?
  83            If you're not sure, try
  84
  85               xscreensaver-command -demo
  86
  87            to go through the list of them and see which work and which
  88            don't.
  89
  90         *  Does the problem occur when running that hack by hand, in
  91            its own window?
  92
  93         *  Does the problem occur when running that hack by hand, on
  94            the root window (the `-root' option)?
  95
  96         *  IMPORTANT: What visual are you using?  Send the output of
  97            the `xdpyinfo' command.
  98
  99         *  Does the problem go away if you give the program a different
 100            `-visual' argument?  (For example, `-visual pseudocolor' or
 101            `-visual truecolor'.)
 102
 103         *  IMPORTANT: What exactly goes wrong?  No, I don't know what
 104            you mean by "crash".  Does it print an "X Error" and exit?
 105            Does it dump core?  Does it go into a loop?
 106
 107         *  If it dumps core, what does the core file say?  Run the
 108            program under a debugger, and show me the stack trace.
 109            (If you don't know how to do that, that's ok.)
 110
 111         *  If it gets an X error, where did it come from?  Run the
 112            program under a debugger; set a breakpoint on `exit';
 113            start the program with the `-sync' command-line option;
 114            and show me the stack trace when it stops.
 115
 116     If the problem is with the xscreensaver process itself, or if you
 117     can't figure out which demo is causing the problem, or if you can't
 118     reproduce the problem in isolation, then you will need to turn on
 119     and examine the debugging output of the driver process.
 120
 121         *  Start `xscreensaver' with the command-line arguments
 122
 123              -verbose -xrm '*captureStderr:false' -xrm '*captureStdout:false'
 124
 125            This will cause it to write a lot of debugging info to the
 126            stdout and stderr of the xscreensaver process (the -verbose
 127            argument turns on the diagnostics; the remaining arguments
 128            prevent the data from being displayed on the screensaver
 129            window as well.
 130
 131            You also might want to set the "*timestamp" resource to True, which
 132            will cause the xscreensaver messages to include the time at which
 133            they were printed.
 134
 135         *  If the problem is intermittent, you might want to capture the
 136            log information to a file and examine it later.
 137
 138         *  Hackers only: If you're feeling adventurous enough to run gdb
 139            on the xscreensaver driver process itself, make sure you've
 140            read the commentary at the top of xscreensaver.c.
 141
 142 -----------------------------------------------------------------------------
 143                                  http://people.netscape.com/jwz/xscreensaver/
 144                                             Jamie Zawinski <jwz@netscape.com>
 145 -----------------------------------------------------------------------------