【翻译】Command Go 上

原文链接 https://golang.org/cmd/go/
由于内容过长，分两次发布

Go 是一个用来管理Go源码的工具。
用法：

go [arguments]

其中command包含以下

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         download and install packages and dependencies
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
packages    package lists and patterns
testflag    testing flags
testfunc    testing functions

使用"go help "查看相关主题的更多帮助信息。

Start a bug report

用法

go bug

Bug打开默认浏览器启动新的错误报告，该报告包含有用的系统信息。（译注：不知有何用）

Compile packages and dependencies

用法：

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

Build 会编译以导入路径命名的包及其依赖项，但是不会安装结果。
如果构建的参数是.go文件列表，则build会将它们视为指定单个包的源文件列表。

编译单个主程序main包时，build生成的可执行文件将以第一个源文件命名（“go build ed.go rx.go”生成"ed"或"ed.exe"）或以源代码目录命名 ("go build unix/sam"生成"sam" or "sam.exe")其中".exe"后缀是window可执行文件后缀。

当编译多个包或单个非main包时，build编译包但丢弃生成的对象，仅用于检查是否可以构建包。

当编译包时，构建会忽略以"_test.go"结尾的文件。

-o 标记仅在编译单个包时生效，强制build将生成的可执行文件或对象写入以“output”命名的文件，而不是上面两端描述的默认行为。

-i 标记安装作为膜表依赖性的包。

build flags的可选内容与 build, clean, get, install, list, run, test 命令共享

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

-asmflags，-gccgoflags，-gcflags和-ldflags标志接受以空格分隔的参数列表，以在构建期间传递给基础工具。要在列表中的元素中嵌入空格，请使用单引号或双引号将其括起来。参数列表可以在包模式和等号之后，这限制了该参数列表只构建匹配该模式的包（有关包模式的描述，请参阅'go help packages'）。如果没有模式，参数列表仅适用于命令行上指定的包。可以用不同的模式重复标志，以便为不同的包组指定不同的参数。如果包与多个标志中给出的模式匹配，则命令行上将以命令行最后一个匹配的标记为准。例如，'go build -gcflags=-S fmt' 只输出fmt包的拆解，'go build -gcflags=all=-S fmt'输出fmt的拆解，以及它的依赖。

有关指定包的更多信息，请参阅“go help packages”。有关安装包和二进制文件的更多信息，请运行'go help gopath'。有关在Go和C / C ++之间调用的更多信息，请运行'go help c'。

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

Remove object files and cached files（移除对象和缓存文件）

使用

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

Clean命令从包源码路径删除对象文件。go命令在临时构建许多临时对象，所以go clean主要关注其它工具或手动调用go build遗留的对象文件。

具体来说，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构建缓存的测试结果失效

-modcache 标记引导clean移除所有下载模块的缓存，包括不同版本依赖的解压源代码

有关构建标志的更多信息，请参阅“go help build”。
有关指定包的更多信息，请参阅“go help packages”。

Show documentation for package or symbol

用法：

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

【省略...】

Print Go environment information

用法：

go env [-json] [var ..]

Env输出Go环境信息。

默认情况下env以shell脚本格式输出信息（window是批处理文件batch file）。如果给出一个或多个的变量名作为参数，则env为每个变量名输出一行值信息。

-json 标记以json格式输出

有关环境变量的更多信息，请参阅“go help environment”。

Update packages to use new APIs

用法：

go fix [packages]

Fix在导入路径命名的包上运行Go fix命令。
有关修复的更多信息，请参阅“go doc cmd / fix”。
有关指定包的更多信息，请参阅“go help packages”。
要使用特定选项运行修复，请运行“go tool fix”。另见：go fmt，go vet。

Gofmt (reformat) package sources（源码格式化）

用法：

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

fmt 在以导入路径命名的包上运行命令"gofmt -l -w"。它输出那些被修改的文件名。

有关gofmt的更多信息，请参阅“go doc cmd / gofmt”。
有关指定包的更多信息，请参阅“go help packages”。
-n标志打印将要执行的命令。-x标志在执行时打印命令。
要使用特定选项运行gofmt，请运行gofmt本身。
另见：go fix，go vet。

