In the magical world of fairies and unicorns, the sun always shines and everything always works smoothly and without issues. Unfortunately, this is not the world we live in, and so you might still encounter issues using Janus, e.g., unexpected crashes and the like. We always try and tackle bugs as soon as we spot them, but some issues may be always lingering in the background.

Should you encounter a bug or a crash, open a new issue on GitHub. Make sure you carefully read the guidelines for contributing, or otherwise we may decide to close the issue and not even look at it.

What's important for us to look into issues and bugs definitely is having enough information to do so. As such, whenever possible try to provide as many details and data as possible. Quite useful to us are GDB stacktraces and/or AddressSanitizer output. The following sections give a quick overview on how you can collect this information after a crash, but for a more detailed description of the tools you should refer to the related documentation pages and tutorials.

GDB

GDB is the GNU Project Debugger and is an effective tool for looking at what has happened (or is happening) inside an application. As such, it's quite useful to spot bugs and the like, as it can provide information about the values of variables when they were used and the application crashed.

First of all make sure that debugging symbols are enabled by reconfiguring Janus like this:

CFLAGS="-Og -g3 -ggdb3 -fno-omit-frame-pointer" ./configure --prefix=/opt/janus

Once done configuring, do a make clean (to make sure everything is recompiled from scratch) and then a make and make install.

When Janus crashes, you should get a core dump file somewhere. This is a recorded state of the application memory at the time of crashing, and so a backtrace of what lead to an issue can help. You can open such a core dump file via gdb this way:

gdb /path/to/bin/janus /path/to/coredump
gdb bt

The bt command retrieves the backtrace, and is what you should provide as part of your new issue.

Note: Please DON'T paste this backtrace in the issue text. Use a service like Gist or Pastebin and pass the generated link instead.

Address Sanitizer

An even better tool for spotting issues is Address Sanitizer, a fast memory error detector. Since it can spot memory errors, it's very useful to find out about hidden race conditions and the like.

Unlike GDB which can be used as is, though, to use Address Sanitizer you'll first need to recompile Janus with some new settings, as it requires a specific dependency on a library, libasan, which you'll need to install through your repository manager if needed. Besides, you'll need at least gcc 4.8 for this to work: older versions of gcc won't work.

Once you've installed libasan, reconfigure Janus like this:

CFLAGS="-O0 -g3 -ggdb3 -fno-omit-frame-pointer -fno-optimize-sibling-calls -fsanitize=address -fsanitize-address-use-after-scope -fno-sanitize-recover=all" LDFLAGS="-fsanitize=address" ./configure --prefix=/opt/janus

Of course you're free to add whatever additional configuration parameter you were using before: the important parts are the environment variables before that. Once done configuring, do a make clean (to make sure everything is recompiled from scratch) and then a make and make install as usual.

At this point, your Janus version should be Address Sanitizer compliant. To make sure, try using ldd to check whether libasan is indeed a dependency or not:

ldd janus | grep asan

If it is, you're done: whenever Janus crashes for any reason, you'll get additional output from Address Sanitizer automatically with details on what went wrong, and that's what you should provide as part of the issue content. Just as a side note, please beware that using Address Sanitizer Janus will run just a bit slower, even though not to the point of being unusable (as when using, e.g., valgrind).

Note: Please DON'T paste Address Sanitizer output in the issue text. Use a service like Gist or Pastebin and pass the generated link instead.