diff --git a/doc/go1.16.html b/doc/go1.16.html index e0187effd7b..2ff763f9b62 100644 --- 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.

+

The -overlay flag

+ +

+ The -overlay flag specifies a JSON configuration file containing + a set of file path replacements. The -overlay flag may be used + with all build commands and go mod 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 go + 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. +

+

Cgo

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index daa407197c6..c4913ce6954 100644 --- 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 21b2289dff2..be5532d7aae 100644 --- 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,