GAMBAS BOOK 3.19.1

Again and again, problems occur when programming with Gambas. Then it is good to be able to turn to other programmers and to the developers of Gambas, because the Gambas community is committed and communicative. The chances of finding solutions are good if you come forward with a meaningful bug report. Note that compiling a bug report follows some basic rules. In this chapter, the author Claus D. reports on his experiences with bug reports.

Basic information on the Gambas programming language is provided by the Gambas wiki at http://gambaswiki.org/wiki. At https://lists.gambas-basic.org/listinfo/user you will find a list of national and international forums and websites dealing with Gambas. The German-language forum https://www.gambas-club.de deserves special mention.

The online Gambas book, with its many examples and projects from a wide range of areas, can be particularly helpful where the Gambas documentation provides insufficient information on classes, components or libraries.

Problems that go beyond this, such as

• unexpected program behaviour or
• program crashes

usually require contacting the developers of Gambas. The procedures described below promise the best and quickest results if your programmes or, for example, the use of a Gambas component get stuck again.

For those cases where you are not one hundred percent sure that it is a bug, the Gambas Mailing List at https://lists.gambas-basic.org/listinfo/user is available. This forum provides first class support from Gambas developers.

Before sending a bug report and registering for it, you should be reasonably sure that no solutions have been discussed or offered for the identified problem. Therefore, use the convenient search function at https://lists.gambas-basic.org/cgi-bin/search.cgi . Here is an example:

Figure 11.5.3.2.1: Example: Query in the Gambas Mailling List

The description of the bug must be in English, formulated as precisely as possible and absolutely provide all details that could be relevant and helpful for isolating or reproducing the bug. This includes the following details:

• Gambas version,
• Linux distribution (Suse, Debian, Mint, Ubuntu) with version and desktop environment,
• GUI toolkit used such as gb.qt4, gb.qt5 or gb.gtk,
• Linux kernel version and
• architecture (32 or 64 bit).

This and other information can be retrieved via the Gambas IDE using the menu item ?/ System information … and copied to the clipboard for further processing.

Here is an excerpt of the information - especially about the operating system:

  [System]
  Gambas=3.12.2
  OperatingSystem=Linux
  Kernel=4.15.0-45-generic
  Architecture=x86_64
  Distribution=Linux Mint 18.3 Sylvia
  Desktop=CINNAMON
  Theme=Gtk
  Language=de_DE.UTF-8
  Memory=7893M
  ...

You can read an (original) bug report and the reactions to the report here:

  Hi Benoit,
  in the Preferences> Projects form, two translations are missing:
  Compress PNG ... and Automatic translation ...
  I immediately sent the translations and made the merger request.
  Have I made a mistake of communication, do I have to wait for more translations?

  Is it normal to always receive from GitLab: "gambas | Pipeline #46825672 has failed for italian-translations" ?

  Regards
  Gianluigi

  Theoritically no, pratically yes: apparently the two ArchLinux pipelines do not work anymore.
  According to the error message, it seems that they rely on an image that is now missing.
  I can't say more, I didn't write the Gambas GitLab config file.

  Regards,
  --
  Benoît Minisini

  It's fixed. It's the name of the archlinux images on the docker website that changed.
  --
  Benoît Minisini

Already in your first bug report, send the developers a small Gambas project where the reported bug is sure to be triggered. This would be the most descriptive and effective way to clearly describe the identified problem.

Reporting bugs should only be done through the Gambas bug tracker, which you can access at http://gambaswiki.org/bugtracker. However, you can only send a bug report if you have previously registered with a valid email address on the above website.

To post, you should proceed like this:

• Select whether it is a bug or a request for a new feature.
• Set the priority of your report according to your assessment (High, Low, Medium).
• Select the affected component or topic from the list provided.
• Select the Gambas version.
• Insert all important information into the field “Description”:

• Three-digit Gambas version.
• Linux distribution (Suse, Debian, Mint, Ubuntu) with version and desktop environment.
• GUI toolkit used such as gb.qt4, gb.qt5 or gb.gtk
• Linux kernel version
• Architecture (32 or 64 bit)

• Be sure to copy all system information into the “System description” field.

• Upload a sample programme in which the problem has been isolated.
• Provide information as promptly as possible when requested by the developer.
• If necessary, change the thread status offered in a drop-down list.

To better illustrate GUI issues, also consider sending screen videos.

All issues in a bug thread are assigned a ticket number and sent to your stored email address, so you are always kept up to date.