Generate Go files by processing source

用法：

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

generate 运行现有文件中的注释描述。那些注释可以执行任何程序，不过一般意图是创建或更新go源码文件。

go generate 不会被go build, go get, go test等命令触发，它需要明确的指定运行。

go generate 扫描文件中的指令，指令格式如下：

//go:generate command argument...

（注：没有前置空格，"//go"中也没有空格）generate执行指令的地方，对应一个可本地执行的可执行文件。它必须位于shell路径（gofmt），完整的路径或是命令别名，如下所述：

为了向人类与工具传达代码是生成的，生成的源应该具有与以下正则表达式匹配的行（在Go语法中）：

// Code generated .* DO NOT EDIT.$

该行可能出现在文件中任意地方，但通常位于开头附近，因此很容易找到。

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

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

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

Go运行生成器时生成几个变量：

$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”的特殊处理。

作为运行命令之前的最后一步，任何具有字母数字名称的环境变量（例如 HOME）的调用都将在整个命令行中进行扩展。变量扩展的语法是所有操作系统上的 NAME将扩展为空字符串。

指令格式如下

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

仅在此源文件剩余的部分，指定字符串xxx表示有args标识的命令。这可以用于创建别名或者处理多字生成器。例如：

//go:generate -command foo go tool foo

指定命令“foo”表示生成器“go tool foo”

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”。
有关指定包的更多信息，请参阅“go help packages”。

Download and install packages and dependencies（下载安装包依赖）

用法：

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

get下载导入路径指定的包及其依赖项。然后像“goinstall”那样安装下载的包。

-d 标记指示在下载软件包后停止; 也就是说，它指示不安装软件包。
-f 标记仅在设置-u时有效，强制get -u不验证每个包是否已从其导入路径隐含的源代码仓储中检出。如果源是original的本地分支，这可能很有用。
-fix 标记指示get在解析依赖项或构建代码之前在下载的包上运行修复工具。
-insecure 标志允许从存储库中提取并使用不安全的方案（如HTTP）解析自定义域。谨慎使用。
-t 标记指示get还下载构建指定包的测试所需的包。
-u 标记指示get使用网络更新命名包及其依赖项。默认情况下，get使用网络检出缺少的包，但不使用它来查找现有包的更新。
-v 标记启用详细进度和调试输出。
Get还接受构建标志来控制安装。请参阅'go help build'。
签出新包时，get创建目标目录GOPATH / src / 。如果GOPATH包含多个条目，则get使用第一个条目。有关详细信息，请参阅：'go help gopath'。
签出或更新包时，查找与本地安装的Go版本匹配的分支或标记。最重要的规则是，如果本地安装运行版本为“go1”，则搜索名为“go1”的分支或标记。如果不存在此类版本，则会检索包的默认分支。
当获取签出或更新Git存储库时，它还会更新存储库引用的任何git子模块。

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

有关指定包的更多信息，请参阅“go help packages”。
有关“go get”如何找到要下载的源代码的更多信息，请参阅“go help importpath”。
本文描述了使用GOPATH管理源代码和依赖项时get的行为。如果go命令在模块感知模式下运行，则get的标志和效果的细节会发生变化，就像'go help get'一样。请参阅“go help modules”和“go help module-get”。另见：go build，go install，go clean。

Compile and install packages and dependencies（编译安装包及其依赖）

用法：

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

install 编译安装导入路径命名的包。
-i 标记安装命名包的依赖项。

有关构建标志的更多信息，请参阅“go help build”。
有关指定包的更多信息，请参阅“go help packages”。
另见：go build，go get，go clean。

List packages or modules

用法：

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

list命令列出命名的包，每个包一行，最常使用的标记是 -f 和 -json，这两个标记用来控制输出的包的格式。其他list的标记，控制更具体的细节。

默认输出显示包的导入路径：

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

-f 标记使用包模板语法指定列表的格式，默认输出格式相当于 -f'{.ImportPath}'。模板结构体如下：

