From a44c3edbe0aafb509a175dfe0918bd17863bc97c Mon Sep 17 00:00:00 2001 From: Jay Conrod Date: Fri, 3 May 2019 18:06:41 -0400 Subject: [PATCH] all: document vendoring in the standard library Added documentation that explains special cases for vendored packages in the standard library and provides instructions for updating vendor directories. Fixes #31806 Change-Id: Ib697ed18eae28023ab0bfb9f4d250992c393571d Reviewed-on: https://go-review.googlesource.com/c/go/+/174999 Reviewed-by: Bryan C. Mills --- src/README.vendor | 54 +++++++++++++++++++++++++++++++++++++++++++ src/cmd/README.vendor | 2 ++ 2 files changed, 56 insertions(+) create mode 100644 src/README.vendor create mode 100644 src/cmd/README.vendor diff --git a/src/README.vendor b/src/README.vendor new file mode 100644 index 0000000000..c80265344e --- /dev/null +++ b/src/README.vendor @@ -0,0 +1,54 @@ +Vendoring in std and cmd +======================== + +The Go command maintains copies of external packages needed by the +standard library in the src/vendor and src/cmd/vendor directories. + +In GOPATH mode, imports of vendored packages are resolved to these +directories following normal vendor directory logic +(see golang.org/s/go15vendor). + +In module mode, std and cmd are modules (defined in src/go.mod and +src/cmd/go.mod). When a package outside std or cmd is imported +by a package inside std or cmd, the import path is interpreted +as if it had a "vendor/" prefix. For example, within "crypto/tls", +an import of "golang.org/x/crypto/cryptobyte" resolves to +"vendor/golang.org/x/crypto/cryptobyte". When a package with the +same path is imported from a package outside std or cmd, it will +be resolved normally. Consequently, a binary may be built with two +copies of a package at different versions if the package is +imported normally and vendored by the standard library. + +Vendored packages are internally renamed with a "vendor/" prefix +to preserve the invariant that all packages have distinct paths. +This is necessary to avoid compiler and linker conflicts. Adding +a "vendor/" prefix also maintains the invariant that standard +library packages begin with a dotless path element. + +The module requirements of std and cmd do not influence version +selection in other modules. They are only considered when running +module commands like 'go get' and 'go mod vendor' from a directory +in GOROOT/src. + +Maintaining vendor directories +============================== + +Before updating vendor directories, ensure that module mode is enabled. +Make sure GO111MODULE=off is not set ('on' or 'auto' should work). + +Requirements may be added, updated, and removed with 'go get'. +The vendor directory may be updated with 'go mod vendor'. +A typical sequence might be: + + cd src + go get -m golang.org/x/net@latest + go mod tidy + go mod vendor + +Use caution when passing '-u' to 'go get'. The '-u' flag updates +modules providing all transitively imported packages, not just +the target module. + +Note that 'go mod vendor' only copies packages that are transitively +imported by packages in the current module. If a new package is needed, +it should be imported before running 'go mod vendor'. diff --git a/src/cmd/README.vendor b/src/cmd/README.vendor new file mode 100644 index 0000000000..ac0df5e925 --- /dev/null +++ b/src/cmd/README.vendor @@ -0,0 +1,2 @@ +See src/README.vendor for information on loading vendored packages +and updating the vendor directory. -- 2.50.0