GoLang 终端命令

GoLang 专栏收录该内容
3 篇文章 0 订阅

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

用法:

go <command> [arguments]

这些命令是:

bug         启动bug报告 
build       构建编译软件包和依赖关系
clean       删除对象文件和缓存文件
doc         显示软件包或符号的文档
env         打印Go环境信息
fix         更新软件包以使用新API 
fmt         gofmt(重新格式化)软件包源
generate    处理源生成生成Go文件
get         向当前模块添加依赖项并进行安装
install     编译并安装软件包以及依赖项
list        软件包或模块列表
mod         模块维护
run         编译并运行Go程序
test        测试包
tool        运行指定的go工具
version     打印Go版本
vet         报告软件包中可能存在的错误

使用“ go help <command> ”可获取有关命令的更多信息。

其他帮助主题:

buildconstraint 生成约束
buildmode       生成模式
c               Go和C 
cache           调用生成和测试缓存
environment     环境变量
filetype        文件类型
go.mod          go.mod文件
gopath          GOPATH环境变量
gopath-get      获取旧版GOPATH go获取
goproxy         模块代理协议
importpath      导入路径语法
modules         模块版本以及更多
module-get      module-aware go get
module-auth     module authentication using go.sum
module-private  module configuration for non-public modules
packages        软件包列表和模式
testflag        测试标志
testfunc        测试功能

使用“ go help <topic>”获得有关该主题的更多信息。

启动错误报告

用法:

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

编译软件包和依赖项

用法:

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 标志安装作为目标依赖项的软件包。

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

- 
	强制重建已经更新的软件包。
-n 
	打印命令,但不运行它们。
-pn 
	可以并行运行
	的程序的数量,例如构建命令或测试二进制文件。
	默认值为可用的CPU数量。
-race 
	启用数据竞争检测。
	仅在linux / amd64,freebsd / amd64,darwin / amd64,windows / amd64,
	linux / ppc64le和linux / arm64上受支持(仅适用于48位VMA)。
-msan 
	启用与内存清理程序的互操作。
	仅在linux / amd64,linux / arm64上受支持,
	并且仅以Clang / LLVM作为主机C编译器受支持。
	在linux / arm64上,将使用饼图构建模式。
-v
	在编译时打印软件包的名称。
-work 
	打印临时工作目录的名称,
	退出时不要删除它。
-x 
	打印命令。

-asmflags'[pattern =] arg list' 
	参数传递给每个go工具asm调用。
-buildmode模式
	使用的构建模式。有关更多信息,请参见“进入帮助构建模式”。
-compiler name 
	要在运行时使用的编译器名称。Compiler(gccgo或gc)。
-gccgoflags'[pattern =] arg list' 
	参数传递给每个gccgo编译器/链接器调用。
-gcflags'[pattern =] arg list' 
	参数传递给每个go工具编译调用。
-installsuffix后缀
	在软件包安装目录的名称中使用后缀,
	以使输出与默认版本分开。
	如果使用-race标志,则安装后缀将自动设置为race,
	或者,如果显式设置,则后缀_race。对于-msan 
	标志也是如此。使用需要非默认编译标志的-buildmode选项
	具有类似的效果。
-ldflags'[pattern =] arg list' 
	参数在每次go工具链接调用时传递。
-linkshared 
	构建代码,该代码将链接到以前
	使用-buildmode = shared创建的共享库。
-mod模式
	要使用的模块下载模式:只读,供应商或mod。
	有关更多信息,请参见“转到帮助模块”。
-modcacherw 
	将新创建的目录保留在模块高速缓存中,
	而不是将其设为只读。
-modfile文件(
	处于模块感知模式),读取(并可能写入)备用go.mod 
	文件,而不是模块根目录中的文件。
	为了确定模块的根
	目录,仍必须存在一个名为“ go.mod”的文件,但无法访问该文件。指定
	-modfile时,还将使用备用的go.sum文件:其路径是
	通过修剪“ .mod”扩展名并附加“ .sum” 从-modfile标志派生的。
-pkgdir dir 
	从dir而不是通常的位置安装和加载所有软件包。
	例如,使用非标准配置进行构建时,
	使用-pkgdir将生成的软件包保留在单独的位置。
-tags标签,列出
	以逗号分隔的构建标签列表,以在
	构建过程中认为满意。有关构建标记的更多信息,请参阅
	go / build软件包的文档中的构建约束说明。
	(Go的早期版本使用空格分隔的列表,
	但已弃用该格式,但仍可识别。)- 
trimpath 
	从生成的可执行文件中删除所有文件系统路径。
	记录的文件名将
	以“ go”(对于标准库),
	模块path @ version(使用模块时)
	或纯导入路径(使用GOPATH时)开头,而不是绝对文件系统路径。
-toolexec'cmd args' 
	一个程序,用于调用诸如vet和asm之类的工具链程序。
	例如,go命令将运行
	'cmd args / path / to / asm <asm的参数> ,而不是运行asm 。