// A Package describes a single package found in a directory.
type Package struct {
    PackagePublic                 // visible in 'go list'
    Internal      PackageInternal // for use inside go command only
}

type PackagePublic struct {
    // Note: These fields are part of the go command's public API.
    // See list.go. It is okay to add fields, but not to change or
    // remove existing ones. Keep in sync with list.go
    Dir           string                `json:",omitempty"` // directory containing package sources
    ImportPath    string                `json:",omitempty"` // import path of package in dir
    ImportComment string                `json:",omitempty"` // path in import comment on package statement
    Name          string                `json:",omitempty"` // package name
    Doc           string                `json:",omitempty"` // package documentation string
    Target        string                `json:",omitempty"` // installed target for this package (may be executable)
    Shlib         string                `json:",omitempty"` // the shared library that contains this package (only set when -linkshared)
    Root          string                `json:",omitempty"` // Go root or Go path dir containing this package
    ConflictDir   string                `json:",omitempty"` // Dir is hidden by this other directory
    ForTest       string                `json:",omitempty"` // package is only for use in named test
    Export        string                `json:",omitempty"` // file containing export data (set by go list -export)
    Module        *modinfo.ModulePublic `json:",omitempty"` // info about package's module, if any
    Match         []string              `json:",omitempty"` // command-line patterns matching this package
    Goroot        bool                  `json:",omitempty"` // is this package found in the Go root?
    Standard      bool                  `json:",omitempty"` // is this package part of the standard Go library?
    DepOnly       bool                  `json:",omitempty"` // package is only as a dependency, not explicitly listed
    BinaryOnly    bool                  `json:",omitempty"` // package cannot be recompiled
    Incomplete    bool                  `json:",omitempty"` // was there an error loading this package or dependencies?

    // Stale and StaleReason remain here *only* for the list command.
    // They are only initialized in preparation for list execution.
    // The regular build determines staleness on the fly during action execution.
    Stale       bool   `json:",omitempty"` // would 'go install' do anything for this package?
    StaleReason string `json:",omitempty"` // why is Stale true?

    // Source files
    // If you add to this list you MUST add to p.AllFiles (below) too.
    // Otherwise file name security lists will not apply to any new additions.
    GoFiles         []string `json:",omitempty"` // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
    CgoFiles        []string `json:",omitempty"` // .go source files that import "C"
    CompiledGoFiles []string `json:",omitempty"` // .go output from running cgo on CgoFiles
    IgnoredGoFiles  []string `json:",omitempty"` // .go source files ignored due to build constraints
    CFiles          []string `json:",omitempty"` // .c source files
    CXXFiles        []string `json:",omitempty"` // .cc, .cpp and .cxx source files
    MFiles          []string `json:",omitempty"` // .m source files
    HFiles          []string `json:",omitempty"` // .h, .hh, .hpp and .hxx source files
    FFiles          []string `json:",omitempty"` // .f, .F, .for and .f90 Fortran source files
    SFiles          []string `json:",omitempty"` // .s source files
    SwigFiles       []string `json:",omitempty"` // .swig files
    SwigCXXFiles    []string `json:",omitempty"` // .swigcxx files
    SysoFiles       []string `json:",omitempty"` // .syso system object files added to package

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

    // Dependency information
    Imports   []string          `json:",omitempty"` // import paths used by this package
    ImportMap map[string]string `json:",omitempty"` // map from source import to ImportPath (identity entries omitted)
    Deps      []string          `json:",omitempty"` // all (recursively) imported dependencies

    // Error information
    // Incomplete is above, packed into the other bools
    Error      *PackageError   `json:",omitempty"` // error loading this package (not dependencies)
    DepsErrors []*PackageError `json:",omitempty"` // errors loading dependencies

    // Test information
    // If you add to this list you MUST add to p.AllFiles (below) too.
    // Otherwise file name security lists will not apply to any new additions.
    TestGoFiles  []string `json:",omitempty"` // _test.go files in package
    TestImports  []string `json:",omitempty"` // imports from TestGoFiles
    XTestGoFiles []string `json:",omitempty"` // _test.go files outside package
    XTestImports []string `json:",omitempty"` // imports from XTestGoFiles
}

