Support debugging via gdb or similar

[aherrmann]

Zig can build binaries with debug symbols compatible with common debuggers like gdb. The embedded debug information includes references to the relevant source file paths to allow the debugger to display source listings. These source file paths are currently set to absolute paths to the build directory. This is incorrect in most cases, as builds occur within Bazel's sandbox under a temporary working directory. E.g.

$ cd e2e/workspace
$ bazel run //simple-binary:binary --run_under=gdb
...
(gdb) l
1       main.zig: No such file or directory.
(gdb) info source
Current source file is main.zig
Compilation directory is /home/runner/.cache/bazel/_bazel_runner/bf578624e6d2c856d2af70bd6da49baf/sandbox/linux-sandbox/9/execroot/_main/simple-binary

The compilation directory refers to the temporary sandbox working directory which no longer exists at the time when gdb is executed.

Expected behavior

The produced binary should not refer to the temporary sandbox working directory, see #79. The produced binary should ideally contain source file references relative to the workspace root, so that gdb debugging works out of the box when initiated from within the project root. Either way, it should be clearly documented how to set the relevant source search paths to allow the debugger to find all relevant sources, including standard library sources and generated sources.

Workaround

A known workaround is to configure the debugger to remap the sandbox working directory prefix to the project root:

(gdb) set substitute-path /home/runner/.cache/bazel/_bazel_runner/bf578624e6d2c856d2af70bd6da49baf/sandbox/linux-sandbox/9/execroot/_main/external EXECROOT

Where EXECROOT should be replaced by the output of bazel info execution_root.

(gdb) l 1
1       const std = @import("std");
2
3       pub fn main() void {
4           std.io.getStdOut().writeAll(
5               "Hello World!\n",
6           ) catch unreachable;
7       }