Command go

Go是用于管理Go源代码的工具.

Usage:

go <command> [arguments]

这些命令是:

bug         start a bug report
build       compile packages and dependencies
clean       remove object files and cached files
doc         show documentation for package or symbol
env         print Go environment information
fix         update packages to use new APIs
fmt         gofmt (reformat) package sources
generate    generate Go files by processing source
get         add dependencies to current module and install them
install     compile and install packages and dependencies
list        list packages or modules
mod         module maintenance
run         compile and run Go program
test        test packages
tool        run specified go tool
version     print Go version
vet         report likely mistakes in packages

使用" go help <命令>"获得有关命令的更多信息.

其他帮助主题:

buildmode   build modes
c           calling between Go and C
cache       build and test caching
environment environment variables
filetype    file types
go.mod      the go.mod file
gopath      GOPATH environment variable
gopath-get  legacy GOPATH go get
goproxy     module proxy protocol
importpath  import path syntax
modules     modules, module versions, and more
module-get  module-aware go get
module-auth module authentication using go.sum
module-private module configuration for non-public modules
packages    package lists and patterns
testflag    testing flags
testfunc    testing functions

使用"转到帮助<topic>"以获取有关该主题的更多信息.

Start a bug report

Usage:

go bug

错误会打开默认浏览器并启动新的错误报告. 该报告包含有用的系统信息.

Compile packages and dependencies

Usage:

go build [-o output] [-i] [build flags] [packages]

Build编译由导入路径命名的包及其依赖项,但不会安装结果.

如果要构建的参数是单个目录中的.go文件列表,则build会将其视为指定单个程序包的源文件列表.

编译软件包时,build会忽略以'_test.go'结尾的文件.

编译单个主程序包时,build将生成的可执行文件写入以第一个源文件(" go build ed.go rx.go"写入" ed"或" ed.exe")命名的输出文件或源代码目录( 'go build unix / sam'写入'sam'或'sam.exe'). 编写Windows可执行文件时,将添加" .exe"后缀.

当编译多个软件包或单个非主软件包时,build会编译软件包,但会丢弃生成的对象,仅用作检查是否可以构建软件包.

-o标志强制构建将生成的可执行文件或对象写入命名的输出文件或目录,而不是最后两段中描述的默认行为. 如果命名输出是存在的目录,那么所有生成的可执行文件都将写入该目录.

-i标志安装作为目标依赖项的软件包.

构建标志由构建,清理,获取,安装,列出,运行和测试命令共享:

-a
	force rebuilding of packages that are already up-to-date.
-n
	print the commands but do not run them.
-p n
	the number of programs, such as build commands or
	test binaries, that can be run in parallel.
	The default is the number of CPUs available.
-race
	enable data race detection.
	Supported only on linux/amd64, freebsd/amd64, darwin/amd64 and windows/amd64.
-msan
	enable interoperation with memory sanitizer.
	Supported only on linux/amd64, linux/arm64
	and only with Clang/LLVM as the host C compiler.
-v
	print the names of packages as they are compiled.
-work
	print the name of the temporary work directory and
	do not delete it when exiting.
-x
	print the commands.

-asmflags '[pattern=]arg list'
	arguments to pass on each go tool asm invocation.
-buildmode mode
	build mode to use. See 'go help buildmode' for more.
-compiler name
	name of compiler to use, as in runtime.Compiler (gccgo or gc).
-gccgoflags '[pattern=]arg list'
	arguments to pass on each gccgo compiler/linker invocation.
-gcflags '[pattern=]arg list'
	arguments to pass on each go tool compile invocation.
-installsuffix suffix
	a suffix to use in the name of the package installation directory,
	in order to keep output separate from default builds.
	If using the -race flag, the install suffix is automatically set to race
	or, if set explicitly, has _race appended to it. Likewise for the -msan
	flag. Using a -buildmode option that requires non-default compile flags
	has a similar effect.
-ldflags '[pattern=]arg list'
	arguments to pass on each go tool link invocation.
-linkshared
	link against shared libraries previously created with
	-buildmode=shared.
-mod mode
	module download mode to use: readonly or vendor.
	See 'go help modules' for more.
-pkgdir dir
	install and load all packages from dir instead of the usual locations.
	For example, when building with a non-standard configuration,
	use -pkgdir to keep generated packages in a separate location.
-tags tag,list
	a comma-separated list of build tags to consider satisfied during the
	build. For more information about build tags, see the description of
	build constraints in the documentation for the go/build package.
	(Earlier versions of Go used a space-separated list, and that form
	is deprecated but still recognized.)
-trimpath
	remove all file system paths from the resulting executable.
	Instead of absolute file system paths, the recorded file names
	will begin with either "go" (for the standard library),
	or a module path@version (when using modules),
	or a plain import path (when using GOPATH).
-toolexec 'cmd args'
	a program to use to invoke toolchain programs like vet and asm.
	For example, instead of running asm, the go command will run
	'cmd args /path/to/asm <arguments for asm>'.

The -asmflags, -gccgoflags, -gcflags, and -ldflags flags accept a space-separated list of arguments to pass to an underlying tool during the build. To embed spaces in an element in the list, surround it with either single or double quotes. The argument list may be preceded by a package pattern and an equal sign, which restricts the use of that argument list to the building of packages matching that pattern (see 'go help packages' for a description of package patterns). Without a pattern, the argument list applies only to the packages named on the command line. The flags may be repeated with different patterns in order to specify different arguments for different sets of packages. If a package matches patterns given in multiple flags, the latest match on the command line wins. For example, 'go build -gcflags=-S fmt' prints the disassembly only for package fmt, while 'go build -gcflags=all=-S fmt' prints the disassembly for fmt and all its dependencies.

有关指定软件包的更多信息,请参见"转到帮助软件包". 有关安装软件包和二进制文件的更多信息,请运行" go help gopath". 有关在Go和C / C ++之间进行调用的更多信息,请运行'go help c'.

注意:Build遵循某些约定,例如" go help gopath"描述的约定. 但是,并非所有项目都可以遵循这些约定. 具有自己的约定或使用单独的软件构建系统的安装可以选择使用较低级别的调用,例如" go tool compile"和" go tool link",以避免构建工具的某些开销和设计决策.

另请参阅:进行安装,获取,清洁.

Remove object files and cached files

Usage:

go clean [clean flags] [build flags] [packages]

清除将从软件包源目录中删除目标文件. go命令可在临时目录中构建大多数对象,因此go clean主要与其他工具或手动调用go build留下的对象文件有关.

如果指定了软件包参数或设置了-i或-r标志,则clean从与导入路径相对应的每个源目录中删除以下文件:

_obj/            old object directory, left from Makefiles
_test/           old test directory, left from Makefiles
_testmain.go     old gotest file, left from Makefiles
test.out         old test log, left from Makefiles
build.out        old test log, left from Makefiles
*.[568ao]        object files, left from Makefiles

DIR(.exe)        from go build
DIR.test(.exe)   from go test -c
MAINFILE(.exe)   from go build MAINFILE.go
*.so             from SWIG

在列表中,DIR表示目录的最终路径元素,而MAINFILE是目录中构建软件包时不包括的该目录中所有Go源文件的基本名称.

-i标志使clean删除相应的已安装归档文件或二进制文件(" go install"将创建什么).

-n标志使clean打印将执行的删除命令,但不运行它们.

-r标志导致将clean递归应用于导入路径命名的软件包的所有依赖项.

-x标志使clean在执行删除命令时打印它们.

-cache标志使clean删除整个go build缓存.

-testcache标志导致clean使go build缓存中的所有测试结果过期.

-modcache标志使clean删除整个模块下载缓存,包括版本化依赖项的未包装源代码.

有关构建标志的更多信息,请参见" go help build".

有关指定软件包的更多信息,请参见"转到帮助软件包".

Show documentation for package or symbol

Usage:

go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]

Doc打印与由其参数(包,const,func,type,var,method或struct字段)标识的项目相关的文档注释,然后对每个"注释"下的第一级项目进行单行总结.项目(包的包级别声明,类型的方法等).

Doc接受零,一或两个参数.

没有给定参数,即以

go doc

它在当前目录中打印软件包的软件包文档. 如果软件包是命令(软件包主软件包),则除非提供了-cmd标志,否则软件包的导出符号将从显示中删除.

When run with one argument, the argument is treated as a Go-syntax-like representation of the item to be documented. What the argument selects depends on what is installed in GOROOT and GOPATH, as well as the form of the argument, which is schematically one of these:

go doc <pkg>
go doc <sym>[.<methodOrField>]
go doc [<pkg>.]<sym>[.<methodOrField>]
go doc [<pkg>.][<sym>.]<methodOrField>

此列表中与参数匹配的第一项是打印其文档的项. (请参见下面的示例.)但是,如果参数以大写字母开头,则假定在当前目录中标识符号或方法.

对于包装,扫描顺序以广度优先顺序按词法确定. 也就是说,所提供的程序包是与搜索匹配的程序包,在根目录层次上最接近根,并且在词法上排在最前面. 始终在GOPATH之前完整扫描GOROOT树.

如果没有指定或匹配的软件包,则选择当前目录中的软件包,因此" go doc Foo"显示当前软件包中符号Foo的文档.

软件包路径必须是合格路径或路径的正确后缀. go工具通常的打包机制不适用于:打包路径元素,例如. 和...并非由go doc实现.

当使用两个参数运行时,第一个必须是完整的程序包路径(不仅仅是后缀),第二个必须是符号或带有method或struct字段的符号. 这类似于godoc接受的语法:

go doc <pkg> <sym>[.<methodOrField>]

在所有形式中,当匹配符号时,参数中的小写字母都匹配,但大写字母完全匹配. 这意味着如果不同的符号具有不同的大小写,则包中可能存在多个小写参数匹配项. 如果发生这种情况,将打印所有匹配项的文档.

Examples:

go doc
	Show documentation for current package.
go doc Foo
	Show documentation for Foo in the current package.
	(Foo starts with a capital letter so it cannot match
	a package path.)
go doc encoding/json
	Show documentation for the encoding/json package.
go doc json
	Shorthand for encoding/json.
go doc json.Number (or go doc json.number)
	Show documentation and method summary for json.Number.
go doc json.Number.Int64 (or go doc json.number.int64)
	Show documentation for json.Number's Int64 method.
go doc cmd/doc
	Show package docs for the doc command.
go doc -cmd cmd/doc
	Show package docs and exported symbols within the doc command.
go doc template.new
	Show documentation for html/template's New function.
	(html/template is lexically before text/template)
go doc text/template.new # One argument
	Show documentation for text/template's New function.
go doc text/template new # Two arguments
	Show documentation for text/template's New function.

At least in the current tree, these invocations all print the
documentation for json.Decoder's Decode method:

go doc json.Decoder.Decode
go doc json.decoder.decode
go doc json.decode
cd go/src/encoding/json; go doc decode

Flags:

-all
	Show all the documentation for the package.
-c
	Respect case when matching symbols.
-cmd
	Treat a command (package main) like a regular package.
	Otherwise package main's exported symbols are hidden
	when showing the package's top-level documentation.
-src
	Show the full source code for the symbol. This will
	display the full Go source of its declaration and
	definition, such as a function definition (including
	the body), type declaration or enclosing const
	block. The output may therefore include unexported
	details.
-u
	Show documentation for unexported as well as exported
	symbols, methods, and fields.

Print Go environment information

Usage:

go env [-json] [-u] [-w] [var ...]

Env打印Go环境信息.

默认情况下,env将信息作为外壳程序脚本输出(在Windows中为批处理文件). 如果给定一个或多个变量名作为参数,则env在其自己的行上打印每个命名变量的值.

-json标志以JSON格式而不是shell脚本打印环境.

-u标志需要一个或多个参数,并且如果已使用'go env -w'进行设置,则取消设置命名环境变量的默认设置.

-w标志需要一个或多个NAME = VALUE形式的参数,并将命名环境变量的默认设置更改为给定值.

有关环境变量的更多信息,请参见"转到帮助环境".

Update packages to use new APIs

Usage:

go fix [packages]

Fix在由导入路径命名的包上运行Go fix命令.

有关修复的更多信息,请参见" go doc cmd / fix". 有关指定软件包的更多信息,请参见"转到帮助软件包".

要使用特定选项运行修复程序,请运行"执行工具修复程序".

另请参阅:转到fmt,转到兽医.

Gofmt (reformat) package sources

Usage:

go fmt [-n] [-x] [packages]

Fmt在由导入路径命名的软件包上运行命令'gofmt -l -w'. 它显示已修改文件的名称.

有关gofmt的更多信息,请参见'go doc cmd / gofmt'. 有关指定软件包的更多信息,请参见"转到帮助软件包".

-n标志打印将要执行的命令. -x标志在执行命令时打印命令.

要使用特定选项运行gofmt,请运行gofmt本身.

另请参阅:修复,审核.

Generate Go files by processing source

Usage:

go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]

在现有文件中生成由指令描述的运行命令. 这些命令可以运行任何进程,但目的是创建或更新Go源文件.

