mirror of
https://github.com/golang/go
synced 2024-09-05 07:54:46 +00:00
doc/go1.17: clarify Modules changes
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:
parent
70546f6404
commit
63b968f4f8
|
@ -134,35 +134,54 @@ Do not send CLs removing the interior tags from such phrases.
|
||||||
|
|
||||||
<h3 id="go-command">Go command</h3>
|
<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 -->
|
<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
|
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,
|
<code>go.mod</code> file, its <codeg>go.mod</code> file now contains an
|
||||||
avoiding the need to download or read <code>go.mod</code> files for
|
explicit <a href="/ref/mod#go-mod-file-require"><code>require</code>
|
||||||
otherwise-irrelevant dependencies. To support lazy loading, in Go 1.17 modules
|
directive</a> for every module that provides a transitively-imported package.
|
||||||
the <code>go</code> command maintains <em>explicit</em> requirements in
|
(In previous versions, the <code>go.mod</code> file typically only included
|
||||||
the <code>go.mod</code> file for every dependency that provides any package
|
explicit requirements for <em>directly</em>-imported packages.)
|
||||||
transitively imported by any package or test within the module.
|
<p>
|
||||||
See <a href="https://golang.org/design/36460-lazy-module-loading">the design
|
|
||||||
document</a> for more detail.
|
<p>
|
||||||
<!-- TODO(bcmills): replace the design-doc link with proper documentation. -->
|
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>
|
||||||
|
|
||||||
<p><!-- golang.org/issue/45965 -->
|
<p><!-- golang.org/issue/45965 -->
|
||||||
Because the number of additional explicit requirements in the go.mod file may
|
Because the number of explicit requirements may be substantially larger in an
|
||||||
be substantial, in a Go 1.17 module the newly-added requirements
|
expanded Go 1.17 <code>go.mod</code> file, the newly-added requirements
|
||||||
on <em>indirect</em> dependencies are maintained in a
|
on <em>indirect</em> dependencies in a <code>go</code> <code>1.17</code>
|
||||||
separate <code>require</code> block from the block containing direct
|
module are maintained in a separate <code>require</code> block from the block
|
||||||
dependencies.
|
containing direct dependencies.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p><!-- golang.org/issue/45094 -->
|
<p><!-- golang.org/issue/45094 -->
|
||||||
To facilitate the upgrade to lazy loading, the
|
To facilitate the upgrade to Go 1.17 pruned module graphs, the
|
||||||
<code>go</code> <code>mod</code> <code>tidy</code> subcommand now supports
|
<a href="/ref/mod#go-mod-tidy"><code>go</code> <code>mod</code> <code>tidy</code></a>
|
||||||
a <code>-go</code> flag to set or change the <code>go</code> version in
|
subcommand now supports a <code>-go</code> flag to set or change
|
||||||
the <code>go.mod</code> file. To enable lazy loading for an existing module
|
the <code>go</code> version in the <code>go.mod</code> file. To convert
|
||||||
without changing the selected versions of its dependencies, run:
|
the <code>go.mod</code> file for an existing module to Go 1.17 without
|
||||||
|
changing the selected versions of its dependencies, run:
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<pre>
|
<pre>
|
||||||
|
@ -199,10 +218,10 @@ Do not send CLs removing the interior tags from such phrases.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p><!-- golang.org/issue/46366 -->
|
<p><!-- golang.org/issue/46366 -->
|
||||||
The <code>go</code> <code>mod</code> <code>graph</code> subcommand also
|
The <a href="/ref/mod#go-mod-graph"><code>go</code> <code>mod</code> <code>graph</code></a>
|
||||||
supports the <code>-go</code> flag, which causes it to report the graph as
|
subcommand also supports the <code>-go</code> flag, which causes it to report
|
||||||
seen by the indicated Go version, showing dependencies that may otherwise be
|
the graph as seen by the indicated Go version, showing dependencies that may
|
||||||
pruned out by lazy loading.
|
otherwise be pruned out.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h4 id="module-deprecation-comments">Module deprecation comments</h4>
|
<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 -->
|
<p><!-- golang.org/issue/36876 -->
|
||||||
If the main module specifies <code>go</code> <code>1.17</code> or higher,
|
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
|
<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
|
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.
|
version is used when building the module's packages from vendored source code.
|
||||||
|
|
Loading…
Reference in a new issue