How to report bugs
From Gerris
Good bug reporting is a very useful contribution to the development of Gerris.
A few rules for a good bug report:
- Make sure that what you are reporting really is a bug (and not a "user error"). For example error messages due to bad parameter file syntax are (usually) not bugs. In a similar way, the code may not do what you expect it to do but it doesn't necessarily mean this is a bug: this can be due for example to a misunderstanding of Gerris' interface or of the physics of the problem etc... On the other hand if you get an error message starting with:
Gfs-ERROR **: ...
this most definitely is a Gerris bug. - Do not give a chance to (real) bugs. If you see one, report it even if you find a simple workaround (and report the workaround too!).
- Report bugs to the gfs-users mailing list.
- Always include the exact Gerris version in your bug report.
- Always include the exact (cut and paste) error message you got.
- Give a concise summary of the bug in the subject line.
- Before sending your bug report, try to reproduce the bug with the simplest possible parameter file: remove as many objects as possible, lower the resolution, if possible make the bug appear as quickly as possible (ideally at the first timestep) etc... This will greatly help developers track the bug down.
- Always attach (as a separate file), the Gerris parameter file (and any other file) necessary to reproduce the bug together with your bug report.
- Include any other relevant information which may help reproduce the problem. Reproducing the problem on a different system (the developer's) is the first and a very important step in bug tracking.
- Do not be disappointed if the bug you reported is not fixed quickly. Gerris has many bugs (as most software does) and your bug may not be the most critical to fix right now. If it is critical to you and you feel you have waited long enough for a fix, try to work a bit more on it on your own (for example by simplifying your parameter file further or by seing which combinations of parameters trigger it etc...) and send a follow-up to your earlier bug report. In any case, all bug reports are carefully archived for future reference.
Post-mortem debugging with gdb
Some bugs can cause the program to receive a "fatal signal". In this case, you will get a message looking like:
[machine:20795] *** Process received signal *** [machine:20795] Signal: Segmentation fault (11) [machine:20795] Signal code: Address not mapped (1) [machine:20795] Failing at address: 0x20 ...
In this case the Unix signal was (11) Segmentation fault. Before posting a bug report, it greatly helps to find out a bit more about the problem. This can be done using post-mortem debugging. Note that this will only work if you have installed Gerris from source (not when using the pre-built packages).
You need first to make sure that your system allows core dumps, like this:
ulimit -c unlimited
which tells the system to allow for unlimited core dump size (this is often set to zero on desktop systems). You then need to rerun the command which produced the error. You should get the same message as above with a line saying that a "core dump" has been generated i.e.
[machine:20795] *** Process received signal *** ... Segmentation fault (core dumped)
The corresponding file is usually called core or core.20795 (the number is the PID of the process which generated the core file). You can then used gdb to get information on where the error occured. Like this for example:
gdb gerris2D core.20795 gdb> where ...
You should copy and paste the output from gdb in your bug report.