Go生成永远不会通过go build,go get,go test等自动运行. 它必须显式运行.

Go generate会在文件中扫描指令,这些指令是以下形式的行:

//go:generate command argument...

(注意:" // go"中没有前导空格,也没有空格),其中command是要运行的生成器,对应于可以在本地运行的可执行文件. 它必须位于以下描述的shell路径(gofmt),标准路径(/ usr / you / bin / mytool)或命令别名中.

为了将生成的代码传达给人类和机器工具,生成的源代码应具有与以下正则表达式(采用Go语法)匹配的行:

^// Code generated .* DO NOT EDIT\.$

该行可能出现在文件中的任何位置,但通常位于开头附近,因此很容易找到.

请注意,go generate不会解析文件,因此看起来像注释中的指令或多行字符串的行将被视为指令.

指令的参数是用空格分隔的标记或双引号字符串,它们在运行时作为单独的参数传递给生成器.

带引号的字符串使用Go语法,并在执行之前进行求值; 带引号的字符串作为生成器的单个参数出现.

Go generate在运行生成器时会设置几个变量:

$GOARCH
	The execution architecture (arm, amd64, etc.)
$GOOS
	The execution operating system (linux, windows, etc.)
$GOFILE
	The base name of the file.
$GOLINE
	The line number of the directive in the source file.
$GOPACKAGE
	The name of the package of the file containing the directive.
$DOLLAR
	A dollar sign.

除了变量替换和带引号的字符串求值外,在命令行上不执行任何特殊处理,例如" globbing".

在运行该命令之前的最后一步,将在整个命令行中扩展任何带有字母数字名称的环境变量的调用,例如$ GOFILE或$ HOME. 在所有操作系统上,变量扩展的语法为$ NAME. 由于求值顺序,变量甚至在带引号的字符串内也会扩展. 如果未设置变量NAME,则$ NAME扩展为空字符串.

形式的指令,

//go:generate -command xxx args...

仅对于此源文件的其余部分,指定字符串xxx表示由参数标识的命令. 这可用于创建别名或处理多字生成器. 例如,

//go:generate -command foo go tool foo

指定命令" foo"代表生成器" go tool foo".

按照命令行给定的顺序生成进程包,一次生成一个. 如果命令行从单个目录列出.go文件,则将它们视为单个程序包. 在包中,generate以文件名顺序一次处理一个包中的源文件. 在源文件中,按它们在文件中出现的顺序生成运行生成器,一次生成一个. go generate工具还将设置构建标记为" generate",以便可以通过go generate检查文件,但在构建过程中将其忽略.

如果有任何生成器返回错误退出状态,则"执行生成"将跳过该程序包的所有进一步处理.

生成器在程序包的源目录中运行.

Go generate接受一个特定的标志:

-run=""
	if non-empty, specifies a regular expression to select
	directives whose full original source text (excluding
	any trailing spaces and final newline) matches the
	expression.

它还接受标准的构建标志,包括-v,-n和-x. -v标志在处理软件包和文件时显示其名称. -n标志打印将要执行的命令. -x标志在执行命令时打印命令.

有关构建标志的更多信息,请参见" go help build".

有关指定软件包的更多信息,请参见"转到帮助软件包".

Add dependencies to current module and install them

Usage:

go get [-d] [-t] [-u] [-v] [-insecure] [build flags] [packages]

Get解析并向当前开发模块添加依赖项,然后构建并安装它们.

第一步是解决要添加的依赖项.

对于每个命名的程序包或程序包模式,get必须确定要使用的相应模块的版本. 默认情况下,get查找带标记的最新版本,例如v0.4.5或v1.2.3. 如果没有标记的发行版本,则get查找最新的标记的发行前版本,例如v0.0.1-pre1. 如果根本没有标记的版本,则get查找最新的已知提交. 如果在更高版本(例如,比最新版本更新的预发行版本)中不再需要该模块,则get将使用它查找的版本. 否则,get将使用当前所需的版本.

可以通过在包参数中添加@version后缀来覆盖此默认版本选择,如" go get golang.org/x/text@v0.3.0"中所示. 版本可以是前缀:@ v1表示从v1开始的最新可用版本. 有关完整查询语法,请参见"模块查询"标题下的" go帮助模块".

对于存储在源代码控制存储库中的模块,版本后缀也可以是提交哈希,分支标识符或源代码控制系统已知的其他语法,如" go get golang.org/x/text@master"中所示. 请注意,不能显式选择名称与其他模块查询语法重叠的分支. 例如,后缀@ v2表示以v2开头的最新版本,而不是名为v2的分支.

如果正在考虑的模块已经是当前开发模块的依赖项,那么get将更新所需的版本. 指定比当前所需版本更早的版本是有效的,并且会降级依赖性. 版本后缀@none表示应完全删除依赖项,并根据需要降级或删除依赖项.

版本后缀@latest显式请求给定路径命名的模块的最新次要版本. 后缀@upgrade与@latest相似,但是如果在比最新发行版本新的修订版或预发行版本中已经需要该模块,则不会降级该模块. 后缀@patch请求最新的补丁程序版本:最新发布的版本,其主要和次要版本号与当前所需版本相同. 像@upgrade一样,@ patch不会降级新版本中已经需要的模块. 如果尚不需要该路径,则@upgrade和@patch等效于@latest.

尽管默认使用包含命名包的模块的最新版本,但它不使用该模块依赖关系的最新版本. 相反,它更喜欢使用该模块请求的特定依赖项版本. 例如,如果最新的A要求模块B v1.2.3,而B v1.2.4和v1.3.1也可用,则"获得get A"将使用最新的A,但按照A的要求使用B v1.2.3. (如果对某个特定模块有相互竞争的要求,那么" go get"将通过获取最大请求版本来解决这些要求.)

-t标志指示开始考虑构建在命令行上指定的程序包测试所需的模块.

-u标志指示get更新模块,以提供在命令行上命名的软件包的依赖关系,以在可用时使用较新的次要版本或修补程序版本. 继续前面的示例," go get -u A"将使用最新的A和B v1.3.1(不是B v1.2.3). 如果B需要模块C,但C不提供在A中构建软件包所需的任何软件包(不包括测试),则C将不会更新.

-u = patch标志(不是-u patch)也指示获取更新依赖关系,但更改默认值以选择补丁程序版本. 继续前面的示例,'go get -u = patch A @ latest'将使用最新的A,其B版本为v1.2.4(不是B v1.2.3),而'go get -u = patch A'将使用的发行版为代替.

当-t和-u标志一起使用时,get还将更新测试依赖项.

通常,添加新的依赖项可能需要升级现有的依赖项以保持有效的构建,并且" go get"会自动执行此操作. 同样,降级一个依赖项可能需要降级其他依赖项,并且" go get"也将自动降级.

-insecure标志允许使用非安全方案(例如HTTP)从存储库中获取信息并解析自定义域. 请谨慎使用.

第二步是下载(如果需要),构建和安装命名的软件包.

如果参数指定模块名称而不是程序包名称(因为模块的根目录中没有Go源代码),则跳过该参数的安装步骤,而不会导致构建失败. 例如,即使没有与该导入路径相对应的代码," go get golang.org/x/perf"也会成功.

请注意,在解决模块版本后,允许使用包模式并对其进行扩展. 例如," go get golang.org/x/perf/cmd / ..."添加最新的golang.org/x/perf,然后以该最新版本安装命令.

-d标志指示获取下载构建命名软件包所需的源代码,包括下载必要的依赖项,而不是构建和安装它们.

没有包参数,'go get'适用于当前目录中的Go包(如果有). 特别是'go get -u'和'go get -u = patch'更新了该软件包的所有依赖关系. 没有软件包参数,也没有-u," go get"仅相当于" go install",而" go get -d"仅相当于" go list".

有关模块的更多信息,请参阅"转到帮助模块".

有关指定软件包的更多信息,请参见"转到帮助软件包".

本文介绍了使用模块管理源代码和依赖项的行为. 相反,如果go命令在GOPATH模式下运行,则get的标志和效果的详细信息会更改," go help get"也会更改. 请参阅"执行帮助模块"和"执行帮助gopath-get".

另请参阅:进行构建,进行安装,清洁,进行mod.

Compile and install packages and dependencies

Usage:

go install [-i] [build flags] [packages]

Install编译并安装由导入路径命名的软件包.

可执行文件安装在由GOBIN环境变量命名的目录中,如果未设置GOPATH环境变量,则默认目录为$ GOPATH / bin或$ HOME / go / bin. $ GOROOT中的可执行文件安装在$ GOROOT / bin或$ GOTOOLDIR中,而不是$ GOBIN中.

禁用模块感知模式后,其他软件包将安装在$ GOPATH / pkg / $ GOOS_ $ GOARCH目录中. 启用模块感知模式后,将构建并缓存其他软件包,但未安装.

-i标志也安装命名包的依赖项.

有关构建标志的更多信息,请参见" go help build". 有关指定软件包的更多信息,请参见"转到帮助软件包".

另请参阅:进行构建,进行获取,进行清理.

List packages or modules

Usage:

go list [-f format] [-json] [-m] [list flags] [build flags] [packages]

列表列出了命名包,每行一个. 最常用的标志是-f和-json,它们控制为每个软件包打印的输出形式. 下面列出的其他列表标志控制着更具体的细节.

默认输出显示软件包导入路径:

bytes
encoding/json
github.com/gorilla/mux
golang.org/x/net/html

-f标志使用软件包模板的语法为列表指定备用格式. 默认输出等效于-f'{{.ImportPath}}'. 传递给模板的结构是:

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 (no longer supported)
    ForTest       string   // package is only for use in named test
    Export        string   // file containing export data (when using -export)
    Module        *Module  // info about package's containing module, if any (can be nil)
    Match         []string // command-line patterns matching this package
    DepOnly       bool     // package is only a dependency, not explicitly listed

    // Source files
    GoFiles         []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
    CgoFiles        []string // .go source files that import "C"
    CompiledGoFiles []string // .go files presented to compiler (when using -compiled)
    IgnoredGoFiles  []string // .go source files ignored due to build constraints
    CFiles          []string // .c source files
    CXXFiles        []string // .cc, .cxx and .cpp source files
    MFiles          []string // .m source files
    HFiles          []string // .h, .hh, .hpp and .hxx source files
    FFiles          []string // .f, .F, .for and .f90 Fortran source files
    SFiles          []string // .s source files
    SwigFiles       []string // .swig files
    SwigCXXFiles    []string // .swigcxx files
    SysoFiles       []string // .syso object files to add to archive
    TestGoFiles     []string // _test.go files in package
    XTestGoFiles    []string // _test.go files outside package

    // Cgo directives
    CgoCFLAGS    []string // cgo: flags for C compiler
    CgoCPPFLAGS  []string // cgo: flags for C preprocessor
    CgoCXXFLAGS  []string // cgo: flags for C++ compiler
    CgoFFLAGS    []string // cgo: flags for Fortran compiler
    CgoLDFLAGS   []string // cgo: flags for linker
    CgoPkgConfig []string // cgo: pkg-config names

    // Dependency information
    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
    Error      *PackageError   // error loading package
    DepsErrors []*PackageError // errors loading dependencies
}

供应商目录中存储的软件包报告了一个ImportPath,该路径包含供应商目录的路径(例如," d / vendor / p"而不是" p"),以便ImportPath唯一地标识软件包的给定副本. Imports,Deps,TestImports和XTestImports列表也包含这些扩展的导入路径. 有关销售的更多信息,请参见golang.org/s/go15vendor.

错误信息(如果有)是

type PackageError struct {
    ImportStack   []string // shortest path from package named on command line to this one
    Pos           string   // position of error (if present, file:line:col)
    Err           string   // the error itself
}

模块信息是一个模块结构,在下面的列表-m的讨论中定义.

模板函数" join"调用strings.Join.

模板函数" context"返回构建上下文,定义为:

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
}

有关这些字段含义的更多信息,请参见go / build包的Context类型的文档.

-json标志使软件包数据以JSON格式而不是模板格式打印.

-compiled标志使列表将CompiledGoFiles设置为呈现给编译器的Go源文件. 通常,这意味着它会重复GoFiles中列出的文件,然后还添加通过处理CgoFiles和SwigFiles生成的Go代码. 导入列表包含来自GoFiles和CompiledGoFiles的所有导入的并集.

-deps标志使列表不仅遍历已命名的软件包,还遍历其所有依赖项. 它以深度优先的顺序遍历它们,因此仅在所有依赖项之后列出该软件包. 在命令行上未明确列出的软件包会将DepOnly字段设置为true.

-e标志更改了错误软件包的处理,即那些找不到或格式错误的软件包. 缺省情况下,list命令为每个错误的包装将错误打印为标准错误,并在常规打印过程中忽略考虑的包装. 使用-e标志,list命令从不将错误打印为标准错误,而是以通常的打印方式处理错误的软件包. 错误的软件包将具有一个非空的ImportPath和一个非null的Error字段; 其他信息可能会或可能不会丢失(置零).

-export标志使列表将"导出"字段设置为包含给定程序包的最新导出信息的文件名.