-asmflags,-gccgoflags,-gcflags和-ldflags标志接受以空格分隔的参数列表,以在构建期间传递给基础工具。要在列表中的元素中嵌入空格,请用单引号或双引号将其引起来。参数列表之前可以有一个软件包模式和一个等号,这将使用该参数列表限制为与该模式匹配的软件包的构建(有关软件包模式的说明,请参阅“ go帮助软件包”)。如果没有模式,则参数列表仅适用于命令行上命名的软件包。可以用不同的模式来重复这些标志,以便为不同的软件包集指定不同的参数。如果程序包与多个标志中给出的模式匹配,则命令行上的最新匹配将获胜。例如,“ go build -gcflags = -S fmt”

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

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

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

删除目标文件和缓存的文件

用法:

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

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

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

_obj /旧对象目录,在Makefiles 
_test /旧测试目录中,在Makefiles 
_testmain.go旧文件中,在Makefiles 
test.out旧测试日志中,在Makefiles 
build.out旧测试日志中,在Makefiles 
*.[568ao] 目标文件,来自gofile的Makefiles 

DIR(.exe),来自go 
test的DIR.test(.exe),来自go test的-c 
MAINFILE(.exe),
*.so 来自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”。

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

显示包装或符号的文档

用法:

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

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

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

没有给定参数,即以

go doc

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

当使用一个参数运行时,该参数被视为要记录的项目的类似于Go语法的表示形式。自变量选择的内容取决于GOROOT和GOPATH中安装的内容以及自变量的形式,其形式如下:

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

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

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

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

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

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

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

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

例子:

go doc 
	显示当前软件包的文档。
go doc Foo 
	在当前软件包中显示Foo的文档。
	(Foo以大写字母开头,因此它不能与
	软件包路径匹配。)
doc coding / json 
	显示encoding / json软件包的文档。
go doc json 
	编码/ json的简写。
go doc json.Number(或go doc json.number)
	显示json.Number的文档和方法摘要。
go doc json.Number.Int64(或转到doc json.number.int64),以
	显示json.Number的Int64方法的文档。
go doc cmd / doc 
	显示doc命令的软件包文档。
go doc -cmd cmd / doc
	在doc命令中显示软件包文档和导出的符号。
go doc template.new 
	显示html / template的New函数的文档。
	(html / template在文字/模板之前在词法上)
go doc text / template.new#一个参数
	显示text / template的New函数的文档。
go doc text / template new#两个参数
	显示text / template的New函数的文档。

至少在当前树中,这些调用都会打印
json.Decoder的Decode方法的文档:

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

标志:

-all 
	显示软件包的所有文档。
-c 
	匹配符号时要注意大小写。
-cmd 
	将命令(主程序包)视为常规程序包。
	否则,
	在显示软件包的顶级文档时,软件包主要的导出符号将被隐藏。
-short 
	每个符号的单行表示。
-src 
	显示该符号的完整源代码。这将
	显示其声明和
	定义的完整Go源代码,例如函数定义(包括
	主体),类型声明或封闭const 
	块。因此,输出可能包含未导出的
	详细信息。
-u
	显示未导出以及已导出
	符号,方法和字段的文档。

打印Go环境信息

用法:

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

Env打印Go环境信息。

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

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

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

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

有关环境变量的更多信息,请参见“转到帮助环境”。

更新软件包以使用新的API

用法:

go fix [packages]

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

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

要使用特定选项运行修复程序,请运行“执行工具修复程序”。

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

Gofmt(重新格式化)包源

用法:

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

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

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

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

-mod标志的值设置要使用的模块下载模式:只读或供应商。有关更多信息,请参见“转到帮助模块”。

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

另请参阅:修复,审核。

通过处理源生成Go文件

用法:

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

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

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

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

// go:生成命令参数...

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

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

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

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

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

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

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

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

$ GOARCH 
	执行架构(arm,amd64等)。
$ GOOS 
	执行操作系统(linux,windows等)。
$ GOFILE 
	文件的基本名称。
$ GOLINE 
	源文件中指令的行号。
$ GOPACKAGE 
	包含指令的文件包的名称。
$ DOLLAR 
	美元符号。

除了变量替换和带引号的字符串求值外,在命令行上不执行任何特殊处理,例如“ 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检查文件,但在构建期间将其忽略。

对于具有无效代码的软件包,仅生成具有有效package子句的源文件。

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

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

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

-run =“”(
	如果非空),它指定一个正则表达式来选择
	其完整原始源文本(不包括
	任何尾随空格和最终换行符)与
	表达式匹配的指令。

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

有关构建标志的更多信息,请参见“ go help build”。

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

将依赖项添加到当前模块并安装它们

用法:

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

获取解决方案并将依赖项添加到当前的开发模块,然后构建并安装它们。

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

对于每个命名的程序包或程序包模式,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也可用,则“ go get A”将使用最新的A,然后按照A的要求使用B v1.2.3。 (如果对某个特定模块有相互竞争的要求,则“获取”可通过获取最大请求版本来解决这些要求。)

-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)从存储库中获取信息并解析自定义域。请谨慎使用。GOINSECURE环境变量通常是更好的选择,因为它可以控制使用不安全方案可以检索哪些模块。有关详细信息,请参见“进入帮助环境”。

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