存在 vendor 目录下的包得到的 ImportPath 包含 vendor 路径（例如： "d/vendor/p" 而不仅仅是“p”）,所以ImportPath 可以唯一标记一个给定包的副本。Imports, Deps, TestImports, 与 XTestImports 列表也包含了扩展导入路径。查阅 golang.org/s/go15vendor 了解更多细节。

错误信息结构如下：

// A PackageError describes an error loading information about a package.
type PackageError struct {
    ImportStack   []string // shortest path from package named on command line to this one
    Pos           string   // position of error
    Err           string   // the error itself
    IsImportCycle bool     `json:"-"` // the error is an import cycle
    Hard          bool     `json:"-"` // whether the error is soft or hard; soft errors are ignored in some places
}

模块信息是一个 Module 结构体，如下文 list -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
}

更多关于 Context 结构体字段的信息，查看go/build 包的 Context 类型文档。

-json 标记指示包数据使用 JSON格式输出，而不是模板类型。

-compiled 标记指示list 将 CompiledGoFiles 设置为呈现给编译器的Go源文件。通常这意味着它会重复GoFiles中列出的文件，然后还会添加通过CgoFiles 和 SwigFiles 生成的Go代码。Import列表包含来自GoFiles与CompiledGoFiles的所有导入合集。

-deps 标记指示list不仅是迭代命名的包，还迭代所有它们的依赖。list以深度优先顺序遍历它们，所以包会在其所有依赖之后列出。未在命令行明确列出的包将DepOnly字段设置为true

-e 标记改变错误包的处理方式，错误包指那些找不到或错误的包。默认情况下，list命令为每个错误的包打印一个标准错误，并通常在打印过程中忽略它们。使用-e标记，list命令将不会打印错误信息，而是像正常情况打印那些错误的包。错误的包邮非空的ImportPath和 non-nil的 Error 字段；其它信息可能会是丢失（零值）

-export 标记使list 将 Export 字段设置为包含给定包的最新到处信息的文件的名称。

-find 标记指示list标识命名的包，但是不解析他们的依赖关系，Imports 与 Deps列表将为空。

-test 标记指示list不止报告命名包而且报告测试二进制文件（对于带有测试的包），以准确地向源代码分析工具传达测试二进制文件的构造方式。报告的二进制测试文件导入路径是包的导入路径后面加“.test”后缀，如“math/rand.test”。在构建测试时，有事需要专门为测试重建某些依赖项（最常见的是测试包本身）。报告的针对特定的测试二进制文件重新编译的包的导入路径后跟一个空格和中括号内的二进制文件名称，如“math/rand [math/rand.test]”或者"regexp [sort.test]"。ForTest 字段也设置正在测试的包的名称（“math/rand”或 "sort"）

Dir, Target, Shlib, Root, ConflictDir, and Export 字段中包含的路径都是绝对路径.

默认情况下，GoFiles，CgoFiles等列表保持Dir中的文件名（即相对于Dir的路径，而不是绝对路径）。使用-compiled和-test 标记时添加的生成文件是引用生成的Go源文件的副本的绝对路径。虽然它们是Go源文件，但路径可能不是以“.go”结尾。

-m 标记指示list列出模块而不是包

当-m指定列出模块时，使用 -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
    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 [v0.4.0] => /tmp/text
rsc.io/pdf v0.1.1 [v0.1.2]

Module 结构体有一个String方法，用于格式化这一行输出，所以默认格式等同于 -f'{{.String}}'

Note that when a module has been replaced, its Replace field describes the replacement module, and its Dir field is set to the replacement's source code, if present. (That is, if Replace is non-nil, then Dir is set to Replace.Dir, with no access to the replaced source code.)