-find标志使列表标识已命名的软件包,但不能解析其依赖关系:Imports和Deps列表将为空.

-test标志使列表不仅报告已命名的软件包,而且报告其测试二进制文件(对于具有测试的软件包),以将测试二进制文件的确切构造传达给源代码分析工具. 报告的测试二进制文件的导入路径是程序包的导入路径,后跟" .test"后缀,如" math / rand.test"中所示. 构建测试时,有时有必要重建专门针对该测试的某些依赖项(最常见的是测试包本身). 报告的针对特定测试二进制文件重新编译的软件包的导入路径,其后带有空格和测试二进制文件的名称,并放在方括号中,如" math / rand [math / rand.test]"或" regexp [sort.test] ". ForTest字段也设置为要测试的软件包的名称(在前面的示例中为" math / rand"或" sort").

Dir,Target,Shlib,Root,ConflictDir和Export文件路径都是绝对路径.

默认情况下,列表GoFiles,CgoFiles等包含Dir中文件的名称(即相对于Dir的路径,而不是绝对路径). 使用-compiled和-test标志时添加的生成文件是指向生成的Go源文件的缓存副本的绝对路径. 尽管它们是Go源文件,但路径可能不会以" .go"结尾.

-m标志使list列出模块而不是软件包.

列出模块时,-f标志仍然指定应用于Go结构的格式模板,但现在指定为Module结构:

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
    GoMod     string       // path to go.mod file for this module, if any
    GoVersion string       // go version used in module
    Error     *ModuleError // error loading module
}

type ModuleError struct {
    Err string // the error itself
}

默认输出是打印模块路径,然后打印有关版本和替换的信息(如果有). 例如," go list -m all"可能会打印:

my/main/module
golang.org/x/text v0.3.0 => /tmp/text
rsc.io/pdf v0.1.1

Module结构体具有String方法,该方法格式化输出的这一行,因此默认格式等效于-f'{{.String}}'.

请注意,在替换模块后,其"替换"字段描述了替换模块,并且其"目录"字段设置为替换的源代码(如果有). (也就是说,如果Replace为非nil,则Dir设置为Replace.Dir,无法访问被替换的源代码.)

-u标志添加有关可用升级的信息. 当给定模块的最新版本比当前模块的最新版本时,列表-u将"模块的更新"字段设置为有关新模块的信息. Module的String方法通过在当前版本之后的方括号中格式化较新的版本来指示可用的升级. 例如," go list -m -u all"可能会打印:

my/main/module
golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
rsc.io/pdf v0.1.1 [v0.1.2]

(对于工具,'go list -m -u -json all'解析起来可能更方便.)

-versions标志使list可以将Module的Versions字段设置为该模块的所有已知版本的列表,该列表按照语义版本控制(从最早到最新)进行排序. 该标志还更改了默认输出格式,以显示模块路径,后跟以空格分隔的版本列表.

list -m的参数被解释为模块列表,而不是软件包列表. 主模块是包含当前目录的模块. 活动模块是主模块及其依赖项. 没有参数,列表-m显示主模块. 使用参数时,列表-m显示参数指定的模块. 任何活动模块均可通过其模块路径指定. 特殊模式" all"指定所有活动模块,首先是主模块,然后是按模块路径排序的依存关系. 包含" ..."的模式指定其模块路径与该模式匹配的活动模块. 格式为path @ version的查询指定该查询的结果,但不限于活动模块. 有关模块查询的更多信息,请参见"进入帮助模块".

模板函数"模块"采用单个字符串参数,该参数必须是模块路径或查询,并将指定的模块作为模块结构返回. 如果发生错误,则结果将是带有非零错误字段的Module结构.

有关构建标志的更多信息,请参见" go help build".

有关指定软件包的更多信息,请参见"转到帮助软件包".

有关模块的更多信息,请参阅"转到帮助模块".

Module maintenance

Go mod提供对模块操作的访问.

请注意,所有go命令都内置了对模块的支持,而不仅仅是'go mod'. 例如,应该使用" go get"完成对依赖项的日常添加,删除,升级和降级. 有关模块功能的概述,请参见"帮助模块".

Usage:

go mod <command> [arguments]

这些命令是:

download    download modules to local cache
edit        edit go.mod from tools or scripts
graph       print module requirement graph
init        initialize new module in current directory
tidy        add missing and remove unused modules
vendor      make vendored copy of dependencies
verify      verify dependencies have expected content
why         explain why packages or modules are needed

使用" go help mod <命令>"可获取有关命令的更多信息.

Download modules to local cache

Usage:

go mod download [-json] [modules]

下载将下载已命名的模块,这些模块可以是选择主模块依赖性的模块模式,也可以是path @ version形式的模块查询. 没有参数,下载适用于主模块的所有依赖项.

go命令将在常规执行期间根据需要自动下载模块. " go mod download"命令主要用于预填充本地缓存或计算Go模块代理的答案.

默认情况下,下载会将错误报告为标准错误,但其他情况下则保持沉默. -json标志导致下载将一系列JSON对象打印到标准输出,描述与该Go结构相对应的每个下载的模块(或失败):

type Module struct {
    Path     string // module path
    Version  string // module version
    Error    string // error loading module
    Info     string // absolute path to cached .info file
    GoMod    string // absolute path to cached .mod file
    Zip      string // absolute path to cached .zip file
    Dir      string // absolute path to cached source root directory
    Sum      string // checksum for path, version (as in go.sum)
    GoModSum string // checksum for go.mod (as in go.sum)
}

有关模块查询的更多信息,请参见"进入帮助模块".

Edit go.mod from tools or scripts

Usage:

go mod edit [editing flags] [go.mod]

Edit提供了一个命令行界面,用于编辑go.mod,主要供工具或脚本使用. 它只读取go.mod; 它不查找有关所涉及模块的信息. 默认情况下,edit读写主模块的go.mod文件,但是可以在编辑标记后指定其他目标文件.

编辑标志指定编辑操作的顺序.

-fmt标志重新格式化go.mod文件,而不进行其他更改. 使用或重写go.mod文件的任何其他修改也暗示了这种重新格式化. 唯一需要此标志的是没有指定其他标志的情况,例如'go mod edit -fmt'.

The -module flag changes the module's path (the go.mod file's module line).

-require = path @ version和-droprequire = path标志在给定的模块路径和版本上添加和删除要求. 请注意,-require会覆盖路径上的所有现有要求. 这些标志主要用于了解模块图的工具. 用户应该更喜欢'go get path @ version'或'go get path @ none',它们可以根据需要进行其他go.mod调整,以满足其他模块施加的约束.

-exclude = path @ version和-dropexclude = path @ version标志添加和删除给定模块路径和版本的排除项. 请注意,如果该排除已经存在,则-exclude = path @ version是no-op.

-replace = old [@v] = new [@v]和-dropreplace = old [@v]标志添加和删除给定模块路径和版本对的替换. 如果在old @ v中省略了@v,则替换适用于所有具有旧模块路径的版本. 如果省略了new @ v中的@v,则新路径应为本地模块根目录,而不是模块路径. 请注意,-replace会覆盖所有旧[@v]的现有替换项.

可以重复-require,-droprequire,-exclude,-dropexclude,-replace和-dropreplace编辑标记,并按照给定的顺序应用更改.

-go = version标志设置预期的Go语言版本.

-print标志以其文本格式打印最终的go.mod,而不是将其写回到go.mod.

-json标志以JSON格式打印最终的go.mod文件,而不是将其写回到go.mod. JSON输出对应于以下Go类型:

type Module struct {
	Path string
	Version string
}

type GoMod struct {
	Module  Module
	Go      string
	Require []Require
	Exclude []Module
	Replace []Replace
}

type Require struct {
	Path string
	Version string
	Indirect bool
}

type Replace struct {
	Old Module
	New Module
}

请注意,这仅描述go.mod文件本身,而不描述其他间接引用的模块. 对于可用于构建的全套模块,请使用" go list -m -json all".

例如,一个工具可以通过解析" go mod edit -json"的输出来获取go.mod作为数据结构,然后可以通过使用-require,-exclude等调用" go mod edit"来进行更改.

Print module requirement graph

Usage:

go mod graph

Graph以文本形式打印模块需求图(已应用替换项). 输出中的每一行都有两个以空格分隔的字段:一个模块及其要求之一. 每个模块都被标识为path @ version形式的字符串,但主模块除外,后者没有@version后缀.

Initialize new module in current directory

Usage:

go mod init [module]

Init初始化并将新的go.mod写入当前目录,实际上是创建一个以当前目录为根的新模块. 文件go.mod必须不存在. 如果可能,init将从导入注释(请参阅" go help importpath")或版本控制配置中猜测模块路径. 要覆盖此猜测,请提供模块路径作为参数.

Add missing and remove unused modules

Usage:

go mod tidy [-v]

Tidy确保go.mod与模块中的源代码匹配. 它添加了构建当前模块的程序包和依赖项所必需的所有缺少的模块,并删除了不提供任何相关程序包的未使用模块. 它还会将所有缺少的条目添加到go.sum中,并删除所有不必要的条目.

-v标志使tidy将有关已卸下模块的信息打印为标准错误.

Make vendored copy of dependencies

Usage:

go mod vendor [-v]

供应商重置主模块的供应商目录,以包括构建和测试所有主模块的软件包所需的所有软件包. 它不包括供应商软件包的测试代码.

-v标志使供应商将供应的模块和软件包的名称打印为标准错误.

Verify dependencies have expected content

Usage:

go mod verify

验证检查自下载以来,当前模块的依赖关系(存储在本地下载的源缓存中)是否未被修改. 如果所有模块均未修改,请验证打印"所有模块均已验证". 否则,它将报告哪些模块已更改,并导致" go mod"以非零状态退出.

Explain why packages or modules are needed

Usage:

go mod why [-m] [-vendor] packages...

Why shows a shortest path in the import graph from the main module to each of the listed packages. If the -m flag is given, why treats the arguments as a list of modules and finds a path to any package in each of the modules.

默认情况下,为什么要查询与"转到全部列出"匹配的软件包图,其中包括对可访问软件包的测试. -vendor标志导致为什么要排除依赖项测试.

输出是一系列节,在命令行上每个软件包或模块名称都有一个节,用空行分隔. 每个节都以注释行"#package"或"#module"开头,给出目标软件包或模块. 随后的行给出了通过导入图的路径,每行一个包. 如果未从主模块引用该软件包或模块,则该节将显示一个带括号的注释,表明该事实.

例如:

$ go mod why golang.org/x/text/language golang.org/x/text/encoding
# golang.org/x/text/language
rsc.io/quote
rsc.io/sampler
golang.org/x/text/language

# golang.org/x/text/encoding
(main module does not need package golang.org/x/text/encoding)
$

Compile and run Go program

Usage:

go run [build flags] [-exec xprog] package [arguments...]

运行编译并运行命名的主Go软件包. 通常,该软件包被指定为来自单个目录的.go源文件列表,但也可以是导入路径,文件系统路径或与单个已知软件包匹配的模式,如" go run"中所示. 或"运行我的/ cmd".

默认情况下," go run"直接运行编译的二进制文件:" a.out arguments ...". 如果给出了-exec标志,那么'go run'使用xprog调用二进制文件:

'xprog a.out arguments...'.

如果未提供-exec标志,则GOOS或GOARCH与系统默认值不同,并且可以在当前搜索路径中找到名为go_ $ GOOS_ $ GOARCH_exec的程序,例如," go run"使用该程序调用二进制文件'go_nacl_386_exec a.out参数...'. 当模拟器或其他执行方法可用时,这允许执行交叉编译的程序.

运行的退出状态不是已编译二进制文件的退出状态.

有关构建标志的更多信息,请参见" go help build". 有关指定软件包的更多信息,请参见"转到帮助软件包".

另请参阅:进行构建.

Test packages

Usage:

go test [build/test flags] [packages] [build/test flags & test binary flags]

"测试"自动测试由导入路径命名的软件包. 它以以下格式打印测试结果的摘要:

ok   archive/tar   0.011s
FAIL archive/zip   0.022s
ok   compress/gzip 0.033s
...

然后是每个失败软件包的详细输出.

"测试"会重新编译每个软件包以及名称与文件模式" * _test.go"匹配的所有文件. 这些其他文件可以包含测试功能,基准功能和示例功能. 有关更多信息,请参见" go help testfunc". 每个列出的软件包都会导致执行单独的测试二进制文件. 名称以" _"(包括" _test.go")或"."开头的文件. 被忽略.

声明后缀为" _test"的程序包的测试文件将被编译为单独的程序包,然后与主测试二进制文件链接并运行.

go工具将忽略名为" testdata"的目录,使其可用于保存测试所需的辅助数据.

作为构建测试二进制文件的一部分,对软件包及其测试源文件进行go测试运行以发现重大问题. 如果go vet发现任何问题,请go test报告那些问题并且不运行测试二进制文件. 仅使用默认的戈维检查的高可信度子集. 该子集是:"原子","布尔"," buildtags"," nilfunc"和" printf". 您可以通过" go doc cmd / vet"查看这些和其他兽医测试的文档. 要禁用go vet的运行,请使用-vet = off标志.