如果参数指定模块名称而不是程序包名称(因为模块的根目录中没有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。

编译并安装软件包和依赖项

用法:

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”。有关指定软件包的更多信息,请参见“转到帮助软件包”。

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

列出软件包或模块

用法:

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字段也设置为要测试的程序包的名称(“数学/ 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 used when loading this module, if any
    GoVersion string       // go version used in module
    Error     *ModuleError // error loading module
}

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

如果模块位于模块高速缓存中或使用了-modfile标志,则GoMod引用的文件可能在模块目录之外。

默认输出是打印模块路径,然后打印有关版本和替换的信息(如果有)。例如,“ 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的查询指定该查询的结果,但不限于活动模块。有关模块查询的更多信息,请参见“进入帮助模块”。

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

有关构建标志的更多信息,请参见“ go help build”。

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

有关模块的更多信息,请参阅“进入帮助模块”。

模块维护

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

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

用法:

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 <命令>”可获取有关命令的更多信息。

将模块下载到本地缓存

用法:

go mod download [-x] [-json] [modules]

下载将下载已命名的模块,这些模块可以是选择主模块依赖性的模块模式,也可以是path @ version形式的模块查询。不带参数的下载适用于主模块的所有依赖项(等同于“ go mod download all”)。

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)
}

-x标志使下载打印输出下载执行的命令。

有关模块查询的更多信息,请参见“进入帮助模块”。

通过工具或脚本编辑go.mod

用法:

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

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

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

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

-module标志更改模块的路径(go.mod文件的模块行)。

-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是禁止操作。

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

-dropreplace = old [@v]标志删除给定模块路径和版本对的替换。如果省略@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”来进行更改。

打印模块需求图

用法:

go mod graph

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

在当前目录中初始化新模块

用法:

go mod init [module]

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

添加缺少的内容并删除未使用的模块

用法:

go mod tidy [-v]

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

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

制作依赖关系的供应商副本

用法:

go mod vendor [-v]

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

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

验证依赖项是否包含预期内容

用法:

go mod verify

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

说明为什么需要软件包或模块

用法:

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

为什么在导入图中显示从主模块到列出的每个软件包的最短路径。如果给出了-m标志,为什么将参数视为一个模块列表,并在每个模块中找到指向任何软件包的路径。

默认情况下,为什么要查询与“转到全部列出”匹配的软件包图,其中包括对可访问软件包的测试。-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)
$

编译并运行Go程序

用法:

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

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

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

'xprog a.out arguments...'.

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

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

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

另请参阅:进行构建。

测试包

用法:

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”,“ errorsas”,“ ifaceassert”,“ nilfunc”,“ printf”和“ stringintconv”。您可以通过“ 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设置如何,成功的软件包测试结果都将被缓存并重新使用。

除了构建标志之外,“ go test”本身处理的标志还有:

-args 
    将命令行的其余部分(-args之后的所有内容)
    传递给测试二进制文件,且未解释且保持不变。
    因为此标志占用了命令行的其余部分,
    所以程序包列表(如果存在)必须出现在此标志之前。

-c 
    将测试二进制文件编译为pkg.test,但不要运行它
    (其中pkg是软件包导入路径的最后一个元素)。
    可以使用-o标志更改文件名。

-exec xprog 
    使用xprog运行测试二进制文件。行为与
    “运行”中的行为相同。有关详细信息,请参见“运行帮助”。

-i 
    安装作为测试依赖项的软件包。
    不要运行测试。

-json
    将测试输出转换为适合自动处理的JSON。
    有关编码的详细信息,请参见“ go doc test2json”。

-o file
    将测试二进制文件编译为命名文件。
    测试仍然运行(除非指定了-c或-i)。

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

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

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

运行指定的go工具

用法:

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

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

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

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

打印版

用法:

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

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

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

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

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

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

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

报告包裹中可能的错误

用法:

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

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

有关vet及其标志的更多信息,请参见'go doc cmd / vet'。有关指定软件包的更多信息,请参见“转到帮助软件包”。有关检查程序及其标志的列表,请参见“ go tool vet help”。有关诸如“ printf”之类的特定检查器的详细信息,请参见“ 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

列出了在文件中应包含文件的条件。约束可能会出现在任何类型的源文件中(不仅是Go),但它们必须出现在文件顶部附近,并且只能出现空白行和其他行注释。这些规则意味着在Go文件中,构建约束必须出现在package子句之前。

为了将构建约束与软件包文档区分开来,必须在一系列构建约束后跟一个空行。

将构建约束评估为以空格分隔的选项的OR。每个选项的求值均以其逗号分隔的术语的AND表示。每个术语由字母,数字,下划线和点组成。术语可以与前面的!取反。例如,构建约束:

// +build linux,386 darwin,!cgo

对应于布尔公式:

(linux AND 386) OR (darwin AND (NOT cgo))

一个文件可能有多个构建约束。总体约束是各个约束的与。也就是说,构建约束:

// +build linux darwin
// +build amd64

对应于布尔公式:

(linux OR darwin) AND amd64

在特定的构建过程中,满足以下条件:

-由runtime.GOOS拼写的目标操作系统,使用
  GOOS环境变量设置。
-由runtime.GOARCH拼写的目标体系结构,使用
  GOARCH环境变量设置。
- 
如果使用了cgo命令,则使用的编译器为“ gc”或“ gccgo” -“ cgo”(请参阅
  “ go帮助环境”中的CGO_ENABLED )。
