From: Keith Randall <khr@golang.org>
Date: Wed, 16 Apr 2025 20:50:44 +0000 (-0700)
Subject: doc: mention stack allocation of variable-sized make calls
X-Git-Tag: go1.25rc1~79
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=aec96d686be16fda519f6fd4a6e3bbfe3454c0b9;p=gostls13.git

doc: mention stack allocation of variable-sized make calls

Also mention the bisect tool and flag used to track down
incorrect uses.

Change-Id: Id36a236e1bb2733b8611b22a5b16916e7d9f5522
Reviewed-on: https://go-review.googlesource.com/c/go/+/666075
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Keith Randall <khr@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
---

diff --git a/doc/next/5-toolchain.md b/doc/next/5-toolchain.md
index c270e9dfc9..3708700c93 100644
--- a/doc/next/5-toolchain.md
+++ b/doc/next/5-toolchain.md
@@ -38,6 +38,18 @@ successfully in Go 1.25. If this change is affecting your code, the solution is
 the non-nil error check earlier in your code, preferably immediately after
 the error-generating statement.
 
+<!-- CLs 653856, 657937, 663795, TBD 664299 -->
+
+The compiler can now allocate the backing store for slices on the
+stack in more situations, which improves performance. This change has
+the potential to amplify the effects of incorrect
+[unsafe.Pointer](/pkg/unsafe#Pointer) usage, see for example [issue
+73199](/issue/73199). In order to track down these problems, the
+[bisect tool](https://pkg.go.dev/golang.org/x/tools/cmd/bisect) can be
+used to find the allocation causing trouble using the
+`-compile=variablemake` flag. All such new stack allocations can also
+be turned off using `-gcflags=all=-d=variablemakehash=n`.
+
 ## Assembler {#assembler}
 
 ## Linker {#linker}