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 46bca7480b70a48151b96880e545fe43cd5bd747..1029d1e8c2e63f3227cc03d6dbe20eb2ae6f34f4 100644 (file)
--- 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 ab04ce001c41db3724ee818f5b14188cc9b4f603..1d3ffefc9752057729757be850f3cf0a1bdefb5f 100644 (file)
--- 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.