cmd/go: add documentation for the -overlay flag

Also add -overlay to the Go 1.16 release notes.

For #40700
Fixes #39958
Fixes #42893

Change-Id: Ifd397549e368b255e7b8800986cfa0563a942af5
Reviewed-on: https://go-review.googlesource.com/c/go/+/274714
Trust: Michael Matloob <matloob@golang.org>
Run-TryBot: Michael Matloob <matloob@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Jay Conrod <jayconrod@google.com>

diff --git a/doc/go1.16.html b/doc/go1.16.html
index e0187effd7b44ab77667c8add49e320356347a52..2ff763f9b628ee16cbbed068db3dd716b49b8a32 100644 (file)
--- a/doc/go1.16.html
+++ b/doc/go1.16.html
@@ -271,6 +271,20 @@ Do not send CLs removing the interior tags from such phrases.
   but without the extra step.
 </p>
 
+<h4 id="overlay-flag">The <code>-overlay</code> flag</h4>
+
+<p><!-- golang.org/issue/39958 -->
+  The <code>-overlay</code> flag specifies a JSON configuration file containing
+  a set of file path replacements. The <code>-overlay</code> flag may be used
+  with all build commands and <code>go</code> <code>mod</code> subcommands.
+  It is primarily intended to be used by editor tooling such as gopls to
+  understand the effects of unsaved changes to source files.  The config file
+  maps actual file paths to replacement file paths and the <code>go</code>
+  command and its builds will run as if the actual file paths exist with the
+  contents given by the replacement file paths, or don't exist if the replacement
+  file paths are empty.
+</p>
+
 <h3 id="cgo">Cgo</h3>
 
 <p><!-- CL 252378 -->

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index daa407197c619d58e88d963028e252bd9c9cc38a..c4913ce695456dca0988ffdf30fe40fe9d638098 100644 (file)
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -164,6 +164,17 @@
 //             directory, but it is not accessed. When -modfile is specified, an
 //             alternate go.sum file is also used: its path is derived from the
 //             -modfile flag by trimming the ".mod" extension and appending ".sum".
+//     -overlay file
+//             read a JSON config file that provides an overlay for build operations.
+//             The file is a JSON struct with a single field, named 'Replace', that
+//             maps each disk file path (a string) to its backing file path, so that
+//             a build will run as if the disk file path exists with the contents
+//             given by the backing file paths, or as if the disk file path does not
+//             exist if its backing file path is empty. Support for the -overlay flag
+//             has some limitations:importantly, cgo files included from outside the
+//             include path must be  in the same directory as the Go package they are
+//             included from, and overlays will not appear when binaries and tests are
+//             run through go run and go test respectively.
 //     -pkgdir dir
 //             install and load all packages from dir instead of the usual locations.
 //             For example, when building with a non-standard configuration,

diff --git a/src/cmd/go/internal/work/build.go b/src/cmd/go/internal/work/build.go
index 21b2289dff2be567c1cad92ac32e9303d5b9a290..be5532d7aae750faaa33c89cc77461a3ff88b92c 100644 (file)
--- a/src/cmd/go/internal/work/build.go
+++ b/src/cmd/go/internal/work/build.go
@@ -124,6 +124,17 @@ and test commands:
                directory, but it is not accessed. When -modfile is specified, an
                alternate go.sum file is also used: its path is derived from the
                -modfile flag by trimming the ".mod" extension and appending ".sum".
+       -overlay file
+               read a JSON config file that provides an overlay for build operations.
+               The file is a JSON struct with a single field, named 'Replace', that
+               maps each disk file path (a string) to its backing file path, so that
+               a build will run as if the disk file path exists with the contents
+               given by the backing file paths, or as if the disk file path does not
+               exist if its backing file path is empty. Support for the -overlay flag
+               has some limitations:importantly, cgo files included from outside the
+               include path must be  in the same directory as the Go package they are
+               included from, and overlays will not appear when binaries and tests are
+               run through go run and go test respectively.
        -pkgdir dir
                install and load all packages from dir instead of the usual locations.
                For example, when building with a non-standard configuration,