diff options
author | Russ Cox <rsc@golang.org> | 2018-07-18 13:30:33 -0400 |
---|---|---|
committer | Russ Cox <rsc@golang.org> | 2018-07-19 18:16:05 +0000 |
commit | 95c3348344de688bbb9aba5474a612442e7d36ad (patch) | |
tree | 9a3bf0b4271bd4db19025c379ec18424a791f42e | |
parent | dada467fc688ef5970bf4af30c2644c0d2ccdb54 (diff) | |
download | go-95c3348344de688bbb9aba5474a612442e7d36ad.tar.gz go-95c3348344de688bbb9aba5474a612442e7d36ad.zip |
cmd/go: generate alldocs.go
Change-Id: I5a82aec66332f52e304f647758221b5f30b4e2b6
Reviewed-on: https://go-review.googlesource.com/124701
Reviewed-by: Bryan C. Mills <bcmills@google.com>
-rw-r--r-- | src/cmd/go/alldocs.go | 842 |
1 files changed, 791 insertions, 51 deletions
diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index fd281460b1..30d1a095fe 100644 --- a/src/cmd/go/alldocs.go +++ b/src/cmd/go/alldocs.go @@ -23,7 +23,8 @@ // generate generate Go files by processing source // get download and install packages and dependencies // install compile and install packages and dependencies -// list list packages +// list list packages or modules +// mod module maintenance // run compile and run Go program // test test packages // tool run specified go tool @@ -40,8 +41,11 @@ // environment environment variables // filetype file types // gopath GOPATH environment variable +// gopath-get legacy GOPATH go get // importpath import path syntax -// packages package lists +// modules modules, module versions, and more +// module-get module-aware go get +// packages package lists and patterns // testflag testing flags // testfunc testing functions // @@ -125,6 +129,8 @@ // arguments to pass on each gccgo compiler/linker invocation. // -gcflags '[pattern=]arg list' // arguments to pass on each go tool compile invocation. +// -getmode mode +// module download mode to use. See 'go help modules' for more. // -installsuffix suffix // a suffix to use in the name of the package installation directory, // in order to keep output separate from default builds. @@ -185,7 +191,7 @@ // // Usage: // -// go clean [-i] [-r] [-n] [-x] [-cache] [-testcache] [build flags] [packages] +// go clean [clean flags] [build flags] [packages] // // Clean removes object files from package source directories. // The go command builds most objects in a temporary directory, @@ -228,6 +234,10 @@ // The -testcache flag causes clean to expire all test results in the // go build cache. // +// The -modcache flag causes clean to remove the entire module +// download cache, including unpacked source code of versioned +// dependencies. +// // For more about build flags, see 'go help build'. // // For more about specifying packages, see 'go help packages'. @@ -512,7 +522,7 @@ // // Usage: // -// go get [-d] [-f] [-fix] [-insecure] [-t] [-u] [-v] [build flags] [packages] +// go get [-d] [-f] [-t] [-u] [-v] [-fix] [-insecure] [build flags] [packages] // // Get downloads the packages named by the import paths, along with their // dependencies. It then installs the named packages, like 'go install'. @@ -562,6 +572,12 @@ // For more about how 'go get' finds source code to // download, see 'go help importpath'. // +// This text describes the behavior of get when using GOPATH +// to manage source code and dependencies. +// If instead the go command is running in module-aware mode, +// the details of get's flags and effects change, as does 'go help get'. +// See 'go help modules' and 'go help module-get'. +// // See also: go build, go install, go clean. // // @@ -581,13 +597,16 @@ // See also: go build, go get, go clean. // // -// List packages +// List packages or modules // // Usage: // -// go list [-cgo] [-deps] [-e] [-export] [-f format] [-json] [-test] [build flags] [packages] +// go list [-f format] [-json] [-m] [list flags] [build flags] [packages] // -// List lists the packages named by the import paths, one per line. +// List lists the named packages, one per line. +// The most commonly-used flags are -f and -json, which control the form +// of the output printed for each package. Other list flags, documented below, +// control more specific details. // // The default output shows the package import path: // @@ -597,27 +616,28 @@ // golang.org/x/net/html // // The -f flag specifies an alternate format for the list, using the -// syntax of package template. The default output is equivalent to -f -// '{{.ImportPath}}'. The struct being passed to the template is: +// syntax of package template. The default output is equivalent +// to -f '{{.ImportPath}}'. The struct being passed to the template is: // // type Package struct { -// Dir string // directory containing package sources -// ImportPath string // import path of package in dir -// ImportComment string // path in import comment on package statement -// Name string // package name -// Doc string // package documentation string -// Target string // install path -// Shlib string // the shared library that contains this package (only set when -linkshared) -// Goroot bool // is this package in the Go root? -// Standard bool // is this package part of the standard Go library? -// Stale bool // would 'go install' do anything for this package? -// StaleReason string // explanation for Stale==true -// Root string // Go root or Go path dir containing this package -// ConflictDir string // this directory shadows Dir in $GOPATH -// BinaryOnly bool // binary-only package: cannot be recompiled from sources -// ForTest string // package is only for use in named test -// DepOnly bool // package is only a dependency, not explicitly listed -// Export string // file containing export data (when using -export) +// Dir string // directory containing package sources +// ImportPath string // import path of package in dir +// ImportComment string // path in import comment on package statement +// Name string // package name +// Doc string // package documentation string +// Target string // install path +// Shlib string // the shared library that contains this package (only set when -linkshared) +// Goroot bool // is this package in the Go root? +// Standard bool // is this package part of the standard Go library? +// Stale bool // would 'go install' do anything for this package? +// StaleReason string // explanation for Stale==true +// Root string // Go root or Go path dir containing this package +// ConflictDir string // this directory shadows Dir in $GOPATH +// BinaryOnly bool // binary-only package: cannot be recompiled from sources +// ForTest string // package is only for use in named test +// DepOnly bool // package is only a dependency, not explicitly listed +// Export string // file containing export data (when using -export) +// Module *Module // info about package's containing module, if any (can be nil) // // // Source files // GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) @@ -644,10 +664,11 @@ // CgoPkgConfig []string // cgo: pkg-config names // // // Dependency information -// Imports []string // import paths used by this package -// Deps []string // all (recursively) imported dependencies -// TestImports []string // imports from TestGoFiles -// XTestImports []string // imports from XTestGoFiles +// Imports []string // import paths used by this package +// ImportMap map[string]string // map from source import to ImportPath (identity entries omitted) +// Deps []string // all (recursively) imported dependencies +// TestImports []string // imports from TestGoFiles +// XTestImports []string // imports from XTestGoFiles // // // Error information // Incomplete bool // this package or a dependency has an error @@ -669,22 +690,25 @@ // Err string // the error itself // } // +// The module information is a Module struct, defined in the discussion +// of list -m below. +// // The template function "join" calls strings.Join. // // The template function "context" returns the build context, defined as: // -// type Context struct { -// GOARCH string // target architecture -// GOOS string // target operating system -// GOROOT string // Go root -// GOPATH string // Go path -// CgoEnabled bool // whether cgo can be used -// UseAllFiles bool // use files regardless of +build lines, file names -// Compiler string // compiler to assume when computing target paths -// BuildTags []string // build constraints to match in +build lines -// ReleaseTags []string // releases the current release is compatible with -// InstallSuffix string // suffix to use in the name of the install dir -// } +// type Context struct { +// GOARCH string // target architecture +// GOOS string // target operating system +// GOROOT string // Go root +// GOPATH string // Go path +// CgoEnabled bool // whether cgo can be used +// UseAllFiles bool // use files regardless of +build lines, file names +// Compiler string // compiler to assume when computing target paths +// BuildTags []string // build constraints to match in +build lines +// ReleaseTags []string // releases the current release is compatible with +// InstallSuffix string // suffix to use in the name of the install dir +// } // // For more information about the meaning of these fields see the documentation // for the go/build package's Context type. @@ -738,10 +762,242 @@ // referring to cached copies of generated Go source files. // Although they are Go source files, the paths may not end in ".go". // +// The -m flag causes list to list modules instead of packages. +// +// When listing modules, the -f flag still specifies a format template +// applied to a Go struct, but now a Module struct: +// +// type Module struct { +// Path string // module path +// Version string // module version +// Versions []string // available module versions (with -versions) +// Replace *Module // replaced by this module +// Time *time.Time // time version was created +// Update *Module // available update, if any (with -u) +// Main bool // is this the main module? +// Indirect bool // is this module only an indirect dependency of main module? +// Dir string // directory holding files for this module, if any +// Error *ModuleError // error loading module +// } +// +// type ModuleError struct { +// Err string // the error itself +// } +// +// The default output is to print the module path and then +// information about the version and replacement if any. +// For example, 'go list -m all' might print: +// +// my/main/module +// golang.org/x/text v0.3.0 => /tmp/text +// rsc.io/pdf v0.1.1 +// +// The Module struct has a String method that formats this +// line of output, so that the default format is equivalent +// to -f '{{.String}}'. +// +// Note that when a module has been replaced, its Replace field +// describes the replacement module, and its Dir field is set to +// the replacement's source code, if present. (That is, if Replace +// is non-nil, then Dir is set to Replace.Dir, with no access to +// the replaced source code.) +// +// The -u flag adds information about available upgrades. +// When the latest version of a given module is newer than +// the current one, list -u sets the Module's Update field +// to information about the newer module. +// The Module's String method indicates an available upgrade by +// formatting the newer version in brackets after the current version. +// For example, 'go list -m -u all' might print: +// +// my/main/module +// golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text +// rsc.io/pdf v0.1.1 [v0.1.2] +// +// (For tools, 'go list -m -u -json all' may be more convenient to parse.) +// +// The -versions flag causes list to set the Module's Versions field +// to a list of all known versions of that module, ordered according +// to semantic versioning, earliest to latest. The flag also changes +// the default output format to display the module path followed by the +// space-separated version list. +// +// The arguments to list -m are interpreted as a list of modules, not packages. +// The main module is the module containing the current directory. +// The active modules are the main module and its dependencies. +// With no arguments, list -m shows the main module. +// With arguments, list -m shows the modules specified by the arguments. +// Any of the active modules can be specified by its module path. +// The special pattern "all" specifies all the active modules, first the main +// module and then dependencies sorted by module path. +// A pattern containing "..." specifies the active modules whose +// module paths match the pattern. +// A query of the form path@version specifies the result of that query, +// which is not limited to active modules. +// See 'go help module' for more about module queries. +// +// The template function "module" takes a single string argument +// that must be a module path or query and returns the specified +// module as a Module struct. If an error occurs, the result will +// be a Module struct with a non-nil Error field. +// // For more about build flags, see 'go help build'. // // For more about specifying packages, see 'go help packages'. // +// For more about modules, see 'go help modules'. +// +// +// Module maintenance +// +// Usage: +// +// go mod [-v] [maintenance flags] +// +// Mod performs module maintenance operations as specified by the +// following flags, which may be combined. +// +// The -v flag enables additional output about operations performed. +// +// The first group of operations provide low-level editing operations +// for manipulating go.mod from the command line or in scripts or +// other tools. They read only go.mod itself; they do not look up any +// information about the modules involved. +// +// The -init flag initializes and writes a new go.mod to the current directory, +// in effect creating a new module rooted at the current directory. +// The file go.mod must not already exist. +// If possible, mod will guess the module path from import comments +// (see 'go help importpath') or from version control configuration. +// To override this guess, use the -module flag. +// (Without -init, mod applies to the current module.) +// +// The -module flag changes (or, with -init, sets) the module's path +// (the go.mod file's module line). +// +// The -require=path@version and -droprequire=path flags +// add and drop a requirement on the given module path and version. +// Note that -require overrides any existing requirements on path. +// These flags are mainly for tools that understand the module graph. +// Users should prefer 'go get path@version' or 'go get path@none', +// which make other go.mod adjustments as needed to satisfy +// constraints imposed by other modules. +// +// The -exclude=path@version and -dropexclude=path@version flags +// add and drop an exclusion for the given module path and version. +// Note that -exclude=path@version is a no-op if that exclusion already exists. +// +// The -replace=old@v=new@w and -dropreplace=old@v flags +// add and drop a replacement of the given module path and version pair. +// If the @v in old@v is omitted, the replacement applies to all versions +// with the old module path. If the @v in new@v is omitted, the +// new path should be a directory on the local system, not a module path. +// Note that -replace overrides any existing replacements for old@v. +// +// These editing flags (-require, -droprequire, -exclude, -dropexclude, +// -replace, and -dropreplace) may be repeated. +// +// The -fmt flag reformats the go.mod file without making other changes. +// This reformatting is also implied by any other modifications that use or +// rewrite the go.mod file. The only time this flag is needed is if no other +// flags are specified, as in 'go mod -fmt'. +// +// The -graph flag prints the module requirement graph (with replacements applied) +// in text form. Each line in the output has two space-separated fields: a module +// and one of its requirements. Each module is identified as a string of the form +// path@version, except for the main module, which has no @version suffix. +// +// The -json flag prints the go.mod file in JSON format corresponding to these +// Go types: +// +// type Module struct { +// Path string +// Version string +// } +// +// type GoMod struct { +// Module Module +// Require []Require +// Exclude []Module +// Replace []Replace +// } +// +// type Require struct { +// Path string +// Version string +// Indirect bool +// } +// +// type Replace string { +// Old Module +// New Module +// } +// +// Note that this only describes the go.mod file itself, not other modules +// referred to indirectly. For the full set of modules available to a build, +// use 'go list -m -json all'. +// +// The next group of operations provide higher-level editing and maintenance +// of a module, beyond the go.mod file. +// +// The -packages flag prints a list of packages in the module. +// It only identifies directories containing Go source code; +// it does not check that those directories contain code that builds. +// +// The -fix flag updates go.mod to use canonical version identifiers and +// to be semantically consistent. For example, consider this go.mod file: +// +// module M +// +// require ( +// A v1 +// B v1.0.0 +// C v1.0.0 +// D v1.2.3 +// E dev +// ) +// +// exclude D v1.2.3 +// +// First, -fix rewrites non-canonical version identifiers to semver form, so +// A's v1 becomes v1.0.0 and E's dev becomes the pseudo-version for the latest +// commit on the dev branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1. +// +// Next, -fix updates requirements to respect exclusions, so the requirement +// on the excluded D v1.2.3 is updated to use the next available version of D, +// perhaps D v1.2.4 or D v1.3.0. +// +// Finally, -fix removes redundant or misleading requirements. +// For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0, +// then go.mod's requirement of B v1.0.0 is misleading (superseded +// by B's need for v1.2.0), and its requirement of C v1.0.0 is redundant +// (implied by B's need for the same version), so both will be removed. +// +// Although -fix runs the fix-up operation in isolation, the fix-up also +// runs automatically any time a go command uses the module graph, +// to update go.mod to reflect reality. For example, the -sync, -vendor, +// and -verify flags all effectively imply -fix. And because the module +// graph defines the meaning of import statements, any commands +// that load packages—'go build', 'go test', 'go list', and so on—also +// effectively imply 'go mod -fix'. +// +// The -sync flag synchronizes go.mod with the source code in the module. +// It adds any missing modules necessary to build the current module's +// packages and dependencies, and it removes unused modules that +// don't provide any relevant packages. It also adds any missing entries +// to go.sum and removes any unnecessary ones. +// +// The -vendor flag resets the module's vendor directory to include all +// packages needed to build and test all the module's packages. +// It does not include any test code for the vendored packages. +// +// The -verify flag checks that the dependencies of the current module, +// which are stored in a local downloaded source cache, have not been +// modified since being downloaded. If all the modules are unmodified, +// -verify prints "all modules verified." Otherwise it reports which +// modules have been changed and causes 'go mod' to exit with a +// non-zero status. +// // // Compile and run Go program // @@ -1069,6 +1325,8 @@ // Examples are linux, darwin, windows, netbsd. // GOPATH // For more details see: 'go help gopath'. +// GOPROXY +// URL of Go module proxy. See 'go help goproxy'. // GORACE // Options for the race detector. // See https://golang.org/doc/articles/race_detector.html. @@ -1262,6 +1520,12 @@ // // See https://golang.org/doc/code.html for an example. // +// GOPATH and Modules +// +// When using modules, GOPATH is no longer used for resolving imports. +// However, it is still used to store downloaded source code (in GOPATH/src/mod) +// and compiled commands (in GOPATH/bin). +// // Internal Directories // // Code in or below a directory named "internal" is importable only @@ -1422,6 +1686,7 @@ // that repository. The supported version control systems are: // // Bazaar .bzr +// Fossil .fossil // Git .git // Mercurial .hg // Subversion .svn @@ -1465,7 +1730,7 @@ // In particular, it should appear before any raw JavaScript or CSS, // to avoid confusing the go command's restricted parser. // -// The vcs is one of "git", "hg", "svn", etc, +// The vcs is one of "bzr", "fossil", "git", "hg", "svn". // // The repo-root is the root of the version control system // containing a scheme and not containing a .vcs qualifier. @@ -1487,12 +1752,22 @@ // same meta tag and then git clone https://code.org/r/p/exproj into // GOPATH/src/example.org. // -// New downloaded packages are written to the first directory listed in the GOPATH -// environment variable (For more details see: 'go help gopath'). +// When using GOPATH, downloaded packages are written to the first directory +// listed in the GOPATH environment variable. +// (See 'go help gopath-get' and 'go help gopath'.) +// +// When using modules, downloaded packages are stored in the module cache. +// (See 'go help modules-get' and 'go help goproxy'.) +// +// When using modules, an additional variant of the go-import meta tag is +// recognized and is preferred over those listing version control systems. +// That variant uses "mod" as the vcs in the content value, as in: // -// The go command attempts to download the version of the -// package appropriate for the Go release being used. -// Run 'go help get' for more. +// <meta name="go-import" content="example.org mod https://code.org/moduleproxy"> +// +// This tag means to fetch modules with paths beginning with example.org +// from the module proxy available at the URL https://code.org/moduleproxy. +// See 'go help goproxy' for details about the proxy protocol. // // Import path checking // @@ -1515,10 +1790,473 @@ // This makes it possible to copy code into alternate locations in vendor trees // without needing to update import comments. // +// Import path checking is also disabled when using modules. +// Import path comments are obsoleted by the go.mod file's module statement. +// // See https://golang.org/s/go14customimport for details. // // -// Package lists +// Modules, module versions, and more +// +// A module is a collection of related Go packages. +// Modules are the unit of source code interchange and versioning. +// The go command has direct support for working with modules, +// including recording and resolving dependencies on other modules. +// Modules replace the old GOPATH-based approach to specifying +// which source files are used in a given build. +// +// Experimental module support +// +// Go 1.11 includes experimental support for Go modules, +// including a new module-aware 'go get' command. +// We intend to keep revising this support, while preserving compatibility, +// until it can be declared official (no longer experimental), +// and then at a later point we may remove support for work +// in GOPATH and the old 'go get' command. +// +// The quickest way to take advantage of the new Go 1.11 module support +// is to check out your repository into a directory outside GOPATH/src, +// create a go.mod file (described in the next section) there, and run +// go commands from within that file tree. +// +// For more fine-grained control, the module support in Go 1.11 respects +// a temporary environment variable, GO111MODULE, which can be set to one +// of three string values: off, on, or auto (the default). +// If GO111MODULE=off, then the go command never uses the +// new module support. Instead it looks in vendor directories and GOPATH +// to find dependencies; we now refer to this as "GOPATH mode." +// If GO111MODULE=on, then the go command requires the use of modules, +// never consulting GOPATH. We refer to this as the command being +// module-aware or running in "module-aware mode". +// If GO111MODULE=auto or is unset, then the go command enables or +// disables module support based on the current directory. +// Module support is enabled only when the current directory is outside +// GOPATH/src and itself contains a go.mod file or is below a directory +// containing a go.mod file. +// +// In module-aware mode, GOPATH no longer defines the meaning of imports +// during a build, but it still stores downloaded dependencies (in GOPATH/src/mod) +// and installed commands (in GOPATH/bin, unless GOBIN is set). +// +// Defining a module +// +// A module is defined by a tree of Go source files with a go.mod file +// in the tree's root directory. The directory containing the go.mod file +// is called the module root. Typically the module root will also correspond +// to a source code repository root (but in general it need not). +// The module is the set of all Go packages in the module root and its +// subdirectories, but excluding subtrees with their own go.mod files. +// +// The "module path" is the import path prefix corresponding to the module root. +// The go.mod file defines the module path and lists the specific versions +// of other modules that should be used when resolving imports during a build, +// by giving their module paths and versions. +// +// For example, this go.mod declares that the directory containing it is the root +// of the module with path example.com/m, and it also declares that the module +// depends on specific versions of golang.org/x/text and gopkg.in/yaml.v2: +// +// module example.com/m +// +// require ( +// golang.org/x/text v0.3.0 +// gopkg.in/yaml.v2 v2.1.0 +// ) +// +// The go.mod file can also specify replacements and excluded versions +// that only apply when building the module directly; they are ignored +// when the module is incorporated into a larger build. +// For more about the go.mod file, see https://research.swtch.com/vgo-module. +// +// To start a new module, simply create a go.mod file in the root of the +// module's directory tree, containing only a module statement. +// The 'go mod' command can be used to do this: +// +// go mod -init -module example.com/m +// +// In a project already using an existing dependency management tool like +// godep, glide, or dep, 'go mod -init' will also add require statements +// matching the existing configuration. +// +// Once the go.mod file exists, no additional steps are required: +// go commands like 'go build', 'go test', or even 'go list' will automatically +// add new dependencies as needed to satisfy imports. +// +// The main module and the build list +// +// The "main module" is the module containing the directory where the go command +// is run. The go command finds the module root by looking for a go.mod in the +// current directory, or else the current directory's parent directory, +// or else the parent's parent directory, and so on. +// +// The main module's go.mod file defines the precise set of packages available +// for use by the go command, through require, replace, and exclude statements. +// Dependency modules, found by following require statements, also contribute +// to the definition of that set of packages, but only through their go.mod +// files' require statements: any replace and exclude statements in dependency +// modules are ignored. The replace and exclude statements therefore allow the +// main module complete control over its own build, without also being subject +// to complete control by dependencies. +// +// The set of modules providing packages to builds is called the "build list". +// The build list initially contains only the main module. Then the go command +// adds to the list the exact module versions required by modules already +// on the list, recursively, until there is nothing left to add to the list. +// If multiple versions of a particular module are added to the list, +// then at the end only the latest version (according to semantic version +// ordering) is kept for use in the build. +// +// The 'go list' command provides information about the main module +// and the build list. For example: +// +// go list -m # print path of main module +// go list -m -f={{.Dir}} # print root directory of main module +// go list -m all # print build list +// +// Maintaining module requirements +// +// The go.mod file is meant to be readable and editable by both +// programmers and tools. The go command itself automatically updates the go.mod file +// to maintain a standard formatting and the accuracy of require statements. +// +// Any go command that finds an unfamiliar import will look up the module +// containing that import and add the latest version of that module +// to go.mod automatically. In most cases, therefore, it suffices to +// add an import to source code and run 'go build', 'go test', or even 'go list': +// as part of analyzing the package, the go command will discover +// and resolve the import and update the go.mod file. +// +// Any go command can determine that a module requirement is +// missing and must be added, even when considering only a single +// package from the module. On the other hand, determining that a module requirement +// is no longer necessary and can be deleted requires a full view of +// all packages in the module, across all possible build configurations +// (architectures, operating systems, build tags, and so on). +// The 'go mod -sync' command builds that view and then +// adds any missing module requirements and removes unnecessary ones. +// +// As part of maintaining the require statements in go.mod, the go command +// tracks which ones provide packages imported directly by the current module +// and which ones provide packages only used indirectly by other module +// dependencies. Requirements needed only for indirect uses are marked with a +// "// indirect" comment in the go.mod file. Indirect requirements are +// automatically removed from the go.mod file once they are implied by other +// direct requirements. Indirect requirements only arise when using modules +// that fail to state some of their own dependencies or when explicitly +// upgrading a module's dependencies ahead of its own stated requirements. +// +// Because of this automatic maintenance, the information in go.mod is an +// up-to-date, readable description of the build. +// +// The 'go get' command updates go.mod to change the module versions used in a +// build. An upgrade of one module may imply upgrading others, and similarly a +// downgrade of one module may imply downgrading others. The 'go get' command +// makes these implied changes as well. If go.mod is edited directly, commands +// like 'go build' or 'go list' will assume that an upgrade is intended and +// automatically make any implied upgrades and update go.mod to reflect them. +// +// The 'go mod' command provides other functionality for use in maintaining +// and understanding modules and go.mod files. See 'go help mod'. +// +// Pseudo-versions +// +// The go.mod file and the go command more generally use semantic versions as +// the standard form for describing module versions, so that versions can be +// compared to determine which should be considered earlier or later than another. +// A module version like v1.2.3 is introduced by tagging a revision in the +// underlying source repository. Untagged revisions can be referred to +// using a "pseudo-version" like v0.0.0-yyyymmddhhmmss-abcdefabcdef, +// where the time is the commit time in UTC and the final suffix is the prefix +// of the commit hash. The time portion ensures that two pseudo-versions can +// be compared to determine which happened later, the commit hash identifes +// the underlying commit, and the prefix (v0.0.0- in this example) is derived from +// the most recent tagged version in the commit graph before this commit. +// +// There are three pseudo-version forms: +// +// vX.0.0-yyyymmddhhmmss-abcdefabcdef is used when there is no earlier +// versioned commit with an appropriate major version before the target commit. +// (This was originally the only form, so some older go.mod files use this form +// even for commits that do follow tags.) +// +// vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef is used when the most +// recent versioned commit before the target commit is vX.Y.Z-pre. +// +// vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef is used when the most +// recent versioned commit before the target commit is vX.Y.Z. +// +// Pseudo-versions never need to be typed by hand: the go command will accept +// the plain commit hash and translate it into a pseudo-version (or a tagged +// version if available) automatically. This conversion is an example of a +// module query. +// +// Module queries +// +// The go command accepts a "module query" in place of a module version +// both on the command line and in the main module's go.mod file. +// (After evaluating a query found in the main module's go.mod file, +// the go command updates the file to replace the query with its result.) +// +// A fully-specified semantic version, such as "v1.2.3", +// evaluates to that specific version. +// +// A semantic version prefix, such as "v1" or "v1.2", +// evaluates to the latest available tagged version with that prefix. +// +// A semantic version comparison, such as "<v1.2.3" or ">=v1.5.6", +// evaluates to the available tagged version nearest to the comparison target +// (the latest version for < and <=, the earliest version for > and >=). +// +// The string "latest" matches the latest available tagged version, +// or else the underlying source repository's latest untagged revision. +// +// A revision identifier for the underlying source repository, +// such as a commit hash prefix, revision tag, or branch name, +// selects that specific code revision. If the revision is +// also tagged with a semantic version, the query evaluates to +// that semantic version. Otherwise the query evaluates to a +// pseudo-version for the commit. +// +// All queries prefer release versions to pre-release versions. +// For example, "<v1.2.3" will prefer to return "v1.2.2" +// instead of "v1.2.3-pre1", even though "v1.2.3-pre1" is nearer +// to the comparison target. +// +// Module versions disallowed by exclude statements in the +// main module's go.mod are considered unavailable and cannot +// be returned by queries. +// +// For example, these commands are all valid: +// +// go get github.com/gorilla/mux@latest # same (@latest is default for 'go get') +// go get github.com/gorilla/mux@v1.6.2 # records v1.6.2 +// go get github.com/gorilla/mux@e3702bed2 # records v1.6.2 +// go get github.com/gorilla/mux@c856192 # records v0.0.0-20180517173623-c85619274f5d +// go get github.com/gorilla/mux@master # records current meaning of master +// +// Module compatibility and semantic versioning +// +// The go command requires that modules use semantic versions and expects that +// the versions accurately describe compatibility: it assumes that v1.5.4 is a +// backwards-compatible replacement for v1.5.3, v1.4.0, and even v1.0.0. +// More generally the go command expects that packages follow the +// "import compatibility rule", which says: +// +// "If an old package and a new package have the same import path, +// the new package must be backwards compatible with the old package." +// +// Because the go command assumes the import compatibility rule, +// a module definition can only set the minimum required version of one +// of its dependencies: it cannot set a maximum or exclude selected versions. +// Still, the import compatibility rule is not a guarantee: it may be that +// v1.5.4 is buggy and not a backwards-compatible replacement for v1.5.3. +// Because of this, the go command never updates from an older version +// to a newer version of a module unasked. +// +// In semantic versioning, changing the major version number indicates a lack +// of backwards compatibility with earlier versions. To preserve import +// compatibility, the go command requires that modules with major version v2 +// or later use a module path with that major version as the final element. +// For example, version v2.0.0 of example.com/m must instead use module path +// example.com/m/v2, and packages in that module would use that path as +// their import path prefix, as in example.com/m/v2/sub/pkg. Including the +// major version number in the module path and import paths in this way is +// called "semantic import versioning". Pseudo-versions for modules with major +// version v2 and later begin with that major version instead of v0, as in +// v2.0.0-20180326061214-4fc5987536ef. +// +// As a special case, module paths beginning with gopkg.in/ continue to use the +// conventions established on that system: the major version is always present, +// and it is preceded by a dot instead of a slash: gopkg.in/yaml.v1 +// and gopkg.in/yaml.v2, not gopkg.in/yaml and gopkg.in/yaml/v2. +// +// The go command treats modules with different module paths as unrelated: +// it makes no connection between example.com/m and example.com/m/v2. +// Modules with different major versions can be used together in a build +// and are kept separate by the fact that their packages use different +// import paths. +// +// In semantic versioning, major version v0 is for initial development, +// indicating no expectations of stability or backwards compatibility. +// Major version v0 does not appear in the module path, because those +// versions are preparation for v1.0.0, and v1 does not appear in the +// module path either. +// +// Code written before the semantic import versioning convention +// was introduced may use major versions v2 and later to describe +// the same set of unversioned import paths as used in v0 and v1. +// To accommodate such code, if a source code repository has a +// v2.0.0 or later tag for a file tree with no go.mod, the version is +// considered to be part of the v1 module's available versions +// and is given an +incompatible suffix when converted to a module +// version, as in v2.0.0+incompatible. The +incompatible tag is also +// applied to pseudo-versions derived from such versions, as in +// v2.0.1-0.yyyymmddhhmmss-abcdefabcdef+incompatible. +// +// In general, having a dependency in the build list (as reported by 'go list -m all') +// on a v0 version, pre-release version, pseudo-version, or +incompatible version +// is an indication that problems are more likely when upgrading that +// dependency, since there is no expectation of compatibility for those. +// +// See https://research.swtch.com/vgo-import for more information about +// semantic import versioning, and see https://semver.org/ for more about +// semantic versioning. +// +// Module code layout +// +// For now, see https://research.swtch.com/vgo-module for information +// about how source code in version control systems is mapped to +// module file trees. +// +// TODO: Add documentation to go command. +// +// Module downloading and verification +// +// The go command maintains, in the main module's root directory alongside +// go.mod, a file named go.sum containing the expected cryptographic checksums +// of the content of specific module versions. Each time a dependency is +// used, its checksum is added to go.sum if missing or else required to match +// the existing entry in go.sum. +// +// The go command maintains a cache of downloaded packages and computes +// and records the cryptographic checksum of each package at download time. +// In normal operation, the go command checks these pre-computed checksums +// against the main module's go.sum file, instead of recomputing them on +// each command invocation. The 'go mod -verify' command checks that +// the cached copies of module downloads still match both their recorded +// checksums and the entries in go.sum. +// +// The go command can fetch modules from a proxy instead of connecting +// to source control systems directly, according to the setting of the GOPROXY +// environment variable. +// +// See 'go help goproxy' for details about the proxy and also the format of +// the cached downloaded packages. +// +// Modules and vendoring +// +// When using modules, the go command completely ignores vendor directories. +// +// By default, the go command satisfies dependencies by downloading modules +// from their sources and using those downloaded copies (after verification, +// as described in the previous section). To allow interoperation with older +// versions of Go, or to ensure that all files used for a build are stored +// together in a single file tree, 'go mod -vendor' creates a directory named +// vendor in the root directory of the main module and stores there all the +// packages from dependency modules that are needed to support builds and +// tests of packages in the main module. +// +// To build using the main module's top-level vendor directory to satisfy +// dependencies (disabling use of the usual network sources and local +// caches), use 'go build -getmode=vendor'. Note that only the main module's +// top-level vendor directory is used; vendor directories in other locations +// are still ignored. +// +// +// Module-aware go get +// +// The 'go get' command changes behavior depending on whether the +// go command is running in module-aware mode or legacy GOPATH mode. +// This help text, accessible as 'go help module-get' even in legacy GOPATH mode, +// describes 'go get' as it operates in module-aware mode. +// +// Usage: get [-d] [-m] [-u] [-v] [-insecure] [build flags] [packages] +// +// Get resolves and adds dependencies to the current development module +// and then builds and installs them. +// +// The first step is to resolve which dependencies to add. +// +// For each named package or package pattern, get must decide which version of +// the corresponding module to use. By default, get chooses the latest tagged +// release version, such as v0.4.5 or v1.2.3. If there are no tagged release +// versions, get chooses the latest tagged prerelease version, such as +// v0.0.1-pre1. If there are no tagged versions at all, get chooses the latest +// known commit. +// +// This default version selection can be overridden by adding an @version +// suffix to the package argument, as in 'go get golang.org/x/text@v0.3.0'. +// For modules stored in source control repositories, the version suffix can +// also be a commit hash, branch identifier, or other syntax known to the +// source control system, as in 'go get golang.org/x/text@master'. +// The version suffix @latest explicitly requests the default behavior +// described above. +// +// If a module under consideration is already a dependency of the current +// development module, then get will update the required version. +// Specifying a version earlier than the current required version is valid and +// downgrades the dependency. The version suffix @none indicates that the +// dependency should be removed entirely. +// +// Although get defaults to using the latest version of the module containing +// a named package, it does not use the latest version of that module's +// dependencies. Instead it prefers to use the specific dependency versions +// requested by that module. For example, if the latest A requires module +// B v1.2.3, while B v1.2.4 and v1.3.1 are also available, then 'go get A' +// will use the latest A but then use B v1.2.3, as requested by A. (If there +// are competing requirements for a particular module, then 'go get' resolves +// those requirements by taking the maximum requested version.) +// +// The -u flag instructs get to update dependencies to use newer minor or +// patch releases when available. Continuing the previous example, +// 'go get -u A' will use the latest A with B v1.3.1 (not B v1.2.3). +// +// The -u=patch flag (not -u patch) instructs get to update dependencies +// to use newer patch releases when available. Continuing the previous example, +// 'go get -u=patch A' will use the latest A with B v1.2.4 (not B v1.2.3). +// +// In general, adding a new dependency may require upgrading +// existing dependencies to keep a working build, and 'go get' does +// this automatically. Similarly, downgrading one dependency may +// require downgrading other dependenceis, and 'go get' does +// this automatically as well. +// +// The -m flag instructs get to stop here, after resolving, upgrading, +// and downgrading modules and updating go.mod. When using -m, +// each specified package path must be a module path as well, +// not the import path of a package below the module root. +// +// The -insecure flag permits fetching from repositories and resolving +// custom domains using insecure schemes such as HTTP. Use with caution. +// +// The second step is to download (if needed), build, and install +// the named packages. +// +// If an argument names a module but not a package (because there is no +// Go source code in the module's root directory), then the install step +// is skipped for that argument, instead of causing a build failure. +// For example 'go get golang.org/x/perf' succeeds even though there +// is no code corresponding to that import path. +// +// Note that package patterns are allowed and are expanded after resolving +// the module versions. For example, 'go get golang.org/x/perf/cmd/...' +// adds the latest golang.org/x/perf and then installs the commands in that +// latest version. +// +// The -d flag instructs get to download the source code needed to build +// the named packages, including downloading necessary dependencies, +// but not to build and install them. +// +// With no package arguments, 'go get' applies to the main module, +// and to the Go package in the current directory, if any. In particular, +// 'go get -u' and 'go get -u=patch' update all the dependencies of the +// main module. With no package arguments and also without -u, +// 'go get' is not much more than 'go install', and 'go get -d' not much +// more than 'go list'. +// +// For more about modules, see 'go help modules'. +// +// For more about specifying packages, see 'go help packages'. +// +// This text describes the behavior of get using modules to manage source +// code and dependencies. If instead the go command is running in GOPATH +// mode, the details of get's flags and effects change, as does 'go help get'. +// See 'go help modules' and 'go help gopath-get'. +// +// See also: go build, go install, go clean, go mod. +// +// +// Package lists and patterns // // Many commands apply to a set of packages: // @@ -1542,9 +2280,11 @@ // // - "main" denotes the top-level package in a stand-alone executable. // -// - "all" expands to all package directories found in all the GOPATH +// - "all" expands to all packages found in all the GOPATH // trees. For example, 'go list all' lists all the packages on the local -// system. +// system. When using modules, "all" expands to all packages in +// the main module and their dependencies, including dependencies +// needed by tests of any of those. // // - "std" is like all but expands to just the packages in the standard // Go library. |