所有测试输出和摘要行都被打印到go命令的标准输出中,即使测试将它们打印成自己的标准错误也是如此. (go命令的标准错误保留用于构建测试的打印错误.)

Go测试以两种不同的模式运行:

第一种称为本地目录模式,发生在没有包参数的情况下调用go测试时(例如," go test"或" go test -v"). 在这种模式下,go test会编译在当前目录中找到的包源和测试,然后运行生成的测试二进制文件. 在这种模式下,缓存(下面讨论)被禁用. 软件包测试完成后,go test将打印摘要行,其中显示测试状态(" ok"或" FAIL"),软件包名称和经过时间.

第二种称为程序包列表模式,发生在使用显式程序包参数(例如" go test math"," go test./ ...",甚至" go test.")调用go test时. 在这种模式下,go test编译并测试命令行上列出的每个软件包. 如果包装测试通过,则go test仅打印最后的"确定"摘要行. 如果包装测试失败,则执行测试将打印完整的测试输出. 如果使用-bench或-v标志调用,则go test会打印完整的输出,即使通过包测试也是如此,以便显示请求的基准测试结果或详细的日志记录. 在所有列出的软件包的软件包测试完成并且打印了它们的输出之后,如果任何软件包测试失败,go test将打印最终的"失败"状态.

仅在软件包列表模式下,go test会缓存成功的软件包测试结果,以避免不必要的重复运行测试. 当可以从缓存中恢复测试结果时,go test将重新显示先前的输出,而不是再次运行测试二进制文件. 发生这种情况时,请在摘要行中测试打印'(cached)'代替经过的时间.

缓存中匹配项的规则是,运行涉及相同的测试二进制文件,并且命令行上的标志完全来自一组受限制的"可缓存"测试标志,定义为-cpu,-list,-parallel,-run ,-short和-v. 如果运行测试在该设置范围之外具有任何测试或非测试标志,则不会缓存结果. 要禁用测试缓存,请使用除可缓存标志以外的任何测试标志或参数. 显式禁用测试缓存的惯用方式是使用-count = 1. 测试是否在包的源根目录(通常是$ GOPATH)中打开文件,或参考环境变量的测试仅与文件和环境变量未更改的将来运行相匹配. 缓存的测试结果被视为立即执行,因此无论-timeout设置如何,成功的软件包测试结果都将被缓存并重新使用.

In addition to the build flags, the flags handled by 'go test' itself are:

-args
    Pass the remainder of the command line (everything after -args)
    to the test binary, uninterpreted and unchanged.
    Because this flag consumes the remainder of the command line,
    the package list (if present) must appear before this flag.