-每个Go主要版本的术语,从当前版本开始:
  从Go 1.1版开始的“ go1.1”,从Go 1.12起的“ go1.12”,依此类推。
--tags标志提供的任何其他标签(请参阅“ go help build”)。

Beta版或次要版本没有单独的构建标记。

如果在删除扩展名和可能的_test后缀后,文件名与以下任何一种模式匹配:

* _GOOS 
* _GOARCH 
* _GOOS_GOARCH

(示例:source_windows_amd64.go),其中GOOS和GOARCH分别表示任何已知的操作系统和体系结构值,然后该文件被视为具有需要这些术语的隐式构建约束(除了文件中的任何显式约束)。

使用GOOS = android除了匹配android标签和文件外,还像GOOS = linux一样匹配构建标签和文件。

除了illumos标签和文件外,使用GOOS = illumos还可以像GOOS = solaris一样匹配构建标签和文件。

要避免考虑将文件用于构建:

// +build ignore

(其他任何不满意的词也可以,但是“忽略”是常规的。)

要仅在使用cgo且仅在Linux和OS X上构建文件:

// +build linux,cgo darwin,cgo

这样的文件通常与另一个文件配对,该文件实现了其他系统的默认功能,在这种情况下,它将带有约束:

// +build !linux,!darwin !cgo

命名文件dns_windows.go将导致仅在构建Windows软件包时才包含该文件;同样,仅当为32位x86构建软件包时,才会包括math_386.s。

构建模式

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

-buildmode = archive 
	将列出的非主软件包构建到.a文件中。名为
	main的软件包将被忽略。

-buildmode = c-archive 
	将列出的主软件包及其导入的所有软件包生成
	到C存档文件中。唯一可调用的符号将是
	使用cgo // export注释导出的那些函数。仅需要
	列出一个主软件包。

-buildmode = c-shared 
	将列出的主软件包及其导入的所有软件包构建
	到C共享库中。唯一可调用的符号将
	是使用cgo // export注释导出的那些函数。
	仅需要列出一个主软件包。

-buildmode =默认
	列出的主软件包内置在可执行文件中,列出的
	非主软件包内置在.a文件中(默认
	行为)。

-buildmode = shared将
	所有列出的非主软件包组合到一个共享
	库中,使用-linkshared 
	选项进行构建时将使用该共享库。名为main的软件包将被忽略。

-buildmode = exe 
	构建列出的主软件包以及将其导入
	可执行文件的所有内容。未命名为main的软件包将被忽略。

-buildmode = pie 
	构建列出的主软件包及其所有导入到
	位置无关可执行文件(PIE)中的软件包。未命名为
	main的软件包将被忽略。

-buildmode = plugin
	将列出的主要软件包及其
	导入的所有软件包构建到Go插件中。未命名为main的软件包将被忽略。

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

在Go和C之间调用

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

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

第二个是SWIG程序,它是用于在语言之间进行接口的通用工具。有关SWIG的信息,请参见 http://swig.org/。运行go build时,任何扩展名为.swig的文件都将传递给SWIG。任何扩展名为.swigcxx的文件都将通过-c ++选项传递给SWIG。

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

构建和测试缓存

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命令打印有关是否重用缓存的测试结果的决策详细信息。

环境变量

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

通用环境变量:

GCCGO 
	为“ go build -compiler = gccgo”运行的gccgo命令。
GOARCH 
	为其编译代码的体系结构或处理器。
	例如amd64、386,arm,ppc64。
GOBIN'go 
	install'将在其中安装命令的目录。
GOCACHE 
	go命令将在其中存储缓存的
	信息以在以后的版本中重复使用的目录。
GOMODCACHE 
	go命令将在其中存储下载的模块的目录。
GODEBUG 
	启用各种调试工具。有关
	详细信息,请参见“ go doc运行时” 。
GOENV 
	Go环境配置文件的位置。
	无法使用'go env -w'进行设置。
高尔夫球
	当给定标志被
	当前命令已知时,默认情况下以
	空格分隔的-flag = value设置列表将应用于go命令。每个条目必须是一个独立的标志。
	因为条目是用空格分隔的,所以标志值
	不能包含空格。命令行
	上列出的标志在此列表之后应用,因此将其覆盖。
GOINSECURE 
	模块路径前缀的以
	逗号分隔的全局模式列表(按照Go的path.Match的语法),应始终以不安全的
	方式获取。仅适用于直接获取的依赖项。
	与'go get'上的-insecure标志不同,GOINSECURE不会禁用
	校验和数据库验证。可以使用GOPRIVATE或GONOSUMDB 
	来实现。
GOOS 
	为其编译代码的操作系统。
	例如linux,darwin,windows,netbsd。
GOPATH 
	有关更多详细信息,请参见:'go help gopath'。
	Go模块代理的
GOPROXY URL。请参阅“前往帮助模块”。
GOPRIVATE,GONOPROXY,GONOSUMDB 
	逗号分隔
	的模块路径前缀列表(以Go的path.Match语法),应始终直接获取
	或不应与校验和数据库进行比较。
	请参阅“转到帮助模块-私有”。
GOROOT 
	go树的根。
