Debugging the source code

There are various ways to debug C++ code. But since Hydrogen is a real-time audio application, methods like setting break points and pausing the execution are not the most appropriate ones. Instead, I would recommend to use our log messages, like INFOLOG, instead.

The overall idea of debugging code with log messages can be summarized in the following steps:

1. Pin down the erroneous function/context using the information at hand.

2. Place log messages in the context to display local/global variables.

3. Recompile the Hydrogen source code (be sure to properly install the changes using make install in the build directory when changing header files).

      ./build.sh mm

   Using ./build.sh mm over changing into the build directory and calling make has the advantage of that the former script is able to invoke ccache for you. This helps you to save a lot of time by recompiling only those parts of the source you actually touched.

4. Run Hydrogen from the command line with a verbosity level of debugging.

     ./build/src/gui/hydrogen --verbose=Debug

5. Acquire further information by reading the logs and continue with step 1 until you were able to find the exact line of code, which is causing the trouble.

Step 1 is undoubtedly the most difficult of the above steps. If you struggle to pin down a good location in the code base to start the debugging, let me give you three distinct examples and how to approach them.

1. You see some odd error messages in the log of Hydrogen or some erroneous behavior is accompanied by them.

   Using the log you can figure out which function is the culprit. Place some log messages inside it to print its private members (or summary statistics of them) in order to figure out what went wrong. Also place some log messages right before the culprit gets called by other functions to figure out where and in which context the error occurs.

2. Hydrogen crashes with a segmentation fault and doesn't print any logs while doing so.

   By using gdb you can identify the function that caused the segfault. You start the debugging using

   gdb build/src/gui/hydrogen

   and by entering run and pressing the return key in the prompt that will show up. Now you make Hydrogen crash and print the whole backtrace using bt.

3. You experience abnormal behavior without any logs.

   These ones are especially hard. If you are able to reproduce the bug and to boil it down into a minimal example, they get way more easy to fix. If not, you, unfortunately, have to have some insights into Hydrogen to get an idea of what might cause the particular bug in a particular situation and which part of the code base is covering it. Place some "meaningful" log messages and queries for member variables in those context and hope to find something unexpected in the log. But remember, you can always contact other Hydrogen developers. You are not alone.

Regardless of the particular nature of the bug, it's always a good idea to check the documentation of related classes and functions. If some particular information you had to look up yourself to understand the code is missing or there is no documentation for the class/function at hand at all, feel encouraged to write some yourself. This will enable other developers and future contributors to be more productive and helps the overall Hydrogen project to evolve.