-c
    Compile the test binary to pkg.test but do not run it
    (where pkg is the last element of the package's import path).
    The file name can be changed with the -o flag.

-exec xprog
    Run the test binary using xprog. The behavior is the same as
    in 'go run'. See 'go help run' for details.

-i
    Install packages that are dependencies of the test.
    Do not run the test.

-json
    Convert test output to JSON suitable for automated processing.
    See 'go doc test2json' for the encoding details.

-o file
    Compile the test binary to the named file.
    The test still runs (unless -c or -i is specified).

测试二进制文件还接受控制测试执行的标志. 这些标志也可以通过" go test"访问. 有关详细信息,请参见" go help testflag".

有关构建标志的更多信息,请参见" go help build". 有关指定软件包的更多信息,请参见"转到帮助软件包".

另请参阅:进行构建,审核.

Run specified go tool

Usage:

go tool [-n] command [args...]

工具运行由参数标识的go工具命令. 不带任何参数,它将打印已知工具的列表.

-n标志使工具打印将要执行但不执行的命令.

有关每个工具命令的更多信息,请参见'go doc cmd / <command>'.

Print Go version

Usage:

go version [-m] [-v] [file ...]

版本会打印Go可执行文件的构建信息.

Go版本报告用于构建每个命名的可执行文件的Go版本.

如果在命令行上未命名文件,则go version将打印其自己的版本信息.

如果已命名目录,则go version递归地遍历该目录,查找可识别的Go二进制文件并报告其版本. 默认情况下,go版本不会报告在目录扫描期间发现的无法识别的文件. -v标志使它报告无法识别的文件.

-m标志使go version在可用时打印每个可执行文件的嵌入式模块版本信息. 在输出中,模块信息由版本行之后的多行组成,每行均由前导制表符缩进.

另请参阅:go doc runtime / debug.BuildInfo.

Report likely mistakes in packages

Usage:

go vet [-n] [-x] [-vettool prog] [build flags] [vet flags] [packages]

兽医在由导入路径命名的软件包上运行" Go vet"命令.

For more about vet and its flags, see 'go doc cmd/vet'. For more about specifying packages, see 'go help packages'. For a list of checkers and their flags, see 'go tool vet help'. For details of a specific checker such as 'printf', see 'go tool vet help printf'.

-n标志打印将要执行的命令. -x标志在执行命令时打印命令.

-vettool = prog标志选择带有替代或附加检查的其他分析工具. 例如,可以使用以下命令来构建和运行"阴影"分析器:

go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow
go vet -vettool=$(which shadow)

go vet支持的构建标志是那些控制软件包解析和执行的标志,例如-n,-x,-v,-tags和-toolexec. 有关这些标志的更多信息,请参见"构建帮助".

另请参阅:go fmt,go fix.

Build modes

" go build"和" go install"命令带有-buildmode参数,该参数指示要构建的目标文件类型. 当前支持的值为:

-buildmode=archive
	Build the listed non-main packages into .a files. Packages named
	main are ignored.

-buildmode=c-archive
	Build the listed main package, plus all packages it imports,
	into a C archive file. The only callable symbols will be those
	functions exported using a cgo //export comment. Requires
	exactly one main package to be listed.

-buildmode=c-shared
	Build the listed main package, plus all packages it imports,
	into a C shared library. The only callable symbols will
	be those functions exported using a cgo //export comment.
	Requires exactly one main package to be listed.

-buildmode=default
	Listed main packages are built into executables and listed
	non-main packages are built into .a files (the default
	behavior).

-buildmode=shared
	Combine all the listed non-main packages into a single shared
	library that will be used when building with the -linkshared
	option. Packages named main are ignored.

-buildmode=exe
	Build the listed main packages and everything they import into
	executables. Packages not named main are ignored.

-buildmode=pie
	Build the listed main packages and everything they import into
	position independent executables (PIE). Packages not named
	main are ignored.

-buildmode=plugin
	Build the listed main packages, plus all packages that they
	import, into a Go plugin. Packages not named main are ignored.

在AIX上,当链接使用使用-buildmode = c-archive构建的Go归档文件的C程序时,必须将-Wl,-bnoobjreorder传递给C编译器.

Calling between Go and C

Go和C / C ++代码之间有两种不同的调用方式.

第一个是cgo工具,它是Go发行版的一部分. 有关如何使用它的信息,请参阅cgo文档(go doc cmd / cgo).

The second is the SWIG program, which is a general tool for interfacing between languages. For information on SWIG see http://swig.org/. When running go build, any file with a .swig extension will be passed to SWIG. Any file with a .swigcxx extension will be passed to SWIG with the -c++ option.

使用cgo或SWIG时,go build会将任何.c,.m,.s或.S文件传递给C编译器,并将任何.cc,.cpp,.cxx文件传递给C ++编译器. 可以设置CC或CXX环境变​​量来分别确定要使用的C或C ++编译器.

Build and test caching

go命令缓存构建输出,以在将来的构建中重用. 缓存数据的默认位置是当前操作系统的标准用户缓存目录中名为go-build的子目录. 设置GOCACHE环境变量将覆盖此默认值,并且运行" go env GOCACHE"将打印当前的缓存目录.

go命令会定期删除最近未使用的缓存数据. 运行" go clean -cache"会删除所有缓存的数据.

构建缓存正确地说明了对Go源文件,编译器,编译器选项等的更改:在典型使用中,无需显式清理缓存. 但是,构建缓存不会检测对使用cgo导入的C库的更改. 如果您对系统上的C库进行了更改,则需要显式清除缓存,或者使用-a build标志(请参阅" go help build")来强制重建依赖于更新的C库的软件包.

go命令还可以缓存成功的软件包测试结果. 有关详情,请参见"进行帮助测试". 运行'go clean -testcache'会删除所有缓存的测试结果(但不会缓存生成的结果).

GODEBUG环境变量可以启用有关缓存状态的调试信息的打印:

GODEBUG = gocacheverify = 1导致go命令绕过任何缓存条目的使用,而是重新构建所有内容并检查结果是否与现有缓存条目匹配.

GODEBUG = gocachehash = 1导致go命令打印用于构造缓存查找键的所有内容哈希的输入. 输出是大量的,但是对于调试缓存很有用.

GODEBUG = gocachetest = 1使go命令打印有关是否重用缓存的测试结果的决策详细信息.

Environment variables

go命令及其调用的工具会查询环境变量以进行配置. 如果未设置环境变量,那么go命令将使用明智的默认设置. 要查看变量<NAME>的有效设置,请运行'go env <NAME>'. 要更改默认设置,请运行'go env -w <NAME> = <VALUE>'. 根据os.UserConfigDir的报告,使用'go env -w'更改的默认值记录在存储在按用户配置目录中的Go环境配置文件中. 可以通过设置环境变量GOENV来更改配置文件的位置,并且'go env GOENV'打印有效位置,但是'go env -w'不能更改默认位置. 有关详情,请参见"前往帮助环境".

通用环境变量:

GCCGO
	The gccgo command to run for 'go build -compiler=gccgo'.
GOARCH
	The architecture, or processor, for which to compile code.
	Examples are amd64, 386, arm, ppc64.
GOBIN
	The directory where 'go install' will install a command.
GOCACHE
	The directory where the go command will store cached
	information for reuse in future builds.
GODEBUG
	Enable various debugging facilities. See 'go doc runtime'
	for details.
GOENV
	The location of the Go environment configuration file.
	Cannot be set using 'go env -w'.
GOFLAGS
	A space-separated list of -flag=value settings to apply
	to go commands by default, when the given flag is known by
	the current command. Each entry must be a standalone flag.
	Because the entries are space-separated, flag values must
	not contain spaces. Flags listed on the command line
	are applied after this list and therefore override it.
GOOS
	The operating system for which to compile code.
	Examples are linux, darwin, windows, netbsd.
GOPATH
	For more details see: 'go help gopath'.
GOPROXY
	URL of Go module proxy. See 'go help modules'.
GOPRIVATE, GONOPROXY, GONOSUMDB
	Comma-separated list of glob patterns (in the syntax of Go's path.Match)
	of module path prefixes that should always be fetched directly
	or that should not be compared against the checksum database.
	See 'go help module-private'.
GOROOT
	The root of the go tree.
GOSUMDB
	The name of checksum database to use and optionally its public key and
	URL. See 'go help module-auth'.
GOTMPDIR
	The directory where the go command will write
	temporary source files, packages, and binaries.

与cgo一起使用的环境变量:

AR
	The command to use to manipulate library archives when
	building with the gccgo compiler.
	The default is 'ar'.
CC
	The command to use to compile C code.
CGO_ENABLED
	Whether the cgo command is supported. Either 0 or 1.
CGO_CFLAGS
	Flags that cgo will pass to the compiler when compiling
	C code.
CGO_CFLAGS_ALLOW
	A regular expression specifying additional flags to allow
	to appear in #cgo CFLAGS source code directives.
	Does not apply to the CGO_CFLAGS environment variable.
CGO_CFLAGS_DISALLOW
	A regular expression specifying flags that must be disallowed
	from appearing in #cgo CFLAGS source code directives.
	Does not apply to the CGO_CFLAGS environment variable.
CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
	Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
	but for the C preprocessor.
CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
	Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
	but for the C++ compiler.
CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
	Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
	but for the Fortran compiler.
CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
	Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
	but for the linker.
CXX
	The command to use to compile C++ code.
FC
	The command to use to compile Fortran code.
PKG_CONFIG
	Path to pkg-config tool.

特定于体系结构的环境变量:

GOARM
	For GOARCH=arm, the ARM architecture for which to compile.
	Valid values are 5, 6, 7.
GO386
	For GOARCH=386, the floating point instruction set.
	Valid values are 387, sse2.
GOMIPS
	For GOARCH=mips{,le}, whether to use floating point instructions.
	Valid values are hardfloat (default), softfloat.
GOMIPS64
	For GOARCH=mips64{,le}, whether to use floating point instructions.
	Valid values are hardfloat (default), softfloat.
GOWASM
	For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use.
	Valid values are satconv, signext.

专用环境变量:

GCCGOTOOLDIR
	If set, where to find gccgo tools, such as cgo.
	The default is based on how gccgo was configured.
GOROOT_FINAL
	The root of the installed Go tree, when it is
	installed in a location other than where it is built.
	File names in stack traces are rewritten from GOROOT to
	GOROOT_FINAL.
GO_EXTLINK_ENABLED
	Whether the linker should use external linking mode
	when using -linkmode=auto with code that uses cgo.
	Set to 0 to disable external linking mode, 1 to enable it.
GIT_ALLOW_PROTOCOL
	Defined by Git. A colon-separated list of schemes that are allowed
	to be used with git fetch/clone. If set, any scheme not explicitly
	mentioned will be considered insecure by 'go get'.
	Because the variable is defined by Git, the default value cannot
	be set using 'go env -w'.

可以从" go env"获得其他信息,但不能从环境中读取:

GOEXE
	The executable file name suffix (".exe" on Windows, "" on other systems).
GOGCCFLAGS
	A space-separated list of arguments supplied to the CC command.
GOHOSTARCH
	The architecture (GOARCH) of the Go toolchain binaries.
GOHOSTOS
	The operating system (GOOS) of the Go toolchain binaries.
GOMOD
	The absolute path to the go.mod of the main module,
	or the empty string if not using modules.
GOTOOLDIR
	The directory where the go tools (compile, cover, doc, etc...) are installed.

File types

go命令检查每个目录中一组受限文件的内容. 它基于文件名的扩展名标识要检查的文件. 这些扩展是:

.go
	Go source files.
.c, .h
	C source files.
	If the package uses cgo or SWIG, these will be compiled with the
	OS-native compiler (typically gcc); otherwise they will
	trigger an error.
.cc, .cpp, .cxx, .hh, .hpp, .hxx
	C++ source files. Only useful with cgo or SWIG, and always
	compiled with the OS-native compiler.
.m
	Objective-C source files. Only useful with cgo, and always
	compiled with the OS-native compiler.
.s, .S
	Assembler source files.
	If the package uses cgo or SWIG, these will be assembled with the
	OS-native assembler (typically gcc (sic)); otherwise they
	will be assembled with the Go assembler.
.swig, .swigcxx
	SWIG definition files.
.syso
	System object files.

除了.syso以外,每种类型的文件都可能包含构建约束,但是go命令停止在文件的第一项(不是空行或//样式行注释)中扫描构建约束. 有关更多详细信息,请参见go / build软件包文档.

The go.mod file

模块版本由源文件树定义,其根目录中带有go.mod文件. 运行go命令时,它将在当前目录中查找,然后在后续的父目录中查找go.mod,这些标志标记了主(当前)模块的根目录.

go.mod文件本身是面向行的,带有//注释,但没有/ * * /注释. 每行仅包含一个指令,由动词后跟参数组成. 例如:

module my/thing
go 1.12
require other/thing v1.0.2
require new/thing/v2 v2.3.4
exclude old/thing v1.2.3
replace bad/thing v1.4.5 => good/thing v1.4.5

这些动词是

module, to define the module path;
go, to set the expected language version;
require, to require a particular module at a given version or later;
exclude, to exclude a particular module version from use; and
replace, to replace a module version with a different module version.

排除和替换仅在主模块的go.mod中应用,并且在依赖项中被忽略. 有关详细信息,请参见https://research.swtch.com/vgo-mvs .

可以从相邻行中分解出前导动词以创建一个块,就像在Go导入中一样:

require (
	new/thing v2.3.4
	old/thing v1.2.3
)

go.mod文件既可以直接编辑,又可以通过工具轻松更新. " go mod edit"命令可用于从程序和工具中解析和编辑go.mod文件. 请参阅" go help mod edit".

每次使用模块图时,go命令都会自动更新go.mod,以确保go.mod始终准确地反映现实并且格式正确. 例如,考虑以下go.mod文件:

module M

require (
        A v1
        B v1.0.0
        C v1.0.0
        D v1.2.3
        E dev
)

exclude D v1.2.3

The update 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.

此更新修改了关于排除的要求,因此对排除的D v1.2.3的要求已更新为使用D的下一个可用版本,可能是D v1.2.4或D v1.3.0.

此更新消除了多余或误导的要求. 例如,如果A v1.0.0本身需要B v1.2.0和C v1.0.0,则go.mod对B v1.0.0的要求具有误导性(已被A对v1.2.0的要求所误导),以及它对C v1的要求. 0.0是多余的(表示A对相同版本的需求),因此两者都将被删除. 如果模块M包含直接从B或C导入软件包的软件包,则将保留要求,但将其更新为所使用的实际版本.

最后,更新将以规范格式重新格式化go.mod,以便将来的机械更改将使差异最小.

由于模块图定义了import语句的含义,因此加载包的所有命令也会使用并因此更新go.mod,包括go build,go get,go install,go list,go test,go mod graph,go mod tidy和去国防部为什么.

由go指令设置的预期语言版本确定编译模块时可用的语言功能. 该版本中可用的语言功能将可供使用. 在较早版本中删除或在较新版本中添加的语言功能将不可用. 请注意,语言版本不会影响构建标记,该构建标记由所使用的Go发行版确定.

GOPATH environment variable

Go路径用于解析导入语句. 它由go / build包实现并记录在文件中.

GOPATH环境变量列出了查找Go代码的位置. 在Unix上,该值为冒号分隔的字符串. 在Windows上,该值为分号分隔的字符串. 在计划9中,该值为列表.

如果未设置环境变量,则GOPATH缺省为用户主目录(Unix上的$ HOME / go,Windows上的%USERPROFILE%\ go)中名为" go"的子目录,除非该目录包含Go发行版. 运行" go env GOPATH"以查看当前的GOPATH.

请参阅https://golang.org/wiki/SettingGOPATH来设置自定义GOPATH.

GOPATH中列出的每个目录必须具有规定的结构:

src目录包含源代码. src下面的路径确定导入路径或可执行文件名称.

pkg目录包含已安装的软件包对象. 就像在Go树中一样,每个目标操作系统和体系结构对都有其自己的pkg子目录(pkg / GOOS_GOARCH).

如果DIR是GOPATH中列出的目录,则源为DIR / src / foo / bar的软件包可以作为" foo / bar"导入,并将其编译形式安装到" DIR / pkg / GOOS_GOARCH / foo / bar.a" ".

bin目录包含已编译的命令. 每个命令都以其源目录命名,但仅命名为最后一个元素,而不是整个路径. 也就是说,将源代码在DIR / src / foo / quux中的命令安装到DIR / bin / quux中,而不是DIR / bin / foo / quux中. 去除了" foo /"前缀,以便您可以将DIR / bin添加到PATH中以获取已安装的命令. 如果设置了GOBIN环境变量,则将命令安装到其命名的目录中,而不是DIR / bin. GOBIN必须是绝对路径.

这是示例目录布局:

GOPATH=/home/user/go

/home/user/go/
    src/
        foo/
            bar/               (go code in package bar)
                x.go
            quux/              (go code in package main)
                y.go
    bin/
        quux                   (installed command)
    pkg/
        linux_amd64/
            foo/
                bar.a          (installed package object)

Go搜索GOPATH中列出的每个目录以查找源代码,但是新软件包始终会下载到列表中的第一个目录中.

有关示例,请参见https://golang.org/doc/code.html .

GOPATH and Modules

使用模块时,GOPATH不再用于解析导入. 但是,它仍用于存储下载的源代码(在GOPATH / pkg / mod中)和已编译的命令(在GOPATH / bin中).

Internal Directories

只有以" internal"的父级为根的目录树中的代码才能导入名为" internal"的目录中或以下的代码. 这是上面目录布局的扩展版本:

/home/user/go/
    src/
        crash/
            bang/              (go code in package bang)
                b.go
        foo/                   (go code in package foo)
            f.go
            bar/               (go code in package bar)
                x.go
            internal/
                baz/           (go code in package baz)
                    z.go
            quux/              (go code in package main)
                y.go

z.go中的代码被导入为" foo / internal / baz",但是该import语句只能出现在以foo为根的子树中的源文件中. 源文件foo / f.go,foo / bar / x.go和foo / quux / y.go都可以导入" foo / internal / baz",但是源文件crash / bang / b.go不能.

See https://golang.org/s/go14internal for details.

Vendor Directories

Go 1.6包括对使用外部依赖项的本地副本来满足这些依赖项(通常称为供应商)的导入的支持.

目录" vendor"下的代码只能通过以" vendor"的父级为根的目录树中的代码导入,并且只能使用忽略该前缀直至并包括vendor元素的导入路径.

Here's the example from the previous section, but with the "internal" directory renamed to "vendor" and a new foo/vendor/crash/bang directory added:

/home/user/go/
    src/
        crash/
            bang/              (go code in package bang)
                b.go
        foo/                   (go code in package foo)
            f.go
            bar/               (go code in package bar)
                x.go
            vendor/
                crash/
                    bang/      (go code in package bang)
                        b.go
                baz/           (go code in package baz)
                    z.go
            quux/              (go code in package main)
                y.go

适用于内部的可见性规则相同,但是z.go中的代码被导入为" baz",而不是" foo / vendor / baz".

供应商目录中的代码在源目录树中更深处,而阴影在较高目录中. 在以foo为根的子树中," crash / bang"的导入将解析为" foo / vendor / crash / bang",而不是顶级的" crash / bang".

供应商目录中的代码不受导入路径检查的影响(请参阅" go help importpath").

When 'go get' checks out or updates a git repository, it now also updates submodules.

供应商目录不会影响" go get"首次检出的新存储库的位置:这些存储库始终位于主GOPATH中,而不位于供应商子树中.

有关详细信息,请参见https://golang.org/s/go15vendor .

Legacy GOPATH go get

" go get"命令根据go命令是以模块感知模式还是旧版GOPATH模式运行来更改行为. 即使在模块感知模式下,此帮助文本也可以作为" go help gopath-get"来访问,它描述了" go get",因为它在旧版GOPATH模式下运行.

用法:去获取[-d] [-f] [-t] [-u] [-v] [-fix] [-不安全] [build标志] [packages]

Get下载由导入路径命名的包及其依赖项. 然后安装命名包,例如" go install".

-d标志指示下载软件包后停止; 也就是说,它指示不要安装软件包.

-f标志仅在设置了-u后才有效,它会强制-u不验证每个软件包是否已从其导入路径所隐含的源代码控制存储库中检出. 如果源是原始文件的本地派生,这将很有用.

-fix标志指示在解决依赖关系或构建代码之前,先对下载的软件包运行修复工具.

-insecure标志允许使用非安全方案(例如HTTP)从存储库中获取信息并解析自定义域. 请谨慎使用.

-t标志指示还可以下载为指定软件包构建测试所需的软件包.

-u标志指示获取使用网络更新命名软件包及其依赖关系的信息. 默认情况下,get使用网络来检查丢失的软件包,但不使用它来查找对现有软件包的更新.

-v标志启用详细进度和调试输出.

Get还接受构建标志来控制安装. 请参阅"建立帮助".

When checking out a new package, get creates the target directory GOPATH/src/<import-path>. If the GOPATH contains multiple entries, get uses the first one. For more details see: 'go help gopath'.

在签出或更新软件包时,get查找与本地安装的Go版本匹配的分支或标记. 最重要的规则是,如果本地安装正在运行版本" go1",请获取搜索名为" go1"的分支或标记的步骤. 如果不存在这样的版本,它将获取程序包的默认分支.

当go get签出或更新Git存储库时,它还会更新该存储库引用的所有git子模块.

永远不要检出或更新存储在供应商目录中的代码.

有关指定软件包的更多信息,请参见"转到帮助软件包".

有关"获取"如何找到要下载的源代码的更多信息,请参见"获取帮助importpath".

本文介绍了使用GOPATH管理源代码和依赖项时get的行为. 相反,如果go命令以模块感知模式运行,则get的标志和效果的详细信息会更改," go help get"也会更改. 请参阅"前往帮助模块"和"前往帮助模块-获取".

另请参阅:进行构建,进行安装,进行清洁.

Module proxy protocol

Go模块代理是可以响应GET请求以指定形式的URL的任何Web服务器. 这些请求没有查询参数,因此即使从固定文件系统(包括file:/// URL)提供服务的站点也可以作为模块代理.

发送到Go模块代理的GET请求是:

GET $ GOPROXY / <模块> / @ v / list返回给定模块的所有已知版本的列表,每行一个.

GET $ GOPROXY / <模块> / @ v / <版本> .info返回有关给定模块版本的JSON格式的元数据.

GET $ GOPROXY / <模块> / @ v / <版本> .mod返回给定模块版本的go.mod文件.

GET $ GOPROXY / <模块> / @ v / <版本> .zip返回该模块给定版本的zip存档.

为了避免从区分大小写的文件系统提供服务时出现问题,<module>和<version>元素进行了大小写编码,将每个大写字母替换为感叹号,后跟相应的小写字母:github.com/Azure编码为github.com/!azure.

有关给定模块的JSON格式的元数据与此Go数据结构相对应,将来可能会扩展:

type Info struct {
    Version string    // version string
    Time    time.Time // commit time
}

给定模块的特定版本的zip归档文件是标准的zip文件,其中包含与模块的源代码和相关文件相对应的文件树. 归档文件使用斜杠分隔的路径,并且归档文件中的每个文件路径都必须以<module> @ <version> /开头,其中模块和版本被直接替换,而不使用大小写编码. 模块文件树的根对应于归档文件中的<module> @ <version> /前缀.

即使直接从版本控制系统下载,go命令也可以合成显式信息,mod和zip文件,并将它们存储在本地缓存$ GOPATH / pkg / mod / cache / download中,就像直接从版本控制系统下载它们一样代理. 缓存的布局与代理URL空间相同,因此在$ GOPATH / pkg / mod / cache / download处(或将其复制到) https://example.com/proxy可以使其他用户通过以下方式访问那些缓存的模块版本GOPROXY = https://example.com/proxy

Import path syntax

导入路径(请参阅" go帮助软件包")表示存储在本地文件系统中的软件包. 通常,导入路径表示标准软件包(例如" unicode / utf8")或在一个工作空间中找到的软件包(有关更多详细信息,请参见:" go help gopath").

Relative import paths

以./或../开头的导入路径称为相对路径. 工具链通过两种方式将相对导入路径作为快捷方式来支持.

首先,相对路径可以用作命令行的简写形式. 如果您在包含以" unicode"导入的代码的目录中工作,并且要运行" unicode / utf8"的测试,则可以键入" go test ./utf8",而不需要指定完整路径. 同样,在相反的情况下," go test .."将从" unicode / utf8"目录中测试" unicode". 还允许使用相对模式,例如" go test./ ..."来测试所有子目录. 有关模式语法的详细信息,请参见"转到帮助包".

其次,如果您不在工作空间中编译Go程序,则可以在该程序的import语句中使用相对路径来引用附近的代码,这些代码也不在工作空间中. 这样可以轻松地在常规工作空间之外尝试小型多包程序,但是此类程序无法通过" go install"安装(没有可用于安装它们的工作空间),因此每次它们从头开始进行重建被建造. 为避免歧义,Go程序不能在工作空间中使用相对的导入路径.

Remote import paths

某些导入路径还描述了如何使用修订控制系统获取程序包的源代码.

A few common code hosting sites have special syntax:

Bitbucket (Git, Mercurial)

	import "bitbucket.org/user/project"
	import "bitbucket.org/user/project/sub/directory"

GitHub (Git)

	import "github.com/user/project"
	import "github.com/user/project/sub/directory"

Launchpad (Bazaar)

	import "launchpad.net/project"
	import "launchpad.net/project/series"
	import "launchpad.net/project/series/sub/directory"

	import "launchpad.net/~user/project/branch"
	import "launchpad.net/~user/project/branch/sub/directory"

IBM DevOps Services (Git)

	import "hub.jazz.net/git/user/project"
	import "hub.jazz.net/git/user/project/sub/directory"

对于托管在其他服务器上的代码,导入路径可以使用版本控制类型进行限定,或者go工具可以通过https / http动态获取导入路径,并从HTML中的<meta>标记中发现代码所在的位置.

要声明代码位置,请输入表单的导入路径

repository.vcs/path

使用命名的版本控制系统指定给定的存储库(带或不带.vcs后缀),然后指定该存储库内的路径. 支持的版本控制系统是:

Bazaar      .bzr
Fossil      .fossil
Git         .git
Mercurial   .hg
Subversion  .svn

例如,

import "example.org/user/foo.hg"

表示Mercurial存储库的根目录,位于example.org/user/foo或foo.hg,并且

import "example.org/repo.git/foo/bar"

表示位于example.org/repo或repo.git的Git存储库的foo / bar目录.

如果版本控制系统支持多种协议,则在下载时依次尝试每种协议. 例如,Git下载尝试https://,然后尝试git + ssh://.

默认情况下,下载仅限于已知的安全协议(例如https,ssh). 要覆盖Git下载的此设置,可以设置GIT_ALLOW_PROTOCOL环境变量(有关更多详细信息,请参见:"转到帮助环境").

如果导入路径不是已知的代码托管站点,并且也缺少版本控制限定符,则go工具将尝试通过https / http获取导入,并在文档的HTML <head>中寻找<meta>标记.

meta标签的格式为:

<meta name="go-import" content="import-prefix vcs repo-root">

import-prefix是与存储库根目录相对应的导入路径. 它必须是前缀或与使用" go get"获取的软件包的完全匹配. 如果不完全匹配,则会在前缀处发出另一个http请求,以验证<meta>标签是否匹配.

meta标签应尽可能早地出现在文件中. 特别是,它应该出现在任何原始JavaScript或CSS之前,以避免混淆go命令的受限解析器.

vcs是" bzr","化石"," git"," hg"," svn"之一.

repo-root是版本控制系统的根,该版本控制系统包含一个方案,但不包含.vcs限定符.

例如,

import "example.org/pkg/foo"

将导致以下请求:

https://example.org/pkg/foo?go-get=1 (preferred)
http://example.org/pkg/foo?go-get=1  (fallback, only with -insecure)

如果该页面包含meta标签

<meta name="go-import" content="example.org git https://code.org/r/p/exproj">

go工具将验证https://example.org/?go-get=1包含相同的元标记,然后将git clone https://code.org/r/p/exproj克隆到GOPATH / src / example.org .

使用GOPATH时,将下载的软件包写入GOPATH环境变量中列出的第一个目录. (请参阅" go help gopath-get"和" go help gopath".)

使用模块时,下载的软件包将存储在模块缓存中. (请参阅" go help module-get"和" go help goproxy".)

使用模块时,会识别go-import元标记的其他变体,它比列出版本控制系统的首选. 该变体使用" mod"作为内容值中的vc,如下所示:

<meta name="go-import" content="example.org mod https://code.org/moduleproxy">

这个标签意味着从URL https://code.org/moduleproxy上可用的模块代理中获取路径以example.org开头的模块. 有关代理协议的详细信息,请参见" go help goproxy".

Import path checking

当上述自定义导入路径功能重定向到已知的代码托管站点时,使用自定义域或已知的托管站点,每个生成的包都有两个可能的导入路径.

如果package语句紧接着(在下一个换行符之前)后面是以下两种形式之一的注释,则称该语句具有"导入注释":

package math // import "path"
package math /* import "path" */

go命令将拒绝安装带有导入注释的软件包,除非该导入路径引用了该软件包. 通过这种方式,导入注释使程序包作者可以确保使用了自定义导入路径,而不是指向基础代码托管站点的直接路径.

在供应商树中找到的代码禁用了导入路径检查. 这样就可以将代码复制到供应商树中的备用位置,而无需更新导入注释.

使用模块时,导入路径检查也被禁用. go.mod文件的module语句已淘汰了导入路径注释.

有关详细信息,请参见https://golang.org/s/go14customimport .

Modules, module versions, and more

模块是相关的Go软件包的集合. 模块是源代码交换和版本控制的单元. go命令直接支持使用模块,包括记录和解决对其他模块的依赖性. 模块取代了旧的基于GOPATH的方法来指定在给定版本中使用哪些源文件.

Module support

Go 1.13包含对Go模块的支持. 每当在当前目录或其父目录中找到go.mod文件时,默认情况下就启用模块感知模式.

充分利用模块支持的最快方法是检出存储库,在其中创建go.mod文件(在下一节中介绍),然后从该文件树中运行go命令.

对于更细粒度的控制,Go 1.13继续使用临时环境变量GO111MODULE,可以将其设置为三个字符串值之一:off,on或auto(默认值). 如果GO111MODULE = on,则go命令需要使用模块,从不咨询GOPATH. 我们称此命令为模块感知或以"模块感知模式"运行. 如果GO111MODULE = off,那么go命令将永远不使用模块支持. 相反,它在供应商目录和GOPATH中查找依赖关系. 我们现在将此称为" GOPATH模式". 如果GO111MODULE = auto或未设置,则go命令根据当前目录启用或禁用模块支持. 仅当当前目录包含go.mod文件或位于包含go.mod文件的目录下方时,才启用模块支持.

在模块感知模式下,GOPATH不再定义构建期间导入的含义,但仍存储下载的依赖项(在GOPATH / pkg / mod中)和已安装的命令(在GOPATH / bin中,除非设置了GOBIN).

Defining a module

模块由Go源文件树定义,该树的根目录中带有go.mod文件. 包含go.mod文件的目录称为模块根目录. 通常,模块根也将对应于源代码存储库根(但通常不需要). 该模块是模块根目录及其子目录中所有Go软件包的集合,但不包括具有自己的go.mod文件的子树.

"模块路径"是对应于模块根目录的导入路径前缀. go.mod文件定义模块路径,并通过提供模块路径和版本来列出在构建期间解析导入时应使用的其他模块的特定版本.

例如,此go.mod声明包含该目录的目录是路径为example.com/m的模块的根目录,并且还声明该模块依赖于golang.org/x/text和gopkg.in的特定版本. /yaml.v2:

module example.com/m

require (
	golang.org/x/text v0.3.0
	gopkg.in/yaml.v2 v2.1.0
)

go.mod文件还可以指定仅在直接构建模块时适用的替换版本和排除版本; 当模块合并到较大的版本中时,它们将被忽略. 有关go.mod文件的更多信息,请参见" go help go.mod".

要启动新模块,只需在模块目录树的根目录中创建一个go.mod文件,其中仅包含一个模块语句. 可以使用'go mod init'命令执行此操作:

go mod init example.com/m

在已经使用现有的依赖管理工具(例如godep,glide或dep)的项目中," go mod init"还将添加与现有配置匹配的require语句.

一旦存在go.mod文件,则无需执行其他步骤:go命令(例如" go build"," go test",甚至" go list")将根据需要自动添加新的依赖关系,以实现导入.

The main module and the build list

"主模块"是包含运行go命令的目录的模块. go命令通过在当前目录,当前目录的父目录或父目录的父目录等中查找go.mod来找到模块​​的根目录.

主模块的go.mod文件通过require,replace和exclude语句定义了go命令可使用的精确的软件包集. 通过在require语句之后找到的依赖模块,也有助于定义该组软件包,但只能通过其go.mod文件的require语句来进行:依赖模块中的所有replace和exclude语句都将被忽略. 因此,replace和exclude语句允许主模块完全控制其自身的构建,而不受依赖项的完全控制.

提供要构建的软件包的模块集称为"构建列表". 最初,构建列表仅包含主模块. 然后,go命令将列表中已经存在的模块所需的确切模块版本递归添加到列表中,直到没有内容可添加到列表中为止. 如果将特定模块的多个版本添加到列表中,则最后仅保留最新版本(根据语义版本排序)以供构建使用.

"执行列表"命令提供有关主模块和构建列表的信息. 例如:

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

go.mod文件旨在由程序员和工具读取和编辑. go命令本身会自动更新go.mod文件,以维持标准格式和require语句的准确性.

任何发现不熟悉的导入的go命令都将查找包含该导入的模块,并将该模块的最新版本自动添加到go.mod中. 因此,在大多数情况下,只需将导入添加到源代码并运行" go build"," go test"甚至" go list"即可:作为分析软件包的一部分,go命令将发现并解决导入问题并更新go.mod文件.

即使只考虑模块中的单个软件包,任何go命令都可以确定缺少模块要求,必须添加该模块. 另一方面,要确定不再需要模块需求并可以将其删除,则需要在所有可能的构建配置(体系结构,操作系统,构建标签等)中完整查看模块中的所有软件包. " go mod tidy"命令可构建该视图,然后添加所有缺少的模块要求并删除不必要的模块要求.

作为在go.mod中维护require语句的一部分,go命令跟踪哪些提供了由当前模块直接导入的软件包,哪些提供了仅由其他模块依赖项间接使用的软件包. 仅间接用途所需的要求在go.mod文件中带有" //间接"注释. 一旦其他直接需求隐含了间接需求,它们就会自动从go.mod文件中删除. 间接需求仅在使用无法说明其某些依赖关系的模块或在其自身声明的要求之前显式升级模块的依赖关系时出现.

由于这种自动维护,go.mod中的信息是该版本的最新可读描述.

" go get"命令更新go.mod来更改构建中使用的模块版本. 一个模块的升级可能意味着升级其他模块,类似地,一个模块的降级可能意味着降级其他模块. 'go get'命令也会进行这些隐含更改. 如果直接编辑go.mod," go build"或" go list"之类的命令将假定要进行升级,并自动进行任何隐式升级并更新go.mod以反映它们.

" go mod"命令提供了用于维护和理解模块以及go.mod文件的其他功能. 请参阅" go help mod".

-mod build标志提供了对go.mod的更新和使用的附加控制.

如果使用-mod = readonly调用,则上述隐式自动更新go.mod不允许使用go命令. 而是在需要对go.mod进行任何更改时失败. 此设置对于检查go.mod不需要更新(例如在持续集成和测试系统中)是最有用的. 即使使用-mod = readonly," go get"命令仍然可以更新go.mod,并且" go mod"命令不使用-mod标志(或任何其他构建标志).

如果使用-mod = vendor调用,则go命令将假定vendor目录包含正确的依赖关系副本,并忽略go.mod中的依赖关系描述.

Pseudo-versions

go.mod文件和go命令通常使用语义版本作为描述模块版本的标准形式,因此可以比较版本以确定哪个版本应该早于或晚于其他版本. 像v1.2.3这样的模块版本是通过在基础源存储库中标记修订来引入的. 未标记的修订版本可以使用"伪版本"来引用,例如v0.0.0-yyyymmddhhmmss-abcdefabcdef,其中时间是UTC的提交时间,最后的后缀是提交哈希的前缀. 时间部分确保可以比较两个伪版本以确定以后发生的情况,提交哈希标识基础提交,并且前缀(在此示例中为v0.0.0-)从提交图中的最新标记版本派生在此提交之前.

有三种伪版本形式:

如果在目标提交之前不存在带有适当主版本的较早版本的提交,则使用vX.0.0-yyyymmddhhmmss-abcdefabcdef. (这最初是唯一的格式,因此,某些较旧的go.mod文件甚至对于遵循标签的提交也使用此格式.)

如果目标提交之前的最新版本的提交是vX.YZ-pre,则使用vX.YZ-pre.0.yyyymmddhhmmss-abcdefabcdef.

vX.Y.(Z + 1)-0.yyyymmddhhmmss-abcdefabcdef用于目标提交之前的最新版本的提交是vX.YZ

不需要手动输入伪版本:go命令将接受纯提交哈希并将其自动转换为伪版本(或标记版本)(如果可用). 此转换是模块查询的示例.

Module queries

go命令在命令行和主模块的go.mod文件中都接受"模块查询"来代替模块版本. (评估主模块的go.mod文件中找到的查询后,go命令更新文件以将查询替换为其结果.)

完整指定的语义版本(例如" v1.2.3")将评估为该特定版本.

语义版本前缀,例如" v1"或" v1.2",将评估为具有该前缀的最新可用标记版本.

语义版本比较,例如" <v1.2.3"或""> = v1.5.6",将评估为最接近比较目标的可用标记版本(<和<=的最新版本,>和>的最早版本=).

字符串" latest"与最新的可用标记版本匹配,或者与底层源存储库的最新无标记版本匹配.

字符串" upgrade"类似于" latest",但是如果当前需要的模块版本比" latest"选择的版本更高(例如,较新的预发行版本),则" upgrade"将选择更高的版本代替.

字符串" patch"将与模块的最新可用标记版本匹配,该模块的主要和次要版本号与当前所需版本相同. 如果当前不需要任何版本,则"补丁"等效于"最新".

基础源存储库的修订标识符(例如,提交哈希前缀,修订标记或分支名称)选择该特定代码修订. 如果修订版本还标记有语义版本,则查询将评估为该语义版本. 否则,查询将评估为提交的伪版本. 请注意,不能以这种方式选择名称和其他查询语法匹配的分支和标记. 例如,查询" v2"表示以" v2"开头的最新版本,而不是名为" v2"的分支.

所有查询都更喜欢发行版而不是预发行版. 例如,即使" v1.2.3-pre1"更接近比较目标," <v1.2.3"将更喜欢返回" v1.2.2"而不是" v1.2.3-pre1".

主模块的go.mod中的exclude语句不允许的模块版本被视为不可用,并且无法由查询返回.

例如,这些命令都是有效的:

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

go命令要求模块使用语义版本,并希望这些版本准确描述兼容性:它假定v1.5.4是v1.5.3,v1.4.0甚至v1.0.0的向后兼容替代. 更一般而言,go命令期望软件包遵循"导入兼容性规则",即:

"如果旧软件包和新软件包具有相同的导入路径,则新软件包必须与旧软件包向后兼容."

由于go命令采用了导入兼容性规则,因此模块定义只能设置其依赖项之一的最低要求版本:它不能设置最大值或排除所选版本. 尽管如此,导入兼容性规则仍不能保证:v1.5.4可能有错误,而不是v1.5.3的向后兼容替代品. 因此,go命令永远不会从未请求的模块的较旧版本更新为较新版本.

在语义版本控制中,更改主版本号表示缺少与早期版本的向后兼容性. 为了保持导入兼容性,go命令要求主版本为v2或更高版本的模块使用主版本为最终元素的模块路径. 例如,example.com / m的v2.0.0版本必须改为使用模块路径example.com/m/v2,并且该模块中的软件包将使用该路径作为其导入路径前缀,例如example.com/m/v2 / sub / pkg. 以这种方式在模块路径和导入路径中包含主要版本号称为"语义导入版本控制". 主版本为v2及更高版本的模块的伪版本以该主版本而不是v0开头,如v2.0.0-20180326061214-4fc5987536ef中所示.

作为一种特殊情况,以gopkg.in/开头的模块路径将继续使用在该系统上建立的约定:主版本始终存在,并且其前面以点号而不是斜杠:gopkg.in/yaml.v1和gopkg.in/yaml.v2,而不是gopkg.in/yaml和gopkg.in/yaml/v2.

go命令将具有不同模块路径的模块视为无关模块:在example.com/m和example.com/m/v2之间不建立连接. 具有不同主要版本的模块可以在构建中一起使用,并且由于它们的软件包使用不同的导入路径而被分开.

在语义版本控制中,主要版本v0用于初始开发,表示没有稳定性或向后兼容的期望. 主版本v0不会出现在模块路径中,因为这些版本是为v1.0.0做准备的,并且v1也未出现在模块路径中.

在引入语义导入版本控制约定之前编写的代码可能使用主要版本v2,而后来使用的主要版本描述的版本与v0和v1中使用的未版本化导入路径相同. 为了容纳这样的代码,如果源代码存储库具有文件树的v2.0.0或更高版本的标签而没有go.mod,则该版本被视为v1模块可用版本的一部分,并且在转换后会给其提供一个+不兼容的后缀到模块版本,如v2.0.0 +不兼容. + incompatible标记也适用于从此类版本派生的伪版本,例如v2.0.1-0.yyyymmddhhmmss-abcdefabcdef + incompatible.

通常,在v0版本,预发行版本,伪版本或+不兼容版本的构建列表中有依赖关系(由'go list -m all'报告)表明升级时更有可能出现问题.这种依赖关系,因为不希望它们兼容.

https://research.swtch.com/vgo-import关于语义进口版本的更多信息,并查看https://semver.org/更多关于语义版本.

Module code layout

现在,请参阅https://research.swtch.com/vgo-module,以获取有关版本控制系统中源代码如何映射到模块文件树的信息.

Module downloading and verification

The go command can fetch modules from a proxy or connect to source control servers directly, according to the setting of the GOPROXY environment variable (see 'go help env'). The default setting for GOPROXY is "https://proxy.golang.org,direct", which means to try the Go module mirror run by Google and fall back to a direct connection if the proxy reports that it does not have the module (HTTP error 404 or 410). See https://proxy.golang.org/privacy for the service's privacy policy. If GOPROXY is set to the string "direct", downloads use a direct connection to source control servers. Setting GOPROXY to "off" disallows downloading modules from any source. Otherwise, GOPROXY is expected to be a comma-separated list of the URLs of module proxies, in which case the go command will fetch modules from those proxies. For each request, the go command tries each proxy in sequence, only moving to the next if the current proxy returns a 404 or 410 HTTP response. The string "direct" may appear in the proxy list, to cause a direct connection to be attempted at that point in the search. Any proxies listed after "direct" are never consulted.

GOPRIVATE和GONOPROXY环境变量允许绕过所选模块的代理. 有关详细信息,请参见"转到帮助模块-私有".

无论模块的来源如何,go命令都会根据已知的校验和检查下载内容,以检测从一天到第二天任何特定模块版本的内容中发生的意外更改. 该检查首先查询当前模块的go.sum文件,但回退到Go校验和数据库,该数据库由GOSUMDB和GONOSUMDB环境变量控制. 有关详情,请参见" go help module-auth".

请参阅" go help goproxy"以获取有关代理协议以及已缓存的已下载软件包格式的详细信息.

Modules and vendoring

使用模块时,go命令将完全忽略供应商目录.

默认情况下,go命令通过从模块源中下载模块并使用那些下载的副本来满足依赖关系(在验证之后,如上一节所述). 为了允许与旧版本的Go互操作,或确保将用于构建的所有文件一起存储在一个文件树中," go mod vendor"在主模块的根目录中创建一个名为vendor的目录并将其全部存储在其中支持主模块中的程序包的构建和测试所需的依赖模块中的程序包.

要使用主模块的顶级供应商目录进行构建以满足相关性(禁用常规网络源和本地缓存的使用),请使用" go build -mod = vendor". 请注意,仅使用主模块的顶级供应商目录. 其他位置的供应商目录仍然被忽略.

Module authentication using go.sum

go命令尝试验证每个下载的模块,并检查今天为特定模块版本下载的位是否与昨天下载的位匹配. 这样可以确保可重复的构建并检测是否引入了意想不到的更改(无论是否恶意).

在每个模块的根目录中,go命令与go.mod一起维护一个名为go.sum的文件,其中包含模块依赖项的加密校验和.

go.sum中每行的形式是三个字段:

<module> <version>[/go.mod] <hash>

每个已知的模块版本都会在go.sum文件中产生两行. 第一行给出了模块版本文件树的哈希值. 第二行在版本后附加" /go.mod",并仅给出模块版本(可能是合成的)go.mod文件的哈希. 仅限go.mod的哈希允许下载和认证模块版本的go.mod文件,该文件是计算依赖关系图所需的,而无需下载所有模块的源代码.

哈希以格式为" h <N>:"的算法前缀开头. 唯一定义的算法前缀是" h1:",它使用SHA-256.

Module authentication failures

go命令维护下载软件包的缓存,并在下载时计算并记录每个软件包的加密校验和. 在正常操作中,go命令对照这些预先计算的校验和检查主模块的go.sum文件,而不是在每次命令调用时重新计算它们. " go mod verify"命令检查模块下载的缓存副本是否仍然与记录的校验和以及go.sum中的条目匹配.

在日常开发中,给定模块版本的校验和永远不会改变. 给定的主模块每次使用依赖项时,go命令都会与主模块的go.sum一起检查其本地缓存副本,无论是否新鲜下载. 如果校验和不匹配,则go命令将不匹配报告为安全错误,并拒绝运行构建. 发生这种情况时,请谨慎操作:意外更改代码意味着今天的版本与昨天的版本不匹配,并且意外的更改可能没有用.

如果go命令报告go.sum不匹配,则所报告模块版本的下载代码与主模块先前版本中使用的代码不匹配. 在这一点上,重要的是找出正确的校验和,确定go.sum是错误的还是下载的代码是错误的. 通常go.sum是正确的:您想使用昨天使用的相同代码.

如果go.sum中尚未包含已下载的模块,并且该模块是公共可用的模块,则go命令将查询Go校验和数据库以获取预期的go.sum行. 如果下载的代码与这些行不匹配,则go命令将报告不匹配并退出. 请注意,go.sum中已列出的模块版本未咨询该数据库.

如果报告了go.sum不匹配,则始终值得调查为什么今天下载的代码与昨天下载的代码不同.

GOSUMDB环境变量标识要使用的校验和数据库的名称以及(可选)其公钥和URL,如下所示:

GOSUMDB="sum.golang.org"
GOSUMDB="sum.golang.org+<publickey>"
GOSUMDB="sum.golang.org+<publickey> https://sum.golang.org"

go命令知道sum.golang.org的公钥,并且名称sum.golang.google.cn(在中国大陆可用)连接到sum.golang.org校验和数据库; 使用任何其他数据库都需要显式提供公钥. URL默认为" https://",后跟数据库名称.

GOSUMDB默认为" sum.golang.org",这是Google运行的Go校验和数据库. 有关服务的隐私权政策,请参阅https://sum.golang.org/privacy .

如果将GOSUMDB设置为" off",或者使用-insecure标志调用了" go get",则将不查询校验和数据库,并且接受所有无法识别的模块,但其代价是放弃了经过验证的可重复下载的安全保证.对于所有模块. 绕过特定模块的校验和数据库的更好方法是使用GOPRIVATE或GONOSUMDB环境变量. 有关详细信息,请参见"转到帮助模块-私有".

" go env -w"命令(请参阅" go help env")可用于为以后的go命令调用设置这些变量.

Module configuration for non-public modules

go命令默认是从proxy.golang.org上的公共Go模块镜像下载模块. 默认情况下,它也将根据sum.golang.org上的公共Go校验和数据库来验证下载的模块,无论其来源如何. 这些默认设置适用于公开可用的源代码.

GOPRIVATE环境变量控制go命令认为哪个模块是私有的(不可公开获得),因此不应使用代理或校验和数据库. 该变量是模块路径前缀的逗号分隔的全局模式列表(按照Go的path.Match的语法). 例如,

GOPRIVATE=*.corp.example.com,rsc.io/private

使go命令将路径前缀与任一模式匹配的任何模块(包括git.corp.example.com/xyzzy、rsc.io/private和rsc.io/private/quux)视为私有模块.

GOPRIVATE环境变量也可以由其他工具使用以标识非公共模块. 例如,编辑者可以使用GOPRIVATE来决定是否将软件包导入超链接到godoc.org页面.

为了对模块下载和验证进行细粒度控制,GONOPROXY和GONOSUMDB环境变量接受相同类型的glob列表,并覆盖GOPRIVATE以分别决定是否使用代理数据库和校验和数据库.

例如,如果公司运行了为私有模块提供服务的模块代理,则用户可以使用以下命令配置go:

GOPRIVATE=*.corp.example.com
GOPROXY=proxy.example.com
GONOPROXY=none

这将告诉go命令和其他工具,以corp.example.com子域开头的模块是私有的,但是公司代理应用于下载公共模块和私有模块,因为GONOPROXY已设置为不会匹配任何模块,覆盖GOPRIVATE.

" go env -w"命令(请参阅" go help env")可用于为以后的go命令调用设置这些变量.

Package lists and patterns

许多命令适用于一组软件包:

go action [packages]

通常,[packages]是导入路径的列表.

是根路径或以开头的导入路径. 或..元素被解释为文件系统路径,并表示该目录中的软件包.

否则,导入路径P表示在GOPATH环境变量中列出的某些DIR的目录DIR / src / P中找到的软件包(有关更多详细信息,请参见:" go help gopath").

如果未提供导入路径,则该操作将应用于当前目录中的程序包.

对于使用go工具构建的软件包,不应使用四个保留的路径名称:

-" main"表示独立可执行文件中的顶级程序包.

-"全部"扩展到所有GOPATH树中找到的所有软件包. 例如,"全部列出"列出了本地系统上的所有软件包. 使用模块时,"全部"扩展到主模块中的所有软件包及其依赖关系,包括其中任何一个的测试所需的依赖关系.

-" std"就像所有其他东西一样,但扩展为仅标准Go库中的软件包.

-" cmd"扩展为Go存储库的命令及其内部库.

以" cmd /"开头的导入路径仅与Go存储库中的源代码匹配.

如果导入路径包含一个或多个" ..."通配符,则通配符是通配符,每个通配符都可以匹配任何字符串,包括空字符串和包含斜杠的字符串. 这样的模式将扩展到在GOPATH树中找到的所有名称与模式匹配的软件包目录.

为了使通用模式更方便,有两种特殊情况. 首先,模式末尾的/ ...可以匹配一个空字符串,因此net / ...可以同时将net和其子目录中的包(例如net / http)匹配. 其次,任何包含通配符的斜杠分隔模式元素都不会参与供应商软件包路径中" vendor"元素的匹配,因此./ ...不匹配./vendor或./子目录中的软件包. mycode / vendor,但是./vendor / ...和./mycode/vendor / ...可以. 但是请注意,本身包含代码的名为vendor的目录不是由供应商提供的软件包:cmd / vendor将是名为vendor的命令,并且模式cmd / ...与其匹配. 有关销售的更多信息,请参见golang.org/s/go15vendor.

导入路径还可以命名要从远程存储库下载的软件包. 运行" go help importpath"以获取详细信息.

Every package in a program must have a unique import path. By convention, this is arranged by starting each path with a unique prefix that belongs to you. For example, paths used internally at Google all begin with 'google', and paths denoting remote repositories begin with the path to the code, such as 'github.com/user/repo'.

程序中的程序包不必具有唯一的程序包名称,但是有两个保留的程序包名称具有特殊含义. 名称main表示命令,而不是库. 命令内置在二进制文件中,无法导入. 名称文档表示目录中非Go程序的文档. go命令将忽略软件包文档中的文件.

作为特殊情况,如果程序包列表是单个目录中的.go文件列表,则该命令将应用于完全由这些文件组成的单个合成程序包,而忽略这些文件中的任何构建约束并忽略其中的任何其他文件.目录.

以"."开头的目录和文件名. go工具会忽略" _"或" _",以及名为" testdata"的目录.

Testing flags

" go test"命令同时获取适用于" go test"本身的标志和适用于结果测试二进制文件的标志.

几个标志控制配置文件并编写适合" go tool pprof"的执行配置文件; 运行" go tool pprof -h"以获取更多信息. pprof的--alloc_space,--alloc_objects和--show_bytes选项控制如何显示信息.

" go test"命令可以识别以下标志,并控制任何测试的执行:

-bench regexp
    Run only those benchmarks matching a regular expression.
    By default, no benchmarks are run.
    To run all benchmarks, use '-bench .' or '-bench=.'.
    The regular expression is split by unbracketed slash (/)
    characters into a sequence of regular expressions, and each
    part of a benchmark's identifier must match the corresponding
    element in the sequence, if any. Possible parents of matches
    are run with b.N=1 to identify sub-benchmarks. For example,
    given -bench=X/Y, top-level benchmarks matching X are run
    with b.N=1 to find any sub-benchmarks matching Y, which are
    then run in full.

-benchtime t
    Run enough iterations of each benchmark to take t, specified
    as a time.Duration (for example, -benchtime 1h30s).
    The default is 1 second (1s).
    The special syntax Nx means to run the benchmark N times
    (for example, -benchtime 100x).

-count n
    Run each test and benchmark n times (default 1).
    If -cpu is set, run n times for each GOMAXPROCS value.
    Examples are always run once.

-cover
    Enable coverage analysis.
    Note that because coverage works by annotating the source
    code before compilation, compilation and test failures with
    coverage enabled may report line numbers that don't correspond
    to the original sources.

-covermode set,count,atomic
    Set the mode for coverage analysis for the package[s]
    being tested. The default is "set" unless -race is enabled,
    in which case it is "atomic".
    The values:
	set: bool: does this statement run?
	count: int: how many times does this statement run?
	atomic: int: count, but correct in multithreaded tests;
		significantly more expensive.
    Sets -cover.

-coverpkg pattern1,pattern2,pattern3
    Apply coverage analysis in each test to packages matching the patterns.
    The default is for each test to analyze only the package being tested.
    See 'go help packages' for a description of package patterns.
    Sets -cover.

-cpu 1,2,4
    Specify a list of GOMAXPROCS values for which the tests or
    benchmarks should be executed. The default is the current value
    of GOMAXPROCS.

-failfast
    Do not start new tests after the first test failure.

-list regexp
    List tests, benchmarks, or examples matching the regular expression.
    No tests, benchmarks or examples will be run. This will only
    list top-level tests. No subtest or subbenchmarks will be shown.

-parallel n
    Allow parallel execution of test functions that call t.Parallel.
    The value of this flag is the maximum number of tests to run
    simultaneously; by default, it is set to the value of GOMAXPROCS.
    Note that -parallel only applies within a single test binary.
    The 'go test' command may run tests for different packages
    in parallel as well, according to the setting of the -p flag
    (see 'go help build').

-run regexp
    Run only those tests and examples matching the regular expression.
    For tests, the regular expression is split by unbracketed slash (/)
    characters into a sequence of regular expressions, and each part
    of a test's identifier must match the corresponding element in
    the sequence, if any. Note that possible parents of matches are
    run too, so that -run=X/Y matches and runs and reports the result
    of all tests matching X, even those without sub-tests matching Y,
    because it must run them to look for those sub-tests.

-short
    Tell long-running tests to shorten their run time.
    It is off by default but set during all.bash so that installing
    the Go tree can run a sanity check but not spend time running
    exhaustive tests.

-timeout d
    If a test binary runs longer than duration d, panic.
    If d is 0, the timeout is disabled.
    The default is 10 minutes (10m).

-v
    Verbose output: log all tests as they are run. Also print all
    text from Log and Logf calls even if the test succeeds.

-vet list
    Configure the invocation of "go vet" during "go test"
    to use the comma-separated list of vet checks.
    If list is empty, "go test" runs "go vet" with a curated list of
    checks believed to be always worth addressing.
    If list is "off", "go test" does not run "go vet" at all.

以下标记也可以被"执行测试"识别,并且可以在执行过程中用于分析测试:

-benchmem
    Print memory allocation statistics for benchmarks.

-blockprofile block.out
    Write a goroutine blocking profile to the specified file
    when all tests are complete.
    Writes test binary as -c would.

-blockprofilerate n
    Control the detail provided in goroutine blocking profiles by
    calling runtime.SetBlockProfileRate with n.
    See 'go doc runtime.SetBlockProfileRate'.
    The profiler aims to sample, on average, one blocking event every
    n nanoseconds the program spends blocked. By default,
    if -test.blockprofile is set without this flag, all blocking events
    are recorded, equivalent to -test.blockprofilerate=1.

-coverprofile cover.out
    Write a coverage profile to the file after all tests have passed.
    Sets -cover.

-cpuprofile cpu.out
    Write a CPU profile to the specified file before exiting.
    Writes test binary as -c would.

-memprofile mem.out
    Write an allocation profile to the file after all tests have passed.
    Writes test binary as -c would.

-memprofilerate n
    Enable more precise (and expensive) memory allocation profiles by
    setting runtime.MemProfileRate. See 'go doc runtime.MemProfileRate'.
    To profile all memory allocations, use -test.memprofilerate=1.

-mutexprofile mutex.out
    Write a mutex contention profile to the specified file
    when all tests are complete.
    Writes test binary as -c would.

-mutexprofilefraction n
    Sample 1 in n stack traces of goroutines holding a
    contended mutex.

-outputdir directory
    Place output files from profiling in the specified directory,
    by default the directory in which "go test" is running.

-trace trace.out
    Write an execution trace to the specified file before exiting.

这些标志中的每一个也可以通过可选的"测试"来识别. 前缀,如-test.v中所示. 但是,当直接调用生成的测试二进制文件(" go test -c"的结果)时,前缀是必需的.

" go test"命令在调用测试二进制文件之前,视情况在可选软件包列表之前和之后重写或除去已识别的标志.

例如,命令

go test -v -myflag testdata -cpuprofile=prof.out -x

将编译测试二进制文件,然后以

pkg.test -test.v -myflag testdata -test.cpuprofile=prof.out

(-x标志被删除,因为它仅适用于go命令的执行,不适用于测试本身.)

The test flags that generate profiles (other than for coverage) also leave the test binary in pkg.test for use when analyzing the profiles.

当" go test"运行测试二进制文件时,它将在相应程序包的源代码目录中运行. 根据测试,直接调用生成的测试二进制文件时可能需要执行相同的操作.

命令行软件包列表(如果存在)必须出现在go test命令未知的任何标志之前. 继续上面的示例,程序包列表必须出现在-myflag之前,但可能出现在-v的任一侧.

当" go test"以程序包列表模式运行时," go test"会缓存成功的程序包测试结果,以避免不必要的重复运行测试. 要禁用测试缓存,请使用除可缓存标志以外的任何测试标志或参数. 显式禁用测试缓存的惯用方式是使用-count = 1.

为了避免将测试二进制文件的参数解释为已知标志或程序包名称,请使用-args(请参阅" go help test"),它将命令行的其余部分直接传递给未解释且未更改的测试二进制文件.

For instance, the command

go test -v -args -x -v

将编译测试二进制文件,然后以

pkg.test -test.v -x -v

Similarly,

go test -args math

将编译测试二进制文件,然后以

pkg.test math

在第一个示例中,-x和第二个-v不变地传递到测试二进制文件,并且对go命令本身没有影响. 在第二个示例中,参数math传递给测试二进制文件,而不是被解释为程序包列表.

Testing functions

" go test"命令希望在与被测软件包相对应的" * _test.go"文件中找到测试,基准测试和示例功能.

测试功能是一个名为TestXxx的功能(其中Xxx并非以小写字母开头),并且应该具有签名,

func TestXxx(t *testing.T) { ... }

基准函数是一个名为BenchmarkXxx的函数,应具有签名,

func BenchmarkXxx(b *testing.B) { ... }

示例函数与测试函数相似,但是不使用* testing.T报告成功或失败,而是将输出打印到os.Stdout. 如果函数中的最后一条注释以" Output:"开头,则将输出与注释进行精确比较(请参见下面的示例). 如果最后一条注释以" Unordered output:"开头,则将输出与注释进行比较,但是将忽略行的顺序. 没有此类注释的示例已编译但未执行. 在" Output:"之后没有文本的示例将被编译,执行,并且预期不会产生任何输出.

Godoc显示ExampleXxx的主体,以演示函数Xxx,常量或变量的用法. 接收器类型为T或* T的方法M的示例名为ExampleT_M. 对于给定的函数,常量或变量,可能有多个示例,以尾随_xxx加以区分,其中xxx是不以大写字母开头的后缀.

这是一个示例示例:

func ExamplePrintln() {
	Println("The output of\nthis example.")
	// Output: The output of
	// this example.
}

这是另一个示例,其中输出的顺序被忽略:

func ExamplePerm() {
	for _, value := range Perm(4) {
		fmt.Println(value)
	}

	// Unordered output: 4
	// 2
	// 1
	// 3
	// 0
}

当整个测试文件包含单个示例函数,至少一个其他函数,类型,变量或常量声明,并且不包含测试或基准测试函数时,将以示例形式显示.

有关更多信息,请参见测试包的文档.

Subdirectories

Name Synopsis
..

by  ICOPY.SITE