GOSUMDB
	要使用的校验和数据库的名称,以及可选的公钥和
	URL。请参阅“转到帮助模块-身份验证”。
GOTMPDIR 
	go命令将在其中写入
	临时源文件,程序包和二进制文件的目录。

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

AR 
	与gccgo编译器一起构建
	时用于处理库归档的命令。
	默认值为“ ar”。
CC 
	用于编译C代码的命令。
CGO_ENABLED 
	是否支持cgo命令。0或
1。CGO_CFLAGS 
	编译
	C代码时cgo的标志将传递给编译器。
CGO_CFLAGS_ALLOW 
	一个正则表达式,指定其他标志以允许
	出现在#cgo CFLAGS源代码指令中。
	不适用于CGO_CFLAGS环境变量。
CGO_CFLAGS_DISALLOW 
	一个正则表达式,指定必须禁止
	在#cgo CFLAGS源代码指令中出现的标志。
	不适用于CGO_CFLAGS环境变量。
CGO_CPPFLAGS,CGO_CPPFLAGS_ALLOW,CGO_CPPFLAGS_DISALLOW 
	类似于CGO_CFLAGS,CGO_CFLAGS_ALLOW和CGO_CFLAGS_DISALLOW,
	但用于C预处理器。
CGO_CXXFLAGS,CGO_CXXFLAGS_ALLOW,CGO_CXXFLAGS_DISALLOW 
	像CGO_CFLAGS,CGO_CFLAGS_ALLOW和CGO_CFLAGS_DISALLOW一样,
	但适用于C ++编译器。
CGO_FFLAGS,CGO_FFLAGS_ALLOW,CGO_FFLAGS_DISALLOW 
	与CGO_CFLAGS,CGO_CFLAGS_ALLOW和CGO_CFLAGS_DISALLOW类似,
	但适用于Fortran编译器。
CGO_LDFLAGS,CGO_LDFLAGS_ALLOW,CGO_LDFLAGS_DISALLOW 
	类似于CGO_CFLAGS,CGO_CFLAGS_ALLOW和CGO_CFLAGS_DISALLOW,
	但用于链接器。
CXX
	用于编译C ++代码的命令。
FC 
	用于编译Fortran代码的命令。
PKG_CONFIG 
	pkg-config工具的路径。

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

GOARM 
	对于GOARCH = arm,要为其编译的ARM体系结构。
	有效值为
5、6、7。GO386 
	对于GOARCH = 386,是浮点指令集。
	有效值为387,sse2。
GOMIPS 
	对于GOARCH = mips {,le},是否使用浮点指令。
	有效值是hardfloat(默认值),softfloat。
GOMIPS64 
	对于GOARCH = mips64 {,le},是否使用浮点指令。
	有效值是hardfloat(默认值),softfloat。
GOWASM 
	对于GOARCH = wasm,使用逗号分隔的实验性WebAssembly功能列表。
	有效值为satconv,signext。

专用环境变量:

GCCGOTOOLDIR 
	如果设置,在哪里可以找到gccgo工具,例如cgo。
	默认值基于gccgo的配置方式。
GOROOT_FINAL 
	当已安装的Go树
	安装在其生成位置以外的位置时,它的根。
	堆栈跟踪中的文件名从GOROOT重写为
	GOROOT_FINAL。
GO_EXTLINK_ENABLED 
	当-linkmode = auto和使用cgo的代码一起使用时
	,链接器是否应使用外部链接模式。
	设置为0禁用外部链接模式,设置为1启用外部链接模式。
GIT_ALLOW_PROTOCOL 
	由Git定义。用冒号分隔的方案列表,
	可与git fetch / clone一起使用。如果设置,则任何未明确指定的方案
	提到的内容会被“获取”视为不安全。
	由于变量是由Git定义的,因此无法
	使用'go env -w'设置默认值。

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

GOEXE 
	可执行文件名后缀(在Windows上为“ .exe”,在其他系统上为“”)。
GOGCCFLAGS 
	提供给CC命令的参数的空格分隔列表。
GOHOSTARCH 
	Go工具链二进制文件的体系结构(GOARCH)。
GOHOSTOS 
	Go工具链二进制文件的操作系统(GOOS)。
GOMOD 
	主模块go.mod 的绝对路径。
	如果启用了模块感知模式,但没有go.mod,则GOMOD将为
	os.DevNull(在类Unix系统上为“ / dev / null”,在Windows上为“ NUL”)。
	如果禁用了模块感知模式,则GOMOD将为空字符串。
GOTOOLDIR 
	安装go工具(编译,覆盖,doc等)的目录。

文件类型

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

.go 
	Go源文件。
.c,.h 
	C源文件。
	如果软件包使用cgo或SWIG,则将使用
	OS本地编译器(通常为gcc)进行编译;否则会
	触发错误。
.cc,.cpp,.cxx,.hh,.hpp,.hxx 
	C ++源文件。仅对cgo或SWIG有用,并且始终
	使用OS本地编译器进行编译。
.m 
	Objective-C源文件。仅对cgo有用,并且始终
	使用OS本地编译器进行编译。
