Loading...
Searching...
No Matches
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 imquic, 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 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 imquic like this:
CFLAGS="-Og -g3 -ggdb3 -fno-omit-frame-pointer" ./configure [..]
Once done configuring, do a make clean (to make sure everything is recompiled from scratch) and then a make and make install.
When imquic 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/your-imquic-app /path/to/coredump gdb bt
The bt command retrieves the backtrace, and is what you should provide as part of your new issue.
DON'T paste this backtrace in the issue text. Use a service like Gist or Pastebin and pass the generated link instead.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 imquic 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 imquic 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 [..]
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 imquic version should be Address Sanitizer compliant. To make sure, try using ldd to check whether libasan is indeed a dependency or not:
ldd src/.libs/libimquic.so | grep asan
If it is, you're done: whenever imquic 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 imquic will run just a bit slower, even though not to the point of being unusable (as when using, e.g., valgrind).