From 99b724f4542f4d9fb4a2ceacbbd2a6d9367dc0f6 Mon Sep 17 00:00:00 2001 From: Sean Liao Date: Fri, 21 Mar 2025 23:23:50 +0000 Subject: [PATCH] cmd/go: document purego convention Fixes #23172 Change-Id: I854e399471dfa22e62fbdec9719e561c4501e5ac Reviewed-on: https://go-review.googlesource.com/c/go/+/660136 Reviewed-by: Michael Matloob LUCI-TryBot-Result: Go LUCI Reviewed-by: Michael Matloob Reviewed-by: Filippo Valsorda Reviewed-by: Michael Knyszek --- src/cmd/go/alldocs.go | 6 ++++++ src/cmd/go/internal/help/helpdoc.go | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index 46bca7480b7..1029d1e8c2e 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 ab04ce001c4..1d3ffefc975 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.