.s,.S,.sx 
	汇编程序源文件。
	如果软件包使用cgo或SWIG,则将使用
	OS本地汇编程序(通常为gcc(sic))进行汇编;否则
	将使用Go汇编器进行汇编。
.swig,.swigcxx 
	SWIG定义文件。
.syso 
	系统对象文件。

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

go.mod文件

模块版本由源文件树定义,其根目录中带有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

此更新将非规范版本标识符重写为semver格式,因此A的v1变为v1.0.0,E的dev成为dev分支上最新提交的伪版本,也许是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环境变量

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代码)
                x.go 
            quux /(程序包main中的代码)
                y.go 
    bin / 
        quux(已安装命令)
    pkg / 
        linux_amd64 / 
            foo / 
                bar.a(已安装的软件包对象)

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

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

GOPATH和模块

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

内部目录

只有以“内部”父级为根的目录树中的代码才能导入名为“内部”的目录中或下方的代码。这是上面目录布局的扩展版本:

/ home / user / go / 
    src / 
        crash / 
            bang /(bang软件包中的代码)
                b.go 
        foo /(foo软件包中的代码)
            f.go 
            bar /(bar软件包中的代码)
                x.go 
            internal / 
                baz /(打包baz中的代码)
                    z.go 
            quux /(打包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不能。

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

供应商目录

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

目录“ vendor”下的代码只能通过以“ vendor”的父级为根的目录树中的代码导入,并且只能使用忽略前缀(直到并包括vendor元素)的导入路径。

这是上一部分的示例,但是将“内部”目录重命名为“供应商”,并添加了新的foo / vendor / crash / bang目录:

/ home / user / go / 
    src / 
        crash / 
            bang /(bang软件包中的代码)
                b.go 
        foo /(foo软件包中的代码)
            f.go 
            bar /(软件包bar的代码)
                x.go 
            vendor / 
                crash / 
                    bang /(打包bang中的代码)
                        b.go 
                baz /(打包baz中的代码)
                    z.go 
            quux /(打包main中的代码)
                y.go

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

供应商目录中的代码位于源目录树的更深层,而较高目录中的代码则处于阴影中。在以foo为根的子树中,“ crash / bang”的导入解析为“ foo / vendor / crash / bang”,而不是顶级的“ crash / bang”。

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

现在,当“ go get”签出或更新git存储库时,它现在还将更新子模块。

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

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

旧版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还接受构建标志来控制安装。请参阅“建立帮助”。

签出新软件包时,get将创建目标目录GOPATH / src / <import-path>。如果GOPATH包含多个条目,则get使用第一个条目。有关更多详细信息,请参见:'go help gopath'。

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

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

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

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

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

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

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

模块代理协议

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

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

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

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

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

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

GET $ GOPROXY / <module> / @ latest以与<模块> / @ v / <版本> .info相同的格式返回有关给定模块的最新已知版本的JSON格式的元数据。如果<module> / @ v / list为空或没有合适的列出版本,则最新版本应为go命令可以使用的模块版本。<module> / @ latest是可选的,不能由模块代理实现。

解析模块的最新版本时,go命令将请求<module> / @ v / list,然后,如果找不到合适的版本,则请求<module> / @ latest。go命令按顺序优先使用:语义上最高的发行版,语义上最高的预发行版以及按时间顺序排列的最新伪版本。在Go 1.12和更早的版本中,go命令将<module> / @ v / list中的伪版本视为预发行版本,但是从Go 1.13开始不再适用。

为了避免从区分大小写的文件系统提供服务时出现问题,<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

导入路径语法

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

相对导入路径

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

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

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

远程导入路径

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

一些常见的代码托管站点具有特殊的语法:

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", "fossil", "git", "hg", "svn".之一。

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

例如,

import "example.org/pkg/foo"

将导致以下请求:

https://example.org/pkg/foo?go-get=1(首选)
 http://example.org/pkg/foo?go-get=1   (备用,仅适用于-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”作为内容值中的vcs,如下所示:

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

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

导入路径检查

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

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

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

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

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

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

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

模块,模块版本等

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

模块支持

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

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

为了获得更细粒度的控制,go命令将继续使用临时环境变量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)。

定义模块

模块由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”)将根据需要自动添加新的依赖关系,以实现导入。

主模块和构建清单

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

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

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

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

go list -m    #主模块的打印路径
go list -m -f = {{.Dir}}    #打印主模块的根目录
go list -m all    #打印构建列表

维护模块要求 

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命令将从主模块的供应商目录中加载软件包,而不是将模块下载到模块高速缓存中并从模块高速缓存中加载软件包。go命令假定供应商目录包含正确的依赖关系副本,并且不会从go.mod文件中计算所需的模块版本集。但是,go命令会检查vendor / modules.txt(由“ go mod vendor”生成)是否包含与go.mod一致的元数据。

如果使用-mod = mod调用,则go命令将从模块缓存中加载模块,即使存在供应商目录也是如此。

如果没有使用-mod标志调用go命令,并且存在供应商目录,并且go.mod中的“ go”版本为1.14或更高版本,则go命令的行为就像是通过-mod = vendor调用一样。

伪版本

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命令将接受纯提交哈希并将其自动转换为伪版本(或标记版本)(如果可用)。此转换是模块查询的示例。

