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 Open Enterprise SDK for Go 1.21 and 1.22.
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.
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.- -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.
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.
- 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 theTEST
option asTEST(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:
The debugger starts at the main Language Environment entry point. For all Go programs, the entry point is the functiondtrun hello
runtime._rt0_s390x_zos
. - To proceed to your application code, set an entry breakpoint and click
Resume. You can use the Modules view in
the Eclipse IDE to set the breakpoint.For example, to set an entry breakpoint for main.main in the Go program object hello2, complete the following steps:
- Expand the Go program object.
- Expand the main compile unit.
- Expand the source file where the main function is defined.
- 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.
- For programs complied with IBM Open Enterprise SDK for Go 1.20, due to the compiler's code generation change, the debugger might stop in the Go runtime routine instead of stepping into a function properly. The work around is to set an entry breakpoint in the function that is called.