From 63b968f4f86f4c23ce92b7ac2feda4fc7ca17c8e Mon Sep 17 00:00:00 2001 From: "Bryan C. Mills" Date: Fri, 16 Jul 2021 16:51:11 -0400 Subject: [PATCH] doc/go1.17: clarify Modules changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Writing CL 333629 clarified my thinking about the behavioral changes associated with lazy loading. There are really two interrelated changes — graph pruning, and lazy loading proper — that are both made possible by the added redundancy in the go.mod file. (I had initially approached the whole cluster of features as “lazy loading” because that was the starting point for the design. Graph pruning came into the picture when we looked at how to bound the worst-case behavior of lazy loading, but it is really the more important of the two aspects of the design.) Note that this change adds links to doc anchors added in CL 333629. Fixes #36460 Fixes #47397 Change-Id: I0ef4af57f647bf5ee210ea7099191fb4befa2cc1 Reviewed-on: https://go-review.googlesource.com/c/go/+/335135 Trust: Bryan C. Mills Run-TryBot: Bryan C. Mills TryBot-Result: Go Bot Reviewed-by: Jay Conrod --- doc/go1.17.html | 70 +++++++++++++++++++++++++++++++------------------ 1 file changed, 45 insertions(+), 25 deletions(-) diff --git a/doc/go1.17.html b/doc/go1.17.html index 48811e6b679..a8307bacac2 100644 --- a/doc/go1.17.html +++ b/doc/go1.17.html @@ -134,35 +134,54 @@ Do not send CLs removing the interior tags from such phrases.

Go command

-

Lazy module loading

+ +

Pruned module graphs in go 1.17 modules

+ If a module specifies go 1.17 or higher, the module + graph includes only the immediate dependencies of + other go 1.17 modules, not their full transitive + dependencies. (See Module graph pruning + for more detail.) +

+ +

+ For the go command to correctly resolve transitive imports using + the pruned module graph, the go.mod file for each module needs to + include more detail about the transitive dependencies relevant to that module. If a module specifies go 1.17 or higher in its - go.mod file, its transitive requirements are now loaded lazily, - avoiding the need to download or read go.mod files for - otherwise-irrelevant dependencies. To support lazy loading, in Go 1.17 modules - the go command maintains explicit requirements in - the go.mod file for every dependency that provides any package - transitively imported by any package or test within the module. - See the design - document for more detail. - + go.mod file, its go.mod file now contains an + explicit require + directive for every module that provides a transitively-imported package. + (In previous versions, the go.mod file typically only included + explicit requirements for directly-imported packages.) +

+ +

+ Since the expanded go.mod file needed for module graph pruning + includes all of the dependencies needed to load the imports of any package in + the main module, if the main module specifies + go 1.17 or higher the go tool no longer + reads (or even downloads) go.mod files for dependencies if they + are not needed in order to complete the requested command. + (See Lazy loading.)

- Because the number of additional explicit requirements in the go.mod file may - be substantial, in a Go 1.17 module the newly-added requirements - on indirect dependencies are maintained in a - separate require block from the block containing direct - dependencies. + Because the number of explicit requirements may be substantially larger in an + expanded Go 1.17 go.mod file, the newly-added requirements + on indirect dependencies in a go 1.17 + module are maintained in a separate require block from the block + containing direct dependencies.

- To facilitate the upgrade to lazy loading, the - go mod tidy subcommand now supports - a -go flag to set or change the go version in - the go.mod file. To enable lazy loading for an existing module - without changing the selected versions of its dependencies, run: + To facilitate the upgrade to Go 1.17 pruned module graphs, the + go mod tidy + subcommand now supports a -go flag to set or change + the go version in the go.mod file. To convert + the go.mod file for an existing module to Go 1.17 without + changing the selected versions of its dependencies, run: 

@@ -199,10 +218,10 @@ Do not send CLs removing the interior tags from such phrases.
 

 
 

-  The go mod graph subcommand also
-  supports the -go flag, which causes it to report the graph as
-  seen by the indicated Go version, showing dependencies that may otherwise be
-  pruned out by lazy loading.
+  The go mod graph
+  subcommand also supports the -go flag, which causes it to report
+  the graph as seen by the indicated Go version, showing dependencies that may
+  otherwise be pruned out.
 

 
 
Module deprecation comments

@@ -270,7 +289,8 @@ Do not send CLs removing the interior tags from such phrases.
 
 

   If the main module specifies go 1.17 or higher,
-  go mod vendor now annotates
+  go mod vendor
+  now annotates
   vendor/modules.txt with the go version indicated by
   each vendored module in its own go.mod file. The annotated
   version is used when building the module's packages from vendored source code.