模块查询

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  #相同(@latest是'go get'的默认值)
go get github.com/gorilla/mux@v1.6.2  #记录v1.6.2 
go get github.com/gorilla/ mux @ e3702bed2 #记录v1.6.2 
go get github.com/gorilla/mux@c856192  #记录v0.0.0-20180517173623-c85619274f5d 
go get github.com/gorilla/mux@master  #记录master的当前含义

模块兼容性和语义版本控制

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/更多关于语义版本。

模块代码布局

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

模块下载与验证 

go命令可以根据GOPROXY环境变量的设置从代理获取模块或直接连接到源控制服务器(请参阅“ go help env”)。GOPROXY的默认设置为“ https://proxy.golang.org,direct ”,这意味着尝试由Google运行的Go模块镜像,如果代理报告它没有模块,则退回到直接连接( HTTP错误404或410)。有关服务的隐私权政策,请参阅https://proxy.golang.org/privacy

如果GOPROXY设置为字符串“ direct”,则下载将使用直接连接到源代码控制服务器。将GOPROXY设置为“关闭”将禁止从任何来源下载模块。否则,GOPROXY应该是模块代理URL的列表,这些URL用逗号(,)或管道(|)字符分隔,以控制错误的后备行为。对于每个请求,go命令都会依次尝试每个代理。如果有错误,如果错误是404或410 HTTP响应,或者如果当前代理后面带有管道字符,则go命令将尝试列表中的下一个代理,这表示可以安全地返回任何错误。

GOPRIVATE和GONOPROXY环境变量允许绕过所选模块的代理。有关详情,请参见“转到帮助模块-私有”。

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

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

模块和供应商

当使用模块时,go命令通常通过从模块的源中下载模块并使用那些下载的副本来满足依赖关系(在验证之后,如上一节所述)。供应商可以用于与Go的较早版本进行互操作,或者用于确保用于构建的所有文件一起存储在单个文件树中。

命令“ go mod vendor”在主模块的根目录中构造一个名为vendor的目录,其中包含支持主模块中软件包的构建和测试所需的所有软件包的副本。“ go mod vendor”还创建了文件vendor / modules.txt,其中包含有关供应商软件包和模块版本的元数据。该文件应与go.mod保持一致:使用供应商时,应在go.mod更新后运行“ go mod供应商”。

如果供应商目录位于主模块的根目录中,并且主模块的go.mod文件中的“ go”版本为1.14或更高版本,则会自动使用该目录。诸如“ go build”和“ go test”之类的构建命令将从供应商目录加载软件包,而不是访问网络或本地模块缓存。要显式启用供应商,请使用标志-mod = vendor调用go命令。要禁用供应,请使用标志-mod = mod。

与GOPATH中的供应商不同,go命令会忽略除主模块根目录之外的其他位置的供应商目录。

使用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。

模块认证失败

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命令调用设置这些变量。

非公共模块的模块配置

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

