Always write the binary to the mode specific directory

and create a symlink if "out" is specified.

This reduces cache invalidation on mode changes.

Author: mering

docs/go/core/rules.md

@@ -144,7 +144,7 @@ This builds an executable from a set of source files,
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="go_binary-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
-| <a id="go_binary-basename"></a>basename |  The basename of this binary. The binary                 basename may also be platform-dependent: on Windows, we add an .exe extension.   | String | optional | "" |
+| <a id="go_binary-basename"></a>basename |  The basename of this binary. The binary                 basename may also be platform-dependent: on Windows, we add an .exe extension.                 When not set, it will default to the label name.   | String | optional | "" |
 | <a id="go_binary-cdeps"></a>cdeps |  The list of other libraries that the c code depends on.                 This can be anything that would be allowed in [cc_library deps]                 Only valid if <code>cgo</code> = <code>True</code>.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | [] |
 | <a id="go_binary-cgo"></a>cgo |  If <code>True</code>, the package may contain [cgo] code, and <code>srcs</code> may contain                 C, C++, Objective-C, and Objective-C++ files and non-Go assembly files.                 When cgo is enabled, these files will be compiled with the C/C++ toolchain                 and included in the package. Note that this attribute does not force cgo                 to be enabled. Cgo is enabled for non-cross-compiling builds when a C/C++                 toolchain is configured.   | Boolean | optional | False |
 | <a id="go_binary-clinkopts"></a>clinkopts |  List of flags to add to the C link command.                 Subject to ["Make variable"] substitution and [Bourne shell tokenization].                 Only valid if <code>cgo</code> = <code>True</code>.   | List of strings | optional | [] |
@@ -164,7 +164,7 @@ This builds an executable from a set of source files,
 | <a id="go_binary-importpath"></a>importpath |  The import path of this binary. Binaries can't actually be imported, but this                 may be used by [go_path] and other tools to report the location of source                 files. This may be inferred from embedded libraries.   | String | optional | "" |
 | <a id="go_binary-linkmode"></a>linkmode |  Determines how the binary should be built and linked. This accepts some of                 the same values as `go build -buildmode` and works the same way.                 <br><br>                 <ul>                 <li>`auto` (default): Controlled by `//go/config:linkmode`, which defaults to `normal`.</li>                 <li>`normal`: Builds a normal executable with position-dependent code.</li>                 <li>`pie`: Builds a position-independent executable.</li>                 <li>`plugin`: Builds a shared library that can be loaded as a Go plugin. Only supported on platforms that support plugins.</li>                 <li>`c-shared`: Builds a shared library that can be linked into a C program.</li>                 <li>`c-archive`: Builds an archive that can be linked into a C program.</li>                 </ul>   | String | optional | "auto" |
 | <a id="go_binary-msan"></a>msan |  Controls whether code is instrumented for memory sanitization. May be one of                 <code>on</code>, <code>off</code>, or <code>auto</code>. Not available when cgo is                 disabled. In most cases, it's better to control this on the command line with                 <code>--@io_bazel_rules_go//go/config:msan</code>. See [mode attributes], specifically                 [msan].   | String | optional | "auto" |
-| <a id="go_binary-out"></a>out |  Sets the output filename for the generated executable. When set, <code>go_binary</code>                 will write this file without mode-specific directory prefixes, without                 linkmode-specific prefixes like "lib", and without platform-specific suffixes                 like ".exe". Note that without a mode-specific directory prefix, the                 output file (but not its dependencies) will be invalidated in Bazel's cache                 when changing configurations.   | String | optional | "" |
+| <a id="go_binary-out"></a>out |  Sets the output symlink filename for the generated executable.   | String | optional | "" |
 | <a id="go_binary-pgoprofile"></a>pgoprofile |  Provides a pprof file to be used for profile guided optimization when compiling go targets.                 A pprof file can also be provided via <code>--@io_bazel_rules_go//go/config:pgoprofile=&lt;label of a pprof file&gt;</code>.                 Profile guided optimization is only supported on go 1.20+.                 See https://go.dev/doc/pgo for more information.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | //go/config:empty |
 | <a id="go_binary-pure"></a>pure |  Controls whether cgo source code and dependencies are compiled and linked,                 similar to setting <code>CGO_ENABLED</code>. May be one of <code>on</code>, <code>off</code>,                 or <code>auto</code>. If <code>auto</code>, pure mode is enabled when no C/C++                 toolchain is configured or when cross-compiling. It's usually better to                 control this on the command line with                 <code>--@io_bazel_rules_go//go/config:pure</code>. See [mode attributes], specifically                 [pure].   | String | optional | "auto" |
 | <a id="go_binary-race"></a>race |  Controls whether code is instrumented for race detection. May be one of                 <code>on</code>, <code>off</code>, or <code>auto</code>. Not available when cgo is                 disabled. In most cases, it's better to control this on the command line with                 <code>--@io_bazel_rules_go//go/config:race</code>. See [mode attributes], specifically                 [race].   | String | optional | "auto" |

go/private/rules/binary.bzl

@@ -136,24 +136,31 @@ def _go_binary_impl(ctx):
     name = ctx.attr.basename
     if not name:
         name = ctx.label.name
-    executable = None
-    if ctx.attr.out:
-        # Use declare_file instead of attr.output(). When users set output files
-        # directly, Bazel warns them not to use the same name as the rule, which is
-        # the common case with go_binary.
-        executable = ctx.actions.declare_file(ctx.attr.out)
-    archive, executable, runfiles = go.binary(
+    archive, executable_binary, runfiles = go.binary(
         go,
         name = name,
         source = go_info,
         gc_linkopts = gc_linkopts(ctx),
         version_file = ctx.version_file,
         info_file = ctx.info_file,
-        executable = executable,
+        executable = None,
     )
     validation_output = archive.data._validation_output
     nogo_diagnostics = archive.data._nogo_diagnostics
 
+    if ctx.attr.out:
+        # Use declare_file instead of attr.output(). When users set output files
+        # directly, Bazel warns them not to use the same name as the rule, which is
+        # the common case with go_binary.
+        executable = ctx.actions.declare_file(ctx.attr.out)
+        ctx.actions.symlink(
+            output = executable,
+            target_file = executable_binary,
+            is_executable = True,
+        )
+    else:
+        executable = executable_binary
+
     providers = [
         archive,
         OutputGroupInfo(
@@ -305,15 +312,11 @@ def _go_binary_kwargs(go_cc_aspects = []):
             "basename": attr.string(
                 doc = """The basename of this binary. The binary
                 basename may also be platform-dependent: on Windows, we add an .exe extension.
+                When not set, it will default to the label name.
                 """,
             ),
             "out": attr.string(
-                doc = """Sets the output filename for the generated executable. When set, `go_binary`
-                will write this file without mode-specific directory prefixes, without
-                linkmode-specific prefixes like "lib", and without platform-specific suffixes
-                like ".exe". Note that without a mode-specific directory prefix, the
-                output file (but not its dependencies) will be invalidated in Bazel's cache
-                when changing configurations.
+                doc = """Sets the output symlink filename for the generated executable.
                 """,
             ),
             "cgo": attr.bool(