Skip to content

Commit

Permalink
_content/ref/mod: update terminology for Go 1.17 changes
Browse files Browse the repository at this point in the history 
For golang/go#47397

Change-Id: I7046bddb17bdd7957603e16580e7c9bab4a8c05a
Reviewed-on: https://go-review.googlesource.com/c/website/+/339991
Trust: Bryan C. Mills <[email protected]>
Run-TryBot: Bryan C. Mills <[email protected]>
TryBot-Result: Go Bot <[email protected]>
Reviewed-by: Jay Conrod <[email protected]>
  • Loading branch information
Bryan C. Mills committed Aug 6, 2021
1 parent 0c3ebd1 commit 06ce489
Show file tree
Hide file tree
Showing 2 changed files with 73 additions and 73 deletions.
6 changes: 3 additions & 3 deletions _content/doc/modules/gomod-ref.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -183,9 +183,9 @@ specified by the `go` directive. This has the following effects:
package transitively imported by a package or test in the main module. (At
`go 1.16` and lower, an indirect dependency is included only if [minimal
version selection](/ref/mod#minimal-version-selection) would otherwise
select a different version.) This extra information enables [lazy
loading](/ref/mod#lazy-loading) and [module graph
pruning](/ref/mod#graph-pruning).
select a different version.) This extra information enables [module graph
pruning](/ref/mod#graph-pruning) and [lazy module
loading](/ref/mod#lazy-loading).
* Because there may be many more `// indirect` dependencies than in previous
`go` versions, indirect dependencies are recorded in a separate block
within the `go.mod` file.
Expand Down
140 changes: 70 additions & 70 deletions _content/ref/mod.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -571,7 +571,8 @@ specified by the `go` directive. This has the following effects:
1.16` and lower, an [indirect dependency](#glos-direct-dependency) is
included only if [minimal version selection](#minimal-version-selection)
would otherwise select a different version.) This extra information enables
[lazy loading](#lazy-loading) and [module graph pruning](#graph-pruning).
[module graph pruning](#graph-pruning) and [lazy module
loading](#lazy-loading).
* Because there may be many more `// indirect` dependencies than in previous
`go` versions, indirect dependencies are recorded in a separate block
within the `go.mod` file.
Expand All @@ -580,7 +581,7 @@ specified by the `go` directive. This has the following effects:
subdirectories of `vendor` to identify the correct main module.)
* `go mod vendor` records the `go` version from each dependency's `go.mod`
file in `vendor/modules.txt`.
<!-- If you update this list, also update /doc/modules/gomod-ref#go. -->
<!-- If you update this list, also update /doc/modules/gomod-ref#go-notes. -->

A `go.mod` file may contain at most one `go` directive. Most commands will add a
`go` directive with the current Go version if one is not present.
Expand Down Expand Up @@ -620,9 +621,11 @@ requirement in its own `go.mod` file (such as a dependency that lacks a `go.mod`
file altogether).

At `go 1.17` and above, the `go` command adds an indirect requirement for each
module that provides a package transitively imported by any package or test in
the main module. These extra requirements enable [lazy loading](#lazy-loading)
and [module graph pruning](#graph-pruning).
module that provides any package imported (even
[indirectly](#glos-indirect-dependency)) by a package or test in the main module
or passed as an argument to `go get`. These more comprehensive requirements
enable [module graph pruning](#graph-pruning) and [lazy module
loading](#lazy-loading).

```
RequireDirective = "require" ( RequireSpec | "(" newline { RequireSpec } ")" newline ) .
Expand Down Expand Up @@ -835,6 +838,8 @@ For example, consider this `go.mod` file:
```
module example.com/M
go 1.16
require (
example.com/A v1
example.com/B v1.0.0
Expand Down Expand Up @@ -989,62 +994,25 @@ is changed to 1.1.
suffix after an argument. This works similarly to a downgrade. All versions
of the named module are removed from the module graph.

## Module graph redundancy {#graph-redundancy}

In a module with a [`go` directive](#go-mod-file-go) at `go 1.17` or higher, the
`go.mod` file is expected to include an explicit [`require`
directive](#go-mod-file-require) to the `go.mod` file for the [selected
version](#glos-selected-version) of every module that provides any package
imported (even [indirectly](#glos-indirect-dependency)) by a package or test in
the [main module](#glos-main-module).

When the `go` command loads packages it makes a best effort to check and
maintain this property: [`go mod tidy`](#go-mod-tidy) adds indirect requirements
for all packages imported by the main module, and [`go get`](#go-get) adds
indirect requirements for the packages imported by those named on the command
line.

A module that _does not_ provide any imported package cannot affect the compiled
artifacts produced by `go build` and `go test`, so this added redundancy allows
packages in the main module to be built and tested using only the requirements
listed in the its own `go.mod` file. The `go` command takes advantage of that
property to substantially reduce the size of the overall module graph.

(At `go 1.16` and below, the `go.mod` file includes only [direct
dependencies](#glos-direct-dependency), so a much larger graph must be loaded to
ensure that all indirect dependencies are included.)

See [the design document](/design/36460-lazy-module-loading) for more detail.

### Lazy loading {#lazy-loading}

If the main module is at `go 1.17` or higher, the `go` command avoids loading
the complete module graph until (and unless) it is needed. Instead, it loads
only the main module's `go.mod` file, then attempts to load the packages to be
built using only those requirements. If a package to be imported (for example, a
dependency of a test for a package outside the main module) is not found among
those requirements, then the rest of the module graph is loaded on demand.

If all packages can be found without loading the full module graph, the `go`
command then loads the `go.mod` files for _only_ the modules containing those
packages, and their requirements are checked against the requirements of the
main module to ensure that they are locally consistent. (Inconsistencies can
arise due to version-control merges, hand-edits, and changes in modules that
have been [replaced](#go-mod-file-replace) using local filesystem paths.)

### Module graph pruning {#graph-pruning}
## Module graph pruning {#graph-pruning}

If the main module is at `go 1.17` or higher, the [module
graph](#glos-module-graph) used for [minimal version
selection](#minimal-version-selection) includes only the _immediate_ (not
transitive) requirements for each module dependency that specifies `go 1.17` or
higher in its own `go.mod` file, unless that version of the module is also
(transitively) required by some _other_ dependency at `go 1.16` or below.

Since a `go 1.17` `go.mod` file includes every dependency needed to build any
package or test in that module, the pruned module graph includes every
dependency needed to `go build` or `go test` the packages in every dependency
explicitly [required](#go-mod-file-require) by the main module.
selection](#minimal-version-selection) includes only the _immediate_
requirements for each module dependency that specifies `go 1.17` or higher in
its own `go.mod` file, unless that version of the module is also (transitively)
required by some _other_ dependency at `go 1.16` or below. (The _transitive_
dependencies of `go 1.17` dependencies are _pruned out_ of the module graph.)

Since a `go 1.17` `go.mod` file includes a [require
directive](#go-mod-file-require) for every dependency needed to build any
package or test in that module, the pruned module graph includes all of the
dependencies needed to `go build` or `go test` the packages in any dependency
explicitly required by the [main module](#glos-main-module). A module that is
_not_ needed to build any package or test in a given module cannot affect the
run-time behavior of its packages, so the dependencies that are pruned out of
the module graph would only cause interference between otherwise-unrelated
modules.

Modules whose requirements have been pruned out still appear in the module graph
and are still reported by `go list -m all`: their [selected
Expand All @@ -1058,10 +1026,11 @@ named package to an explicit dependency, allowing `go build` or `go test` to be
invoked on that package.

Because Go 1.16 and earlier did not support module graph pruning, the full
transitive closure of dependencies — including transitive `go 1.17` dependencies
— is still included for each module that specifies `go 1.16` or lower. (The
`go.mod` file for a `go 1.16` or lower module does not necessarily include the
requirements needed to build the packages and tests in that module.)
transitive closure of dependencies — including transitive `go 1.17`
dependencies — is still included for each module that specifies `go 1.16` or
lower. (At `go 1.16` and below, the `go.mod` file includes only
[direct dependencies](#glos-direct-dependency), so a much larger graph must be
loaded to ensure that all indirect dependencies are included.)

The [`go.sum` file](#go-sum-files) recorded by [`go mod tidy`](#go-mod-tidy) for
a module by default includes checksums needed by the Go version _one below_ the
Expand All @@ -1072,6 +1041,26 @@ module graph loaded by Go 1.17. The `-compat` flag can be used to override the
default version (for example, to prune the `go.sum` file more aggressively in a
`go 1.17` module).

See [the design document](/design/36460-lazy-module-loading) for more detail.

### Lazy module loading {#lazy-loading}

The more comprehensive requirements added for module graph pruning also enable
another optimization when working within a module. If the main module is at
`go 1.17` or higher, the `go` command avoids loading the complete module graph
until (and unless) it is needed. Instead, it loads only the main module's
`go.mod` file, then attempts to load the packages to be built using only those
requirements. If a package to be imported (for example, a dependency of a test
for a package outside the main module) is not found among those requirements,
then the rest of the module graph is loaded on demand.

If all imported packages can be found without loading the module graph, the
`go` command then loads the `go.mod` files for _only_ the modules containing
those packages, and their requirements are checked against the requirements of
the main module to ensure that they are locally consistent. (Inconsistencies can
arise due to version-control merges, hand-edits, and changes in modules that
have been [replaced](#go-mod-file-replace) using local filesystem paths.)

## Compatibility with non-module repositories {#non-module-compat}

To ensure a smooth transition from `GOPATH` to modules, the `go` command can
Expand Down Expand Up @@ -1927,12 +1916,12 @@ imported by other packages.

Once `go mod tidy` has loaded this set of packages, it ensures that each module
that provides one or more packages has a `require` directive in the main
module's `go.mod` file or, if the main module is at `go 1.16` or below (see
[Module graph redundancy](#graph-redundancy)), is required by another required
module. `go mod tidy` will add a requirement on the latest version on each
missing module (see [Version queries](#version-queries) for the definition of
the `latest` version). `go mod tidy` will remove `require` directives for
modules that don't provide any packages in the set described above.
module's `go.mod` file or — if the main module is at `go 1.16` or below — is
required by another required module. `go mod tidy` will add a requirement on the
latest version of each missing module (see [Version queries](#version-queries)
for the definition of the `latest` version). `go mod tidy` will remove `require`
directives for modules that don't provide any packages in the set described
above.

`go mod tidy` may also add or remove `// indirect` comments on `require`
directives. An `// indirect` comment denotes a module that does not provide a
Expand All @@ -1942,8 +1931,9 @@ dependencies and comments are added.)

If the `-go` flag is set, `go mod tidy` will update the [`go`
directive](#go-mod-file-go) to the indicated version, enabling or disabling
[lazy loading](#lazy-loading) and [module graph pruning](#graph-pruning) (and
adding or removing indirect requirements as needed) according to that version.
[module graph pruning](#graph-pruning) and [lazy module loading](#lazy-loading)
(and adding or removing indirect requirements as needed) according to that
version.

By default, `go mod tidy` will check that the [selected
versions](#glos-selected-version) of modules do not change when the module graph
Expand Down Expand Up @@ -4062,6 +4052,11 @@ or a module that appears in the [module graph](#glos-module-graph) but does not
provide any package directly imported by the main module.
(Compare [direct dependency](#glos-direct-dependency).)

<a id="glos-lazy-module-loading"></a>
**lazy module loading:** A change in Go 1.17 that avoids loading the [module
graph](#glos-module-graph) for commands that do not need it in modules that
specify `go 1.17` or higher. See [Lazy module loading](#lazy-loading).

<a id="glos-main-module"></a>
**main module:** The module in which the `go` command is invoked. The main
module is defined by a [`go.mod` file](#glos-go-mod-file) in the current
Expand Down Expand Up @@ -4113,6 +4108,11 @@ module](#glos-main-module). Each vertex in the graph is a module; each edge is a
version from a `require` statement in a `go.mod` file (subject to `replace` and
`exclude` statements in the main module's `go.mod` file.

<a id="glos-module-graph-pruning"></a>
**module graph pruning:** A change in Go 1.17 that reduces the size of the
module graph by omitting transitive dependencies of modules that specify `go
1.17` or higher. See [Module graph pruning](#graph-pruning).

<a id="glos-module-path"></a>
**module path:** A path that identifies a module and acts as a prefix for
package import paths within the module. For example, `"golang.org/x/net"`.
Expand Down

0 comments on commit 06ce489

Please sign in to comment.