How to debug Golf programs with gdb

Debugging information is always included regardless of how you make your application; what varies is the amount of debugging info included. You can compile your Golf application normally:

gg -q

Copied!

This will create an executable that can be debugged with gdb. You can debug your Golf program with gdb just as if it were a plain C program, which technically it is. This makes it much easier to get to the bottom of any issue directly without having to deal with virtual machines, p-code translation, assembler etc.

For this reason, the debugging ecosystem for Golf programs is already fully developed. For instance you can use Valgrind or Google ASAN with Golf programs just as you'd with a C program.

Note that in order to debug the Golf itself, it's best to be compiled from source, or you need to use the included debugging information (meaning you need to install a debug package). This will be covered in another article here on Golf blog.

Example

Here's an example of debugging using Golf. We'll create a little parsing application to illustrate.

First, let's create a directory for our application "split" (since you'll be splitting a URL query string into name/value pairs):

mkdir split
cd split
gg -k split

Copied!

Create a source file "parse.golf" and copy this:

 begin-handler /parse
     silent-header
     set-string str = "a=1&b=2&c=3"
     // Split string using "&" as a delimiter
     split-string str with "&" to pair count pair_tot
     start-loop repeat pair_tot use pair_count
         read-split pair_count from pair to item
         // Now split each item using "=" as a delimiter
         split-string item with "=" to equal
         read-split 1 from equal to name
         read-split 2 from equal to value
         // Output each name/value
         print-format "Name [%s] value [%s]\n", name, value
     end-loop
 end-handler

Copied!

This program will parse the string "a=1&b=2&c=3" to produce name/value pairs - this is obviously a parsing of URL query string. It uses split-string statement which will split the string based on some delimiter string, and then you use read-split statement to get the split pieces one by one. Very simple.

Compile and link this:

gg -q --public

Copied!

What's what here? First of all "-q" will make your project (meaning compile and link it, both command-line executable and application server), while "--public" makes all handlers public, meaning they can handle external requests (i.e. those from a caller outside your application).

Debugging

Okay so now to execute this with gdb, do this:

gg -r --req="/parse"

Copied!

This will produce something like the following (substitute "your-user" for your OS user name):

export CONTENT_TYPE=
export CONTENT_LENGTH=
unset GG_SILENT_HEADER
export GG_SILENT_HEADER
export REQUEST_METHOD=GET
export SCRIPT_NAME="/split"
export PATH_INFO="/parse"
export QUERY_STRING=""
/home/your-user/.golf/apps/split/.bld/split

Copied!

This is basically setting the necessary environment variables and then executing the "split" program (specified here in full path). Remember, Golf program can execute exactly the same as a web application server as well as command-line executable; hence the web environment variables need to be set.

So if you copy and paste the above into bash shell, you'll get:

Name [a] value [1]
Name [b] value [2]
Name [c] value [3]

Copied!

Which is the proper parsing of the string. Okay so far so good.

Now to debug your program, do:

gdb /home/your-user/.golf/apps/split/.bld/split

Copied!

You are now in gdb debugging shell:

GNU gdb (Ubuntu 15.0.50.20240403-0ubuntu1) 15.0.50.20240403-git
Copyright (C) 2024 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.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "x86_64-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://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 /home/your-user/.golf/apps/split/.bld/split...
(gdb)

Copied!

Now you can use standard gdb commands. We'll set a break in our code above (which is handler "parse"), and then run the program. Next we'll simply execute one statement at a time, and then we'll print the loop variable:

(gdb) br parse
Breakpoint 1 at 0x3a5e: file /var/lib/gg/bld/split/__parse.o.c, line 4.
(gdb) run
Starting program: /home/your-user/.golf/apps/split/.bld/split
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".

Breakpoint 1.1, parse () at /home/your-user/tmp/test/split/parse.golf:1
4	void parse () {
(gdb) next
2	    silent-header
(gdb)
3	    set-string str = "a=1&b=2&c=3"
(gdb)
4	    split-string str with "&" to pair count pair_tot
(gdb)
5	    start-loop repeat pair_tot use pair_count
(gdb)
6	        read-split pair_count from pair to item
(gdb)
5	    start-loop repeat pair_tot use pair_count
(gdb)
6	        read-split pair_count from pair to item
(gdb)
7	        split-string item with "=" to equal
(gdb)
8	        read-split 1 from equal to name
(gdb)
9	        read-split 2 from equal to value
(gdb)
11	        print-format "Name [%s] value [%s]\n", name, value
(gdb)
Name [a] value [1]
6	        read-split pair_count from pair to item
(gdb) print pair_count
$1 = 1

Copied!

As you can see, you're stepping through your Golf program, with the code showing exactly as it is in your source file! You can do here anything that you can in a C program, for instance set breakpoints, conditions etc. In this case we also print the value of variable pair_count.

gdb is too powerful to summarize here. There are many tutorials on the web. But suffice it to say you can easily debug your programs and see how they work step by step and a lot more (that's an understatement!).

Finally, if you're so inclined, you can also step through generated C code and see exactly what makes your program tick. To do that, make your program with "--c-lines" flag, which lets you do that:

gg -q --public --c-lines

Copied!

Now, repeat the above to get into gdb, and it may look like this (note that generated code can always change and there's absolutely no guarantee it will stay the same!):

Breakpoint 1.1, parse () at /home/your-user/.golf/apps/split/.bld/__parse.o.c:4
4	void parse () {
(gdb) next
7	gg_get_config ()->ctx.req->silent=1;
(gdb) n
10	char *str = GG_EMPTY_STRING;
(gdb)
17	if (_gg_gstr_once0) {
(gdb)
18	gg_gstr_ret0 = gg_mem_add_const (_gg_gstr0, sizeof(_gg_gstr0)-GG_ALIGN);
(gdb)
19	_gg_gstr_once0 = false;
(gdb)
21	str = gg_gstr_ret0;
(gdb)
22	gg_mem_add_ref (gg_gstr_ret0);
(gdb)
29	if (_gg_gstr_once1) {
(gdb)
30	gg_gstr_ret1 = gg_mem_add_const (_gg_gstr1, sizeof(_gg_gstr1)-GG_ALIGN);
(gdb)
31	_gg_gstr_once1 = false;
(gdb)
33	gg_split_str *pair = NULL;
(gdb)
34	gg_num pair_tot = 0;
(gdb)
35	gg_break_down (str, gg_gstr_ret1, &(pair));
(gdb)
36	pair_tot= (pair)->num_pieces;
(gdb)
39	gg_num pair_count = 0;
(gdb)

Copied!

This is literally the C code that runs your program. It doesn't look as user friendly for sure, but it's useful if you'd like to see what exactly takes place. It's also useful in debugging your program and Golf as well.

Now you know how to debug your Golf programs with gdb.