From: Sean Liao <sean@liao.dev>
Date: Fri, 21 Mar 2025 23:23:50 +0000 (+0000)
Subject: cmd/go: document purego convention
X-Git-Tag: go1.26rc1~409
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=99b724f454;p=gostls13.git

cmd/go: document purego convention

Fixes #23172

Change-Id: I854e399471dfa22e62fbdec9719e561c4501e5ac
Reviewed-on: https://go-review.googlesource.com/c/go/+/660136
Reviewed-by: Michael Matloob <matloob@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Michael Matloob <matloob@golang.org>
Reviewed-by: Filippo Valsorda <filippo@golang.org>
Reviewed-by: Michael Knyszek <mknyszek@google.com>
---

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 46bca7480b..1029d1e8c2 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -2190,6 +2190,12 @@
 // building the package for Windows; similarly, math_386.s will be included
 // only when building the package for 32-bit x86.
 //
+// By convention, packages with assembly implementations may provide a go-only
+// version under the "purego" build constraint. This does not limit the use of
+// cgo (use the "cgo" build constraint) or unsafe. For example:
+//
+//	//go:build purego
+//
 // Go versions 1.16 and earlier used a different syntax for build constraints,
 // with a "// +build" prefix. The gofmt command will add an equivalent //go:build
 // constraint when encountering the older syntax.
diff --git a/src/cmd/go/internal/help/helpdoc.go b/src/cmd/go/internal/help/helpdoc.go
index ab04ce001c..1d3ffefc97 100644
--- a/src/cmd/go/internal/help/helpdoc.go
+++ b/src/cmd/go/internal/help/helpdoc.go
@@ -1009,6 +1009,12 @@ Naming a file dns_windows.go will cause it to be included only when
 building the package for Windows; similarly, math_386.s will be included
 only when building the package for 32-bit x86.
 
+By convention, packages with assembly implementations may provide a go-only
+version under the "purego" build constraint. This does not limit the use of
+cgo (use the "cgo" build constraint) or unsafe. For example:
+
+        //go:build purego
+
 Go versions 1.16 and earlier used a different syntax for build constraints,
 with a "// +build" prefix. The gofmt command will add an equivalent //go:build
 constraint when encountering the older syntax.