The -u flag adds information about available upgrades. When the latest version of a given module is newer than the current one, list -u sets the Module's Update field to information about the newer module. The Module's String method indicates an available upgrade by formatting the newer version in brackets after the current version. For example, 'go list -m -u all' might print:my/main/module
golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
rsc.io/pdf v0.1.1 [v0.1.2]
(For tools, 'go list -m -u -json all' may be more convenient to parse.)The -versions flag causes list to set the Module's Versions field to a list of all known versions of that module, ordered according to semantic versioning, earliest to latest. The flag also changes the default output format to display the module path followed by the space-separated version list.The arguments to list -m are interpreted as a list of modules, not packages. The main module is the module containing the current directory. The active modules are the main module and its dependencies. With no arguments, list -m shows the main module. With arguments, list -m shows the modules specified by the arguments. Any of the active modules can be specified by its module path. The special pattern "all" specifies all the active modules, first the main module and then dependencies sorted by module path. A pattern containing "..." specifies the active modules whose module paths match the pattern. A query of the form path@version specifies the result of that query, which is not limited to active modules. See 'go help modules' for more about module queries.The template function "module" takes a single string argument that must be a module path or query and returns the specified module as a Module struct. If an error occurs, the result will be a Module struct with a non-nil Error field.For more about build flags, see 'go help build'.For more about specifying packages, see 'go help packages'.For more about modules, see 'go help modules'.

Module maintenance（模块维护）

Go mod 提供对模块的操作

注意，所有的go命令都内置了对模块的支持，而不仅仅是“go mod”。例如日常应该使用“go get”对依赖项做添加，移除，升级和降级操作。有关模块功能的概述，请参阅“go help modules”。

用法：

go mod [arguments]

command 是：

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（下载模块到本地缓存）

用法：

go mod download [-json] [modules]

download命令下载命名模块，模块是那些可以被模块模式选择的主模块依赖或者路径格式为@version的模块查询。如果没有参数，download 应用于所有依赖项的主模块

在进行普通操作是go命令将自动下载模块。“go mod download”一般主要用于对本地缓存的预填充或者验证go模块代理。

默认情况下，如果download出现错误，则打印标准错误信息，没有则为空。 -json 标记指示download输出一系列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)
}

有关模块查询的更多信息，请参阅“go help modules”。

Edit go.mod from tools or scripts（使用工具或脚本编辑go.mod）

用法：

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

edit提供了一个命令行界面用于编辑go.mod，主要用于工具或脚本。他只读go.mod；并没有查找关于模块的信息。默认情况下edit命令编辑主模块的go.mod文件，但是可以指定不同的编辑来指定编辑不同文件。

editing flags 参数指出一系列的编辑操作。

-fmt 编辑重新格式化go.mod而不进行任何更改。这样的重新格式化在其他修改到go.mod操作的时候也会发生。在没有指定其他标记的情况下才需要指定-fmt标记。

-module 标记改变模块路径（go.mod文件中 module 那行）

-require=path@version 与 -droprequire=path 标记分别添加，移除给定模块路径版本的的需求模块。注意 -require将覆盖任何存在的需求模块的路径。这两个标记主要用于了解模块视图的工具。用户更偏好使用"go get path@version" or "go get path@none"这样可以根据需要调整go.mod模块，以满足其他模块的导入需求。

-require, -droprequire, -exclude, -dropexclude, -replace, and -dropreplace 这些编辑标签可以重复，将按照给出的顺序依次做出修改。

-go=version 设置期望使用的Go语言版本。

-print 标记以text格式输出最终的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（输出模块需求视图）

用法：

go mod graph

graph 输出模块需求图表的文本格式（包括替换内容）。每行输出有由空格隔开的两部分组成，模块与其对应的需求。每个模块被格式 path@version 唯一识别，除了主模块，没有 @version 的版本后缀。

Initialize new module in current directory（在当前路径初始化模块）

用法：

go mod init [module]

init 初始化并在当前路径写入一个新的go.mod文件，实际上是在当前路径创建一个新模块根（module root）。原目录必须不存在go.mod文件。

如果可能的话，init将会根据import comments 或者版本控制系统的配置文件推算出模块路径。如果要重写路径，指定模块路径参数（module）

