doc/bugs.txt

   1
   2 Reporting bugs
   3 --------------
   4
   5     Naturally it is easiest for me if you already know what causes the
   6     unexpected behavior. Even better if you have a patch to propose.
   7     However, quite often the reason for unexpected behavior is unknown,
   8     so below are a few things what to do before sending a bug report.
   9
  10     In case of a crash (usually segmentation violation):
  11
  12       1. Try to create a small example how to reprocude the issue.
  13
  14       2. If you are writing an application using liblzma or libzfile,
  15          double check that you are using the libraries correctly (for
  16          example, that you didn't forget to call lzma_init()). If it is
  17          the command line tool included in LZMA Utils that is crashing,
  18          ignore this step.
  19
  20       3. Compile LZMA Utils with debugging code using configure switch
  21          `--enable-debug'. If you are using GCC as the compiler, use
  22          CFLAGS='-O0 -ggdb'. Don't strip the resulting binaries.
  23
  24       4. Turn on core dumps. The exact command depends on your shell;
  25          for example in GNU bash it is done with `ulimit -c unlimited',
  26          and in tcsh with `limit coredumpsize unlimited'.
  27
  28       5. Try to reproduce the suspected bug. If you get `assertion failed'
  29          message, be sure to include the complete message in your bug
  30          report. If the application leaves a coredump, get a backtrace
  31          using gdb:
  32            $ gdb /path/to/app-binary   # Loads the app to the debugger.
  33            (gdb) core core   # Opens the coredump.
  34            (gdb) bt   # Prints the backtrace. Copy & paste to bug report.
  35            (gdb) quit   # Quits gdb.
  36
  37     Send your bug report to Lasse Collin <lasse.collin@tukaani.org>. Don't
  38     send the core dump file or the actual executables. If you have a small
  39     example file(s) (total size less than 100 KiB), please include it/them
  40     as an attachment.
  41
  42     Do NOT complain about problems with LZMA Utils to Igor Pavlov.
  43     Although the code of LZMA Utils is derived from his code, there are
  44     a lot of changes, which may have introduced bugs not present in
  45     the original version.
  46