BugReportingAndErrors

Bug reports and feature requests

All support communication, including wiki edits, is logged on our GitHub issues page.

Before submitting a new issue

0. Update to the most recent stable release (see these upgrade instructions given in our FAQ).
1. Review relevant documentation including known limitations.
2. Confirm it does not already appear on the list of open issues.

When submitting a new issue

• For tracking purposes, it is important to keep communication as granular as possible.
• At minimum, each bug report and/or feature request should be documented as a separate issue.
• In general, the more details you can provide, the better.
• For new feature requests, you can skip the instructions below and directly post a new issue describing your proposed new feature and why it is a good thing we should add to RNAStructViz
• For installation questions, please read through the next section so you can provide us with as much information as possible about the state of your install platform and what specific problems you are running into installing RNAStructViz

Detailed instructions for gathering bug report data

Information to include in a new issue

To submit a new bug report please add a new issue to our tracking database which includes the following information:

1. To help us identify platform and version you are running, execute and report the output of the command:

$ RNAStructViz --about

2. Any information you can provide us with how you installed our software.
3. A step-by-step procedure for how we can reproduce the bugs you experience.
4. If you are able to take screenshots to document the step-by-step account of how to reproduce the bugs you are reporting, please upload those as attachments to the new issue thread.
5. Consider uploading copies of the CT files you are loading when the error you are reporting occurs. This extra information will allow us to track down the errors ourselves efficiently.

Please also do take the time to enter relevant error messages (if any) into a search engine to gather perspective on common software configuration issues before posting a new support request.

Getting even more verbose errors with a debugger

You can locate the precise source code file line numbers where RNAStructViz is failing using the gdb (on Linux) or lldb (on Mac) debugger. We will walk you through the procedure of using lldb on Mac OSX. The steps and commands issued to generate the extra debugging information are the same for gdb for Linux and other Unix systems using the GNU compiler toolchain.

1. Launch the debugger with an argument of the program you want to debug:

$ lldb /usr/local/opt/rnastructviz/bin/RNAStructViz
(lldb) target create "/usr/local/opt/rnastructviz/bin/RNAStructViz"
Current executable set to '/usr/local/opt/rnastructviz/bin/RNAStructViz' (x86_64).
(lldb) 

This will open a sub-shell which has its own command set for debugging the program.

2. Type "run" and then go through the steps necessary to crash the RNAStructViz application, i.e., generate the bug you are reporting.

3. Once the crash has occurred, the RNAStructViz GUI should be frozen and you should not be able to enter any new input into the application. Navigate back to the terminal you used to type "run". You should see the llvm debugger shell prompt again. Type "bt" at this prompt (bt for backtrace):

(lldb) bt

4. This will print a backtrace (or stack trace) of the most recent source code line numbers executed to obtain the error. Please copy and paste this backtrace information and post it along with your bug report.

NOTE: Some users have reported issues getting llvm to debug with RNAStructViz. If this happens on your system, please try to update your version of Apple's xcode to a 64-bit-compatible version if you can.

An optional bash export to print verbose information on heap allocation and memory access errors

There is a useful bash shell export that can be set to enable additional printing of verbose debugging information when memory allocated from and/or freed from the heap is accessed inappropriately within the code. In general, running the following command may generate valuable issues about your runtime error that can be included with a new issues report:

$ export MALLOC_CHECK_=3
$ RNAStructViz

Please include any error messages or stack trace data generated after you set this option. To unset, or disable the option when you run other software compiled with gcc/g++, you can open a new terminal window, or choose to issue the following command:

$ unset MALLOC_CHECK_

The rationale for what this runtime export setting provides is quoted from the GNU manpages for the compiler:

Another possibility to check for and guard against bugs in the use of malloc, realloc and free is to set the environment variable MALLOC_CHECK_. When MALLOC_CHECK_ is set, a special (less efficient) implementation is used which is designed to be tolerant against simple errors, such as double calls of free with the same argument, or overruns of a single byte (off-by-one bugs).

Not all such errors can be protected against, however, and memory leaks can result. If MALLOC_CHECK_ is set to 0, any detected heap corruption is silently ignored; if set to 1, a diagnostic is printed on stderr; if set to 2, abort is called immediately. This can be useful because otherwise a crash may happen much later, and the true cause for the problem is then very hard to track down.

Settings 1 and 2 can be combined by setting MALLOC_CHECK_ to 3 (three). This will enable the print out of warning messages on standard error (1), and will call abort() when problems are noticed (2).