Add missing and remove unused modules（添加缺失模块，移除未使用模块）

用法：

go mod tidy [-v]

tidy 确保 go.mod文件与模块中源代码匹配。tidy添加当前模块包编译所需的缺失的模块，移除其它无关的模块。该命令同样添加缺失的实体到go.sum文件，并从中移除不需要的。

-v 标记指示tidy输出模块移除信息以及标准错误输出。

Make vendored copy of dependencies（创建依赖的 vendor复制）

用法：

go mod vendor [-v]

vendor重置主模块的vendor目录，使其包含所有编译需要的包，且测试所有主模块的包(??)。它不包括vendor包的测试代码

-v 标记指示vendor 以标准错误输出模块名，包名

Verify dependencies have expected content（验证依赖）

用法：

go mod verify

verify 检查当前模块的依赖（存储在本地下载缓存中）自下载后有没有被改变。如果所有模块都没有被修改，verify 输出“all modules verified”，否则将报告哪些模块被改变，然后导致 go mod 命令以非零状态退出。

Explain why packages or modules are needed（解释为何需要这些包与模块）

使用：

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.By default, why queries the graph of packages matched by "go list all", which includes tests for reachable packages. The -vendor flag causes why to exclude tests of dependencies.The output is a sequence of stanzas, one for each package or module name on the command line, separated by blank lines. Each stanza begins with a comment line "# package" or "# module" giving the target package or module. Subsequent lines give a path through the import graph, one package per line. If the package or module is not referenced from the main module, the stanza will display a single parenthesized note indicating that fact.For example:$ 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（编译运行Go程序）

用法：

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

run 编译运行命名的主Go包。通常 package 参数被指定为一系列.go源文件，不过它也可能是一个导入路径，文件系统路径，或者模式匹配到一个已知的包，例如"go run ." 或 "go run my/cmd"

默认情况下，go run 命令直接运行编译的二进制文件："a.out arguments..."。如果指定 -exec 标记，那么“go run”通过xprog调用二进制文件

'xprog a.out arguments...'

若为指定 -exec 标记，GOOS 或 GOARCH 与默认系统不一样，且当前搜索路径可用找到 go_GOARTH_exec 的文件，那么“go run”将通过该程序调用二进制文件，例如“go_nacl_386_exec a.out arguments...”这允许通过模拟器或其他方式执行交叉编译。

run的退出状态码与编译二进制文件的退出状态码不一样

Test packages（测试包）

用法：

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

"go test"对导入路径下的包自动化测试。它格式化输出测试结果的摘要：

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

每个测试失败的包会有详细输出。

“go test”重新编译包内每个匹配“_test.go”的文件。那些额外的文件可以包含函数测试，基准测试，样例测试（function,benchmark,example）。参阅“go help testfunc”了解更多。每个列出的包都会单独的执行测试二进制文件。以" _ " (包括_test.go)或"."开头的文件将被忽略。

那些以 " _test " 声明的包将被单独的编译，然后连接并与主测试文件一起运行。

go tool 将忽略名为 testdata的目录，使其可以用于放置测试需要的辅助数据

作为编译测试文件的一部分，go test 对包运行 vet，vet检查测试源文件中的重大问题。如果 go vet 找到任何问题，那么 go test将报告问题且终止执行。Only a high-confidence subset of the default go vet checks are used. That subset is: 'atomic', 'bool', 'buildtags', 'nilfunc', and 'printf'. You can see the documentation for these and other vet tests via "go doc cmd/vet". To disable the running of go vet, use the -vet=off flag.

所有的测试输出与汇总都打印到go命令的标准输出，即使测试打印他们自己的标准错误（go命令标准错误保留用于构建测试时打印错误。）

go test 使用以下两种方式运行测试：

第一种称为本地目录模式，在 go test 调用没有指定包参数的时候发生（例如："go test" "go test -v"）。在这个模式下，go test 命令编译当前目录中的包与测试，然后运行生成的测试文件。在此模式下禁用缓存。在测试完成后，go test 一行摘要显示测试结果（“ok”或“FAIL”），包名，还有已用时间。