In order to be able to document program crashes caused by, for example, a memory protection violation (segmentation/signal #11 fault) for reporting in the bug tracker, two programs are recommended by the Gambas developers:

• GNU Debugger
• Valgrind program

To prepare for the test, open a console and make the Gambas project directory the current directory:

  $ cd /home/claus/Gambas/project_folder

Then enter the following command to start the GNU debugger:<code_b_5>.

The console output of the debugger for the Gambas project 'test' looked like this:

  claus@claus-VBox:~/Gambas3/test$ gdb gbx3
  GNU gdb (Ubuntu 8.1-0ubuntu3) 8.1.0.20180409-git
  Copyright (C) 2018 Free Software Foundation, Inc.
  License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
  This is free software: you are free to change and redistribute it.
  ...
  This GDB was configured as "x86_64-linux-gnu".
  Type "show configuration" for configuration details.
  For bug reporting instructions, please see:
  <http://www.gnu.org/software/gdb/bugs/>.
  Find the GDB manual and other documentation resources online at:
  <http://www.gnu.org/software/gdb/documentation/>.
  For help, type "help".
  Type "apropos word" to search for commands related to "word"...
  Reading symbols from gbx3...(no debugging symbols found)...fertig.
  (gdb)

To start the programme in the current project directory with the Gambas interpreter, enter the run command after the debugger prompt ( gdb ) and take the programme to the point where it crashes.

The output of the debugger then looked like this, for example:

  (gdb) run
  Starting program: /usr/bin/gbx3
  [Thread debugging using libthread_db enabled]
  Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
  [New Thread 0x7fffea517700 (LWP 4722)]
  qt5ct: using qt5ct plugin
  [New Thread 0x7fffe0231700 (LWP 4723)]
  Thread 1 "gbx3" received signal SIGSEGV, Segmentation fault.
  0x0000555555573f47 in ?? ()
  (gdb)

In this case, it is a detected memory protection violation (segmentation fault).

The programme flow before the programme crash is of great use for the developer's error analysis and can be determined via a so-called backtrace. The backtrace function is started by entering the bt command after the debugger prompt, and the output then looks like this:

  (gdb) bt
  #0  0x00007ffff5e827a8 in ?? () from /usr/lib/gambas3/gb.qt5.so
  #1  0x00007ffff432f5b5 in QMetaObject::activate(QObject*, int, int, void**) ()
     from /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
  #2  0x00007ffff5373b82 in QAbstractButton::clicked(bool) ()
     from /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5
  ...
  #5 0x00007ffff537536d in QAbstractButton::mouseReleaseEvent(QMouseEvent*) ()
     from /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5
  #6 0x00007ffff52c1038 in QWidget::event(QEvent*) ()
     from /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5
  #7 0x00007ffff528282c in QApplicationPrivate::notify_helper(QObject*, QEvent*)
      () from /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5
  #8 0x00007ffff528a64f in QApplication::notify(QObject*, QEvent*) ()

Attention: This example does not correspond to a real bug and only shows an excerpt of the output of the GNU debugger!

To stop the GNU debugger enter the following command:

  (gdb) quit

For a bug analysis, the Gambas developers need all the output of the GNU Debugger after the run and bt commands, which you should copy into the bug report.

Some programme crashes take place with a delay in relation to the actual bug, which is why a stack backtrace is not always sufficient. In order to be able to carry out analyses here as well, the free software Valgrind can be used, which allows the execution of a programme in an emulated CPU environment and thus enables extensive observations and analyses. The programme flow of the Gambas programme to be tested is considerably slowed down by this, which must be accepted in view of the intended goal.

The installation of Valgrind can be carried out in a console:

  $ sudo apt install valgrind

To prepare for the test, open a console and make the Gambas project directory the current directory:

  $ cd /home/claus/Gambas/project_folder

The test is started by the following command in a console:

  $ valgrind --tool=memcheck --num-callers=50 gbx3 > valgrind.out 2>&1

To log the test results, this creates the file valgrind.out in the project directory, which you should make available in full to the Gambas developers in a report.

Since Valgrind will try to continue running the programme after an error, it may be necessary to stop the programme by typing Ctrl+C.

Here is an extract of the contents of the valgrind.out file:

  ==32717== Process terminating with default action of signal 11 (SIGSEGV) ***
  ==32717==  Access not within mapped region at address 0xFFFFFFFFFFFFFFF9
  ==32717==    at 0x127F47: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x1372B9: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x1550F6: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x15AFBC: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x15DC58: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x13B228: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x13D2EF: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x6F87B58: ??? (in /usr/lib/gambas3/gb.qt5.so.0.0.0)
  ==32717==    by 0x6F8A129: ??? (in /usr/lib/gambas3/gb.qt5.so.0.0.0)
  ==32717==    by 0x15BD42: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x15DC8E: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x1261B9: ??? (in /usr/bin/gbx3)
  ==32717==    by 0x4E5DB96: (below main) (libc-start.c:310)
  ==32717==  If you believe this happened as a result of a stack
  ==32717==  overflow in your program's main thread (unlikely but
  ==32717==  possible), you can try to increase the size of the
  ==32717==  main thread stack using the --main-stacksize= flag.
  ==32717==  The main thread stack size used in this run was 8388608.

The line marked with *** is where the crash happened. In this case it was a Signal_11 error (protection violation).