How to report bugs
Adapted from A Hacker’s Guide to NCURSES, by Eric S. Raymond.
The reporting address for bugs is bug-ncurses@gnu.org. It is a GNU Mailman list; join it from its subscription page.
The list archive holds past reports and their answers.
The ncurses code is maintained by a small group of volunteers. While we try our best to fix bugs promptly, we simply don’t have a lot of hours to spend on elementary hand-holding. We rely on intelligent cooperation from our users. If you think you have found a bug in ncurses, there are some steps you can take before contacting us that will help get the bug fixed quickly.
In order to use our bug-fixing time efficiently, we put people who show us they have taken these steps at the head of our queue. This means that if you don’t, you will probably end up at the tail end and have to wait a while.
1. Develop a recipe to reproduce the bug
Section titled “1. Develop a recipe to reproduce the bug”Bugs we can reproduce are likely to be fixed very quickly, often within days. The most effective single thing you can do to get a quick fix is develop a way we can duplicate the bad behavior: ideally, by giving us source for a small, portable test program that breaks the library. (Even better is a keystroke recipe using one of the test programs provided with the distribution.)
2. Try to reproduce the bug on a different terminal type
Section titled “2. Try to reproduce the bug on a different terminal type”In our experience, most of the behaviors people report as library bugs are actually due to subtle problems in terminal descriptions. This is especially likely to be true if you are using a traditional asynchronous terminal or PC-based terminal emulator, rather than xterm or a UNIX console entry.
It is therefore extremely helpful if you can tell us whether or not your problem reproduces on other terminal types. Usually you will have both a console type and xterm available; please tell us whether or not your bug reproduces on both.
If you have xterm available, it is also good to collect xterm reports for different window sizes. This is especially true if you normally use an unusual xterm window size: a surprising number of the bugs we have seen are either triggered or masked by these.
3. Generate and examine a trace file for the broken behavior
Section titled “3. Generate and examine a trace file for the broken behavior”Recompile your program with the debugging versions of the libraries. Insert a curses_trace() call with the argument set to TRACE_UPDATE. (See Debugging with traces for details on trace levels.) Reproduce your bug, then look at the trace file to see what the library was actually doing.
Another frequent cause of apparent bugs is application coding errors that cause the wrong things to be put on the virtual screen. Looking at the virtual-screen dumps in the trace file will tell you immediately if this is happening, and save you from the possible embarrassment of being told that the bug is in your code and is your problem rather than ours.
If the virtual-screen dumps look correct but the bug persists, it’s possible to crank up the trace level to give more and more information about the library’s update actions and the control sequences it issues to perform them. The test directory of the distribution contains a tool, tracemunch, for digesting these logs to make them less tedious to wade through.
Often you will find terminfo problems at this stage by noticing that the escape sequences put out for various capabilities are wrong. If not, you are likely to learn enough to be able to characterize any bug in the screen-update logic quite exactly.
4. Report details and symptoms, not just interpretations
Section titled “4. Report details and symptoms, not just interpretations”If you do the preceding two steps, it is very likely that you will discover the nature of the problem yourself and be able to send us a fix. This will create happy feelings all around and earn you good karma for the first time you run into a bug you really can’t characterize and fix yourself.
If you are still stuck, at least you will know what to tell us. Remember, we need details. If you guess about what is safe to leave out, you are too likely to be wrong.
If your bug produces a bad update, include a trace file. Try to make the trace at the least voluminous level that pins down the bug. Logs that have been through tracemunch are OK: it doesn’t throw away any information (actually they are better than un-munched ones because they are easier to read).
If your bug produces a core-dump, please include a symbolic stack trace generated by gdb(1) or your local equivalent.
Tell us about every terminal on which you have reproduced the bug, and every terminal on which you can’t. Ideally, send us terminfo sources for all of these (yours might differ from ours).
Include your ncurses version and your OS/machine type, of course! You can find your ncurses version in the curses.h file.
Test frames for the library algorithms
Section titled “Test frames for the library algorithms”If your problem smells like a logic error or in cursor movement or scrolling or a bad capability, there are a couple of tiny test frames for the library algorithms in the ncurses directory that may help you isolate it. These aren’t part of the normal build: make test_progs in that directory builds them.
The most important of these is lib_mvcur, a test frame for the cursor-movement optimization code. With this program, you can see directly what control sequences will be emitted for any given cursor movement or scroll/insert/delete operations. If you think you have got a bad capability identified, you can disable it and test again. The program is command-driven and has on-line help.
If you think the vertical-scroll optimization is broken, or just want to understand how it works better, build hashmap and read the header comments of hardscroll.c and hashmap.c; then try it out. You can also test the hardware-scrolling optimization separately with hardscroll.