Debugging programs compiled with IBM Open Enterprise SDK for Go

IBM Open Enterprise SDK for Go is an industry-standard Go compiler that you can use to build Go programs for the z/OS platform. IBM® z/OS® Debugger supports debugging programs compiled with IBM Open Enterprise SDK for Go 1.17.

Note: Go programs are currently not supported in IBM Z® Open Debug that is provided in Wazi for VS Code and Wazi for Dev Spaces.

`go build` command

With each go build action, the Go compiler creates a single load module that includes all runtime package functions required to run the application packages. The Go compiler and assembler produce DWARF debugging data by default, which is embedded as NOLOAD (no load) classes in the resulting program object. You cannot produce a separate DWARF side file.

The go build command passes arguments to the underlying compiler, assembler, and linker tools by using the following options:

-gcflags Compiler flags: -dwarf=true is required and specified as the default.; -dwarflocationlists=true is required and specified as the default.
-asmflags Assembler flags: No assembler options affect the debugger.
-ldflags Linker flags: Do not specify -s because it disables the generation of the DWARF symbol table.; Do not specify -w because it disables the embedding of DWARF information in the program object.

Debugging a Go program

The Go build process produces a Language Environment-enabled program object with entry point _rt0_s390x_zos. To debug a Go program object, you must use the Language Environment® TEST option.

Go programs only run under UNIX System Services.

You can use the following shell script called dtrun to debug:
```
export STEPLIB=EQAW.SEQAMOD:$STEPLIB
export GOMAXPROCS=1
export _CEE_RUNOPTS="TEST(ERROR,*,PROMPT,DBMDT:*)"
$@
```
Note: This shell script assumes that you have logged on to the z/OS system with the Remote System Explorer, and that Debug Manager is activated on the system. If Debug Manager is not available, you can code the TEST option as TEST(ERROR,*,PROMPT,TCPIP&your.ip.address%your-debug-port:*).
Invoke the debugger for your Go program. You can use the following command to run the shell script:
```
dtrun hello
```
The debugger starts at the main Language Environment entry point. For all Go programs, the entry point is the function runtime._rt0_s390x_zos.
To proceed to your application code, set an entry breakpoint and click Resume. You can use the Modules view to set the breakpoint.
For example, to set an entry breakpoint for main.main in the Go program object hello2, complete the following steps:
1. Expand the Go program object.
2. Expand the main compile unit.
3. Expand the source file where the main function is defined.
4. Right-click main.main and select Set Entry Breakpoint.

Debug features that are not supported for Go programs

Compiled code coverage
Delay debug
Debug console commands
Conditional breakpoints
Load breakpoints
Source entry breakpoints
Watch breakpoints
Actions on breakpoints
Stop at all function entries
Run to location
Jump to location
Hover
Automonitor filter
Playback
Visual debugging

Go features that are not supported in debugging

cgo
Go assembler
Debugging artifacts of go test
Channel expressions
Expressions containing Go functions
Go application code that runs in more than one thread. If you set GOMAXPROCS=1, z/OS Debugger can debug your whole application. Otherwise, any code running in a thread other than the initial one is not debugged.

Known issues and limitations

Expression evaluation for non-top stack frame local (auto) variables is not supported.
STEP OVER might behave like STEP INTO when the callee is inlined.