From: Jay Conrod Date: Mon, 25 Nov 2019 19:38:34 +0000 (-0500) Subject: doc: add section on resolving packages to module reference doc X-Git-Tag: go1.14beta1~90 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=b11d02ef740091d15671a647f876142018613aa4;p=gostls13.git doc: add section on resolving packages to module reference doc Updates #33637 Change-Id: I3b4303479b44894442a04226cbf1f1e27dbb2fb7 Reviewed-on: https://go-review.googlesource.com/c/go/+/208779 Reviewed-by: Tyler Bui-Palsulich Reviewed-by: Bryan C. Mills --- diff --git a/doc/modules.md b/doc/modules.md index a0756ed861..caf5ac3f17 100644 --- a/doc/modules.md +++ b/doc/modules.md @@ -141,6 +141,72 @@ repositories](#compatibility-with-non-module-repositories) for more information. ### Resolving a package to a module +When the `go` command loads a package using a [package +path](#glos-package-path), it needs to determine which module provides the +package. + +The `go` command starts by searching the [build list](#glos-build-list) for +modules with paths that are prefixes of the package path. For example, if the +package `example.com/a/b` is imported, and the module `example.com/a` is in the +build list, the `go` command will check whether `example.com/a` contains the +package, in the directory `b`. At least one file with the `.go` extension must +be present in a directory for it to be considered a package. [Build +constraints](/pkg/go/build/#hdr-Build_Constraints) are not applied for this +purpose. If exactly one module in the build list provides the package, that +module is used. If two or more modules provide the package, an error is +reported. If no modules provide the package, the `go` command will attempt to +find a new module (unless the flags `-mod=readonly` or `-mod=vendor` are used, +in which case, an error is reported). + + + +When the `go` command looks up a new module for a package path, it checks the +`GOPROXY` environment variable, which is a comma-separated list of proxy URLs or +the keywords `direct` or `off`. A proxy URL indicates the `go` command should +contact a [module proxy](#glos-module-proxy) using the [`GOPROXY` +protocol](#goproxy-protocol). `direct` indicates that the `go` command should +[communicate with a version control system](#communicating-with-vcs). `off` +indicates that no communication should be attempted. The `GOPRIVATE` and +`GONOPROXY` [environment variables](#environment-variables) can also be used to +control this behavior. + +For each entry in the `GOPROXY` list, the `go` command requests the latest +version of each module path that might provide the package (that is, each prefix +of the package path). For each successfully requested module path, the `go` +command will download the module at the latest version and check whether the +module contains the requested package. If one or more modules contain the +requested package, the module with the longest path is used. If one or more +modules are found but none contain the requested package, an error is +reported. If no modules are found, the `go` command tries the next entry in the +`GOPROXY` list. If no entries are left, an error is reported. + +For example, suppose the `go` command is looking for a module that provides the +package `golang.org/x/net/html`, and `GOPROXY` is set to +`https://corp.example.com,https://proxy.golang.org`. The `go` command may make +the following requests: + +* To `https://corp.example.com/` (in parallel): + * Request for latest version of `golang.org/x/net/html` + * Request for latest version of `golang.org/x/net` + * Request for latest version of `golang.org/x` + * Request for latest version of `golang.org` +* To `https://proxy.golang.org/`, if all requests to `https://corp.example.com/` + have failed with 404 or 410: + * Request for latest version of `golang.org/x/net/html` + * Request for latest version of `golang.org/x/net` + * Request for latest version of `golang.org/x` + * Request for latest version of `golang.org` + +After a suitable module has been found, the `go` command will add a new +requirement with the new module's path and version to the main module's `go.mod` +file. This ensures that when the same package is loaded in the future, the same +module will be used at the same version. If the resolved package is not imported +by a package in the main module, the new requirement will have an `// indirect` +comment. + ## `go.mod` files