第二种称为包列表模式，go test 调用指定确切的包参数时发生（例如"go test math","go test ./..."甚至是"go test ."）。在此模式下，go test 编译测试每个命令行中出现的包。如果包测试通过，go test最后只会输出一行“ok”作为总结。如果包测试失败，go test 打印完整的测试输出。如果调用带有 -bench 或 -v flag，go test 即使测试通过的包也会打印完整的输出，为了显示基准请求结果或荣誉的日志。

仅在包列表模式下，go test 会缓存成功运行测试的包，以避免没必要的重复执行。当可以从缓存中恢复测试结果时，go test将重新显示先前的输出，而不是再次运行测试二进制。发生这种情况时，go test 在输出行的使用时间后边打印“(cached)”。

缓存匹配的规则是：运行相同的测试文件且命令行上的标记全部来自'可缓存的'集合（-cpu, -list, -parallel, -run, -short, and -v）。如果执行的go test 命令行有任何测试或非测试标记不在上述集合中，则结果不可缓存。要关闭缓存，使用任何不在上述集合的测试标记。不使用缓存的惯用法是使用标记 -count=1。 Tests that open files within the package's source root (usually $GOPATH) or that consult environment variables only match future runs in which the files and environment variables are unchanged. A cached test result is treated as executing in no time at all, so a successful package test result will be cached and reused regardless of -timeout setting.

除了构建标记之外，“go test”本身处理的标记是：

-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 build”。有关指定包的更多信息，请参阅“go help packages”。另见：go build，go vet。

Run specified go tool

用法：

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

tool 运行有参数指定的go工具命令。如果没有参数，它输出已知的工具列表。

-n 标记指示tool 打印即将执行的命令，但是不执行它们。

有关每个工具命令的更多信息，请参阅“go doc cmd / ”。

Print Go version

Usage:

go version

Version prints the Go version, as reported by runtime.Version.

Report likely mistakes in packages（报告包中可能的错误）

用法：

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

vet 在导入路径命名包上运行 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 标记选择替代的分析工具或使用其它工具。例如使用以下命令构建运行“shadow”分析工具。

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

支持go vet 的 build 标记包含哪些控制包解析和执行的标记，如-n, -x, -v, -tags, and -toolexec

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.

Calling between Go and 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文件传递给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 构建标记强制重新构建依赖于更新的C链接库的包。

go命令也缓存成功的包测试结果。有关详细信息，请参阅“go help test”。运行'go clean -testcache'会删除所有缓存的测试结果（但不会缓存构建结果）。

The GODEBUG environment variable can enable printing of debugging information about the state of the cache:
GODEBUG=gocacheverify=1 causes the go command to bypass the use of any cache entries and instead rebuild everything and check that the results match existing cache entries.

GODEBUG=gocachehash=1 causes the go command to print the inputs for all of the content hashes it uses to construct cache lookup keys. The output is voluminous but can be useful for debugging the cache.

GODEBUG=gocachetest=1 causes the go command to print details of its decisions about whether to reuse a cached test result.

Environment variables（环境变量）

go 命令以及工具的调用，需要检查几个不同的环境变量。对于其中许多，您可以通过运行'go env NAME'来查看系统的默认值，其中NAME是变量的名称。

通用环境变量：

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.
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. 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 goproxy'.
GORACE
        Options for the race detector.
        See https://golang.org/doc/articles/race_detector.html.
GOROOT
        The root of the go tree.
GOTMPDIR
        The directory where the go command will write
        temporary source files, packages, and binaries.

GOFLAGS列表中的每个条目都必须是独立标志。由于条目是以空格分隔的，因此标志值不得包含空格。

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

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.
PKG_CONFIG
        Path to pkg-config tool.
AR
        The command to use to manipulate library archives when
        building with the gccgo compiler.
        The default is 'ar'.

体系结构特定的环境变量：

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.

专用环境变量：

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

“go env”提供的其他信息，但未从环境中读取：

GOEXE
        The executable file name suffix (".exe" on Windows, "" on other systems).
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.