languages/go
languages/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-07-19 19:44:12 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc/go1.17: clarify Modules changes

Browse source 
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 <bcmills@google.com>
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Jay Conrod <jayconrod@google.com>
This commit is contained in:
Bryan C. Mills 2021-07-16 16:51:11 -04:00
parent 70546f6404
commit 63b968f4f8
1 changed files with 45 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
doc/go1.17.html
View file

@ -134,35 +134,54 @@ Do not send CLs removing the interior tags from such phrases.
<h3 id="go-command">Go command</h3>
<h4 id="lazy-loading">Lazy module loading</h4>
<a id="lazy-loading"><!-- for existing links only --></a>
<h4 id="graph-pruning">Pruned module graphs in <code>go 1.17</code> modules</h4>
<p><!-- golang.org/issue/36460 -->
If a module specifies <code>go</code> <code>1.17</code> or higher, the module
graph includes only the <em>immediate</em> dependencies of
other <code>go</code> <code>1.17</code> modules, not their full transitive
dependencies. (See <a href="/ref/mod#graph-pruning">Module graph pruning</a>
for more detail.)
</p>
<p>
For the <code>go</code> command to correctly resolve transitive imports using
the pruned module graph, the <code>go.mod</code> file for each module needs to
include more detail about the transitive dependencies relevant to that module.
If a module specifies <code>go</code> <code>1.17</code> or higher in its
<code>go.mod</code> file, its transitive requirements are now loaded lazily,
avoiding the need to download or read <code>go.mod</code> files for
otherwise-irrelevant dependencies. To support lazy loading, in Go 1.17 modules
the <code>go</code> command maintains <em>explicit</em> requirements in
the <code>go.mod</code> file for every dependency that provides any package
transitively imported by any package or test within the module.
See <a href="https://golang.org/design/36460-lazy-module-loading">the design
document</a> for more detail.
<!-- TODO(bcmills): replace the design-doc link with proper documentation. -->
<code>go.mod</code> file, its <codeg>go.mod</code> file now contains an
explicit <a href="/ref/mod#go-mod-file-require"><code>require</code>
directive</a> for every module that provides a transitively-imported package.
(In previous versions, the <code>go.mod</code> file typically only included
explicit requirements for <em>directly</em>-imported packages.)
<p>
<p>
Since the expanded <code>go.mod</code> 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
<code>go</code> <code>1.17</code> or higher the <code>go</code> tool no longer
reads (or even downloads) <code>go.mod</code> files for dependencies if they
are not needed in order to complete the requested command.
(See <a href="/ref/mod#lazy-loading">Lazy loading</a>.)
</p>
<p><!-- golang.org/issue/45965 -->
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 <em>indirect</em> dependencies are maintained in a
separate <code>require</code> block from the block containing direct
dependencies.
Because the number of explicit requirements may be substantially larger in an
expanded Go 1.17 <code>go.mod</code> file, the newly-added requirements
on <em>indirect</em> dependencies in a <code>go</code> <code>1.17</code>
module are maintained in a separate <code>require</code> block from the block
containing direct dependencies.
</p>
<p><!-- golang.org/issue/45094 -->
To facilitate the upgrade to lazy loading, the
<code>go</code> <code>mod</code> <code>tidy</code> subcommand now supports
a <code>-go</code> flag to set or change the <code>go</code> version in
the <code>go.mod</code> 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
<a href="/ref/mod#go-mod-tidy"><code>go</code> <code>mod</code> <code>tidy</code></a>
subcommand now supports a <code>-go</code> flag to set or change
the <code>go</code> version in the <code>go.mod</code> file. To convert
the <code>go.mod</code> file for an existing module to Go 1.17 without
changing the selected versions of its dependencies, run:
</p>
<pre>
@ -199,10 +218,10 @@ Do not send CLs removing the interior tags from such phrases.
</p>
<p><!-- golang.org/issue/46366 -->
The <code>go</code> <code>mod</code> <code>graph</code> subcommand also
supports the <code>-go</code> 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 <a href="/ref/mod#go-mod-graph"><code>go</code> <code>mod</code> <code>graph</code></a>
subcommand also supports the <code>-go</code> flag, which causes it to report
the graph as seen by the indicated Go version, showing dependencies that may
otherwise be pruned out.
</p>
<h4 id="module-deprecation-comments">Module deprecation comments</h4>
@ -270,7 +289,8 @@ Do not send CLs removing the interior tags from such phrases.
<p><!-- golang.org/issue/36876 -->
If the main module specifies <code>go</code> <code>1.17</code> or higher,
<code>go</code> <code>mod</code> <code>vendor</code> now annotates
<a href="/ref/mod#go-mod-vendor"><code>go</code> <code>mod</code> <code>vendor</code></a>
now annotates
<code>vendor/modules.txt</code> with the <code>go</code> version indicated by
each vendored module in its own <code>go.mod</code> file. The annotated
version is used when building the module's packages from vendored source code.