GOPRIVATE环境变量控制go命令认为哪个模块是私有的(不可公开获得),因此不应使用代理或校验和数据库。该变量是模块路径前缀的逗号分隔的glob模式列表(按照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环境变量接受相同类型的全局列表,并分别覆盖GOPRIVATE来分别决定是否使用代理数据库和校验和数据库。

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

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

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

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

包裹清单和样式

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

go action [packages]

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

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

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

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

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

-“ main”表示独立可执行文件中的顶级程序包。

-“ all”扩展到所有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。

An import path can also name a package to be downloaded from a remote repository. Run 'go help importpath' for details.

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'.

Packages in a program need not have unique package names, but there are two reserved package names with special meaning. The name main indicates a command, not a library. Commands are built into binaries and cannot be imported. The name documentation indicates documentation for a non-Go program in the directory. Files in package documentation are ignored by the go command.

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

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

测试标志

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

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

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

-bench regexp 
    仅运行与正则表达式匹配的那些基准。
    默认情况下,不运行任何基准测试。
    要运行所有基准,请使用“ -bench”。或“ -bench =”。
    正则表达式由无括号的斜杠(/)
    字符拆分为一系列正则表达式,并且
    基准标识符的每个部分都必须与
    序列中的相应元素(如果有)匹配。可能的匹配父项
    以bN = 1进行运行以标识子基准。例如,在
    给定-bench = X / Y的情况下,
    以bN = 1 运行与X匹配的顶级基准,以找到与Y匹配的所有子基准,
    然后将其完整运行。

-benchtime t
    对每个基准运行足够的迭代,以t表示
    为time.Duration(例如-benchtime 1h30s)。
    默认值为1秒(1s)。
    特殊语法Nx意味着要运行基准测试N次
    (例如,-benchtime 100x)。

-count n 
    运行每个测试和基准测试n次(默认为1)。
    如果设置了-cpu,则对每个GOMAXPROCS值运行n次。
    示例始终运行一次。

-cover 
    启用覆盖率分析。
    请注意,由于覆盖率是通过
    在编译之前对源代码进行注释而起作用的,因此
    启用覆盖率的编译和测试失败可能会报告行号不一致
    原始来源。

-covermode set,count,atomic 
    设置
    要测试的软件包的覆盖率分析的模式。除非启用了-race,否则缺省值为“ set”,
    在这种情况下,它为“ atomic”。
    值:
	set:bool:该语句是否运行?
	count:int:该语句运行多少次?
	atomic:int:计数,但在多线程测试中正确;
		贵得多。
    设置-cover。

-coverpkg pattern1,pattern2,pattern3 
    在每个测试中将覆盖率分析应用于与模式匹配的程序包。
    默认设置是每个测试仅分析要测试的程序包。
    有关程序包模式的说明,请参见“转到帮助程序包”。
    设置-cover。

-cpu 1,2,4 
    指定
    应为其执行测试或基准的GOMAXPROCS值的列表。默认值为
    GOMAXPROCS 的当前值。

-failfast 
    第一次测试失败后,请勿开始新的测试。

-list regexp 
    列出与正则表达式匹配的测试,基准或示例。
    不会运行任何测试,基准测试或示例。这只会
    列出顶级测试。没有子测试或子基准。

-parallel n 
    允许并行执行调用t.Parallel的测试函数。
    该标志的值是可以
    同时运行的最大测试数;默认情况下,它设置为GOMAXPROCS的值。
    请注意,-parallel仅适用于单个测试二进制文件。
    根据-p标志的设置,
    “ go test”命令也可以针对不同的程序包并行运行测试
    (请参阅“ go help build”)。

-run regexp 
    仅运行与正则表达式匹配的那些测试和示例。
    对于测试,正则表达式由无括号的斜杠(/)
    字符拆分为一系列正则表达式,并且
    测试标识符的每个部分都必须与中的相应元素匹配
    顺序(如果有)。请注意,也可能
    运行匹配项的父项,因此-run = X / Y匹配并运行并报告
    所有与X匹配的测试的结果,即使那些没有与Y匹配的子测试的结果也是如此,
    因为它必须运行它们以查找那些子测试-测试。

-short 
    告诉长时间运行的测试以缩短其运行时间。
    它默认情况下是关闭的,但是在all.bash期间设置,以便安装
    Go树可以运行健全性检查,而不花费时间运行
    详尽的测试。

-timed d 
    如果测试二进制文件的运行时间超过持续时间d,则出现恐慌。
    如果d为0,则禁用超时。
    默认值为10分钟(10m)。

-v
    详细的输出:在运行所有测试时记录它们。
    即使测试成功,也要打印Log和Logf调用中的所有文本。

-vet list
    将“ go test”期间的“ go vet”调用配置
    为使用逗号分隔的vet检查列表。
    如果列表为空,则“ go test”将运行“ go vet”,并带有经过整理的
    被认为总是值得解决的支票清单。
    如果列表为“ off”,则“ go test”根本不会运行“ go vet”。

以下标记也可以被“执行测试”识别,并可以在执行期间用于分析测试:

-benchmem 
    打印基准的内存分配统计信息。

-blockprofile block.out 
    所有测试完成后
    ,将goroutine阻止配置文件写入指定的文件。
    像-c那样编写测试二进制文件。

-blockprofilerate n 
    通过
    使用n调用runtime.SetBlockProfileRate来控制goroutine阻止配置文件中提供的详细信息。
    请参阅“转到doc runtime.SetBlockProfileRate”。
    探查器的目的是平均
    在程序花费的每n纳秒中采样一次阻塞事件。默认情况下,
    如果设置了-test.blockprofile而没有此标志,
    则将记录所有阻止事件,等效于-test.blockprofilerate = 1。

-coverprofile cover.out 
    在所有测试通过之后,将coverage配置文件写入文件。
    设置-cover。

-cpuprofile cpu.out 
    退出之前,将CPU配置文件写入指定的文件。
    像-c那样编写测试二进制文件。

-memprofile mem.out 
    所有测试通过后,将分配配置文件写入文件。
    像-c那样编写测试二进制文件。

-memprofilerate n 
    通过
    设置runtime.MemProfileRate 启用更精确(且昂贵)的内存分配配置文件。请参阅“转到doc runtime.MemProfileRate”。
    要分析所有内存分配,请使用-test.memprofilerate = 1。

-mutexprofile Mutex.out
    所有测试完成后
    ,将互斥锁争用概要文件写入指定的文件。
    像-c那样编写测试二进制文件。

-mutexprofilefraction n 
    持有
    竞争互斥量的goroutine的n个堆栈跟踪中的样本1 。

-outputdir directory
    将概要分析的输出文件放在指定目录中,
    默认情况下是运行“ go test”的目录。

-trace trace.out 
    退出之前,将执行跟踪写入到指定文件。

这些标志中的每一个也可以通过可选的“测试”来识别。前缀,如-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命令的执行,不适用于测试本身。)

生成配置文件的测试标志(除了覆盖率以外)还将测试二进制文件保留在pkg.test中,以供在分析配置文件时使用。

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

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

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

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

例如,命令

go test -v -args -x -v

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

pkg.test -test.v -x -v

同样,

go test -args math

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

pkg.test math

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

测试功能

“ 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
}

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

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

  • 0
    点赞
  • 0
    评论
  • 2
    收藏
  • 一键三连
    一键三连
  • 扫一扫,分享海报

©️2021 CSDN 皮肤主题: 1024 设计师:白松林 返回首页
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值