kpathsea: Bug checklist
8.1 Bug checklist
=================
Before reporting a bug, please check below to be sure it isn't already
known (⇒Common problems).
Bug reports should be sent via electronic mail to <tex-k@tug.org>.
The general principle is that a good bug report includes all the
information necessary for reproduction. Therefore, to enable
investigation, your report should include the following:
* The version number(s) of the program(s) involved, and of Kpathsea
itself. You can get the former by giving a sole option '--version'
to the program, and the latter by running 'kpsewhich --version'.
The 'NEWS' and 'ChangeLog' files also contain the version number.
* The hardware, operating system (including version), compiler, and
'make' program you are using (the output of 'uname -a' is a start
on the first two, though incomplete).
* Any options you gave to 'configure'. This is recorded in the
'config.status' files.
If you are reporting a bug in 'configure' itself, it's probably
system-dependent, and it will be unlikely the maintainers can do
anything useful if you merely report that thus-and-such is broken.
Therefore, you need to do some additional work: for some bugs, you
can look in the file 'config.log' where the test that failed should
appear, along with the compiler invocation and source program in
question. You can then compile it yourself by hand, and discover
why the test failed. Other 'configure' bugs do not involve the
compiler; in that case, the only recourse is to inspect the
'configure' shell script itself, or the Autoconf macros that
generated 'configure'.
* The log of all debugging output, if the bug is in path searching.
You can get this by setting the environment variable
'KPATHSEA_DEBUG' to '-1' before running the program. Please look
at the log yourself to make sure the behavior is really a bug
before reporting it; perhaps "old" environment variable settings
are causing files not to be found, for example.
* The contents of any input files necessary to reproduce the bug.
For bugs in DVI-reading programs, for example, this generally means
a DVI file (and any EPS or other files it uses)--TeX source files
are helpful, but the DVI file is required, because that's the
actual program input.
* If you are sending a patch (do so if you can!), please do so in the
form of a context diff ('diff -c') against the original
distribution source. Any other form of diff is either not as
complete or harder for me to understand. Please also include a
'ChangeLog' entry.
* If the bug involved is an actual crash (i.e., core dump), it is
easy and useful to include a stack trace from a debugger (I
recommend the GNU debugger GDB (<https://gnu.org/software/gdb>).
If the cause is apparent (a 'NULL' value being dereferenced, for
example), please send the details along. If the program involved
is TeX or Metafont, and the crash is happening at apparently-sound
code, however, the bug may well be in the compiler, rather than in
the program or the library (⇒TeX or Metafont failing TeX or
Metafont failing.).
* Any additional information that will be helpful in reproducing,
diagnosing, or fixing the bug.
Info Catalog
kpathsea: Reporting bugs
kpathsea: Mailing lists