go/build
Package build
import "go/build"
概述
索引
概述
Package build 收集有关 Go 包的信息。
Go Path
Go path 是包含 Go 源代码的目录树列表。它被咨询解决在标准 Go 树中找不到的导入。默认路径是 GOPATH 环境变量的值，被解释为适合于操作系统的路径列表（在 Unix 上，变量是冒号分隔的字符串；在 Windows 上是分号分隔的字符串；在 Plan 9上，是一个列表）。
Go path 中列出的每个目录必须具有规定的结构：
src/ 目录保存源代码。'src' 下面的路径决定了导入路径或可执行文件的名称。
pkg/directory 保存已安装的软件包对象。与 Go 树一样，每个目标操作系统和体系结构对都有自己的 pkg 子目录（pkg/GOOS_GOARCH）。
如果 DIR 是 Go 路径中列出的目录，那么在 DIR/src/foo/bar 中包含源文件的包可以作为“foo/bar”导入，并将其编译形式安装到“DIR/pkg/GOOS_GOARCH/foo/bar.a“（或者，对于gccgo，”DIR/pkg/gccgo/foo/libbar.a“）。
bin/directory 保存编译的命令。每个命令都是为其源目录命名的，但仅使用最后一个元素，而不是整个路径。也就是说，DIR/src/foo/quux 中源代码的命令安装在DIR/bin/quux中，而不是 DIR/bin/foo/quux 中。foo/ 被剥离，以便您可以将 DIR/bin 添加到 PATH 以获取已安装的命令。
以下是一个目录布局示例：
GOPATH=/home/user/gocode
/home/user/gocode/
src/
foo/
bar/ (go code in package bar)
x.go
quux/ (go code in package main)
y.go
bin/
quux (installed command)
pkg/
linux_amd64/
foo/
bar.a (installed package object)
建立约束（条件）
构建约束（条件），也称为构建标记，是一个开始的行注释
// +build
其中列出了文件应该包含在软件包中的条件。约束可能出现在任何类型的源文件中（而不仅仅是 Go），但它们必须出现在文件的顶部附近，仅由空行和其他行注释开头。这些规则意味着在 Go 文件中，构建约束必须出现在 package 子句之前。
为了将构建约束与包文档区分开来，必须在一系列构建约束之后加上空行。
构建约束被评估为空间分隔选项的OR；每个选项评估为逗号分隔术语的 AND；并且每个术语都是一个字母数字字，或者以！开头，否定。即构建约束：
// +build linux,386 darwin,!cgo
对应于布尔公式：
(linux AND 386) OR (darwin AND (NOT cgo))
一个文件可能有多个构建约束。总体约束是个体约束的“AND”。也就是说，构建约束：
// +build linux darwin
// +build 386
对应于布尔公式：
(linux OR darwin) AND 386
在特定版本中，以下词语得到满足：
- 目标操作系统，由runtime.GOOS拼写
- 目标体系结构，由runtime.GOARCH拼写
- 正在使用的编译器，“gc”或“gccgo”
- “cgo”，如果ctxt.CgoEnabled为true
- “go1.1”，从Go 1.1版开始
- “go1.2”，从Go 1.2版开始
- 从Go 1.3版开始，“go1.3”
- 从Go版本1.4开始的“go1.4”
- 从Go 1.5版开始的“go1.5”
- “go1.6”，从Go 1.6版开始
- 从Go版本1.7开始的“go1.7”
- 从Go版本1.8开始的“go1.8”
- 从Go版本1.9开始的“go1.9”
- ctxt.BuildTags中列出的任何其他单词
如果在剥离扩展名和可能的 _test 后缀后文件的名称与下列任何一种模式匹配：
*_GOOS
*_GOARCH
*_GOOS_GOARCH
（例如：source_windows_amd64.go）其中 GOOS 和 GOARCH 分别代表任何已知的操作系统和体系结构值，则该文件被认为具有隐含的构建约束，要求这些项（除了文件中的任何显式约束）。
为了防止构建文件被考虑：
// +build ignore
（任何其他不满意的词也会起作用，但“ignore”是常规的。）
仅在使用 cgo 时构建文件，并且仅在 Linux 和 OS X 上构建文件：
// +build linux,cgo darwin,cgo
这样的文件通常与其他文件实现默认功能的其他文件配对，在这种情况下，该文件会带来约束：
// +build !linux,!darwin !cgo
命名文件 dns_windows.go 将导致它仅在为 Windows 构建软件包时才被包含；同样，只有在为32位x86构建软件包时才会包含 math_386.s。
除了 android 标签和文件，使用 GOOS=android 与GOOS = linux 匹配构建标签和文件。
Binary-Only（仅二进制） Packages
可以以二进制形式分发包，而不包括用于编译包的源代码。要做到这一点，软件包必须与源代码文件一起分发，而不是通过构建约束排除并包含“//go:binary-only-package ”注释。与构建约束一样，此注释必须出现在文件的顶部附近，仅以空行和其他行注释开头，并且在注释后面有空行，以便将其与包文档分开。与构建约束不同，此评论仅在非测试 Go 源文件中才能识别。
因此只有二进制包的最小源代码是：
//go:binary-only-package
package mypkg
源代码可能包含额外的 Go 代码。该代码从未编译过，但会被诸如 godoc 之类的工具处理，并可能作为最终用户文档很有用。
索引
- Variables
- func ArchChar(goarch string) (string, error)
- func IsLocalImport(path string) bool
- type Context
- func (ctxt *Context) Import(path string, srcDir string, mode ImportMode) (*Package, error)
- func (ctxt *Context) ImportDir(dir string, mode ImportMode) (*Package, error)
- func (ctxt *Context) MatchFile(dir, name string) (match bool, err error)
- func (ctxt *Context) SrcDirs() []string
- type ImportMode
- type MultiplePackageError
- func (e *MultiplePackageError) Error() string
- type NoGoError
- func (e *NoGoError) Error() string
- type Package
- func Import(path, srcDir string, mode ImportMode) (*Package, error)
- func ImportDir(dir string, mode ImportMode) (*Package, error)
- func (p *Package) IsCommand() bool
包文件
build.go doc.go read.go syslist.go
变量
ToolDir 是包含构建工具的目录。
var ToolDir = filepath.Join(runtime.GOROOT(), "pkg/tool/"+runtime.GOOS+"_"+runtime.GOARCH)
func ArchChar（显示源代码）
func ArchChar(goarch string) (string, error)
ArchChar 返回“？” 和一个错误。在早期版本的 Go 中，返回的字符串用于派生编译器和链接器工具名称，缺省对象文件后缀和默认链接器输出名称。从 Go 1.5 开始，这些字符串不再因架构而异; 它们分别是compile，link，.o 和 a.out。
func IsLocalImport（显示源代码）
func IsLocalImport(path string) bool
IsLocalImport 报告导入路径是否为本地导入路径，如“。”，“..”，“./foo”或“../foo”。
type Context（显示源代码）
上下文指定了构建的支持上下文。
type Context struct {
GOARCH string // 目标架构
GOOS string // 目标操作系统
GOROOT string // Go root
GOPATH string // Go path
CgoEnabled bool // 是否可以使用cgo
UseAllFiles bool // 使用文件而不管+build行，文件名
Compiler string // 编译器在计算目标路径时假设
// 构建和发布标记指定构建约束
// 在处理+build线时应该被认为是满意的。
// 创建新上下文的客户端可以自定义BuildTags
// 默认为空，但自定义ReleaseTags通常是错误的，
// 默认为当前版本兼容的Go版本列表。
// 除了BuildTags和ReleaseTags之外，还要构建约束
// 将GOARCH和GOOS的值视为满意标记。
BuildTags []string
ReleaseTags []string
// 安装后缀指定要在安装名称中使用的后缀
// 目录。 默认情况下它是空的，但需要保留自定义构建
// 它们的输出分开可以设置InstallSuffix这样做。 例如，当
// 使用竞争检测器，go命令使用InstallSuffix =“race”，所以
// 在Linux/386系统上，软件包被写入一个名为的目录
// “linux_386_race”而不是通常的“linux_386”。
InstallSuffix string
// JoinPath将路径片段序列连接到单个路径中。
// 如果JoinPath为nil，则Import使用filepath.Join。
JoinPath func(elem ...string) string
// SplitPathList将路径列表拆分为单个路径的切片。
// 如果SplitPathList为nil，则Import使用filepath.SplitList。
SplitPathList func(list string) []string
// IsAbsPath报告路径是否为绝对路径。
// 如果IsAbsPath为nil，则Import使用filepath.IsAbs。
IsAbsPath func(path string) bool
// IsDir报告路径是否命名目录。
// 如果IsDir为nil，则Import调用os.Stat并使用结果的IsDir方法。
IsDir func(path string) bool
// HasSubdir报告dir是否是词汇的子目录
// root，也许是下面的多个级别。 它不试图检查
// 是否存在目录。
// 如果是这样，HasSubdir将rel设置为斜杠分隔的路径
// 可以连接到root以生成相当于dir的路径。
// 如果HasSubdir为nil，则Import使用构建的实现
// filepath.EvalSymlinks。
HasSubdir func(root, dir string) (rel string, ok bool)
// ReadDir返回一个os.FileInfo片段，按名称排序，
// 描述命名目录的内容。
// 如果ReadDir为nil，则Import使用ioutil.ReadDir。
ReadDir func(dir string) ([]os.FileInfo, error)
// OpenFile打开一个文件（不是目录）进行读取。
// 如果OpenFile为nil，则Import使用os.Open。
OpenFile func(path string) (io.ReadCloser, error)
}
默认是构建的默认上下文。它使用 GOARCH，GOOS，GOROOT 和 GOPATH 环境变量（如果已设置），或者编译代码的 GOARCH，GOOS 和 GOROOT。
var Default Context = defaultContext()
func (*Context) Import（显示源代码）
func (ctxt *Context) Import(path string, srcDir string, mode ImportMode) (*Package, error)
导入返回有关由导入路径命名的Go包的详细信息，解释相对于 srcDir 目录的本地导入路径。如果路径是命名可以使用标准导入路径导入的包的本地导入路径，则返回的包会将 p.ImportPath 设置为该路径。
在包含该软件包的目录中，.go，.c，.h 和 .s 文件被视为软件包的一部分，但以下内容除外：
- 包文档中的.go文件
- 以_或开头的文件。（可能是编辑临时文件）
- 具有上下文不满足的构建约束的文件
如果发生错误，Import 将返回一个非零错误和一个非零*Package 含部分信息的包。
func (*Context) ImportDir（显示源代码）
func (ctxt *Context) ImportDir(dir string, mode ImportMode) (*Package, error)
ImportDir 与 Import 类似，但处理指定目录中的 Go包。
func (*Context) MatchFile（显示源代码）
func (ctxt *Context) MatchFile(dir, name string) (match bool, err error)
MatchFile 报告给定目录中具有给定名称的文件是否与上下文相匹配，并且将包含在由该目录的 ImportDir 创建的包中。
MatchFile 考虑文件的名称，并可能使用 ctxt.OpenFile 来读取文件的部分或全部内容。
func (*Context) SrcDirs（显示源代码）
func (ctxt *Context) SrcDirs() []string
SrcDirs 返回一个包源代码根目录的列表。它从当前的 Go 和 Go 路径绘制，但省略了不存在的目录。
type ImportMode（显示源代码）
ImportMode 控制 Import 方法的行为。
type ImportMode uint
const (
// 如果设置了FindOnly，则在找到目录后，Import将停止
// 应该包含包的来源。 它没有
// 读取目录中的任何文件。
FindOnly ImportMode = 1 << iota
// 如果设置了AllowBinary，则可以通过编译来满足Import
// 没有相应来源的包对象。
//
// Deprecated（推荐使用）:
// 创建仅编译包的受支持方式是
// 编写包含//go:binary-only-package注释的源代码
// 文件的顶部。 这样的包装将被认可
// 无论这个标志设置如何（因为它有源代码）
// 并将在返回的包中将BinaryOnly设置为true。
AllowBinary
// 如果设置了ImportComment，则解析对包语句的导入注释。
// 如果导入发现无法理解的注释，则返回错误
// 或在多个源文件中查找冲突的注释。
// 有关更多信息，请参阅golang.org/s/go14customimport。
ImportComment
// 默认情况下，Import搜索供应商目录
// 在搜索之前应用于给定的源目录
// GOROOT和GOPATH的根源。
// 如果Import使用供应商查找并返回包
// 目录，生成的ImportPath是完整路径
// 到包，包括导致的路径元素
// 包括“供应商”。
// 例如，如果导入（“y”，“x/subdir”，0）找到
// “x/vendor/y”，返回的包的ImportPath是“x/vendor/y”，
// 不是简单的“y”。
// 有关更多信息，请参阅golang.org/s/go15vendor。
//
// 设置IgnoreVendor会忽略供应商目录。
//
// 与包的ImportPath相反，
// 返回的包的Imports，TestImports和XTestImports
// 始终是源文件的确切导入路径：
// 导入不会尝试解析或检查这些路径。
IgnoreVendor
)
type MultiplePackageError（显示源代码）
MultiplePackageError 描述了包含多个包的多个可构建的 Go 源文件的目录。
type MultiplePackageError struct {
Dir string // 包含文件的目录
Packages []string // 找到包名
Files []string // 相应文件：Files [i]声明包Packages [i]
}
func (*MultiplePackageError) Error（显示源代码）
func (e *MultiplePackageError) Error() string
type NoGoError（显示源代码）
NoGoError 是 Import 用来描述不包含可构建的 Go 源文件的目录所使用的错误。（它可能仍然包含测试文件，被构建标签隐藏的文件等等。）
type NoGoError struct {
Dir string
}
func (*NoGoError) Error（显示源代码）
func (e *NoGoError) Error() string
type Package（显示源代码）
软件包描述了在目录中找到的 Go 软件包。
type Package struct {
Dir string // 包含包源的目录
Name string // 包名称
ImportComment string // 导入路径注释包语句
Doc string // 文档概要
ImportPath string // 包的导入路径（“”如果未知）
Root string // 这个包所在的Go树的根
SrcRoot string // 包源根目录（“”如果未知）
PkgRoot string // 包安装根目录（“”如果未知）
PkgTargetRoot string // 体系结构依赖安装根目录（“”如果未知）
BinDir string // 命令安装目录（“”如果未知）
Goroot bool // 在Go root中找到的包
PkgObj string // 安装.a文件
AllTags []string // 可能影响此目录中文件选择的标记
ConflictDir string // 这个目录在$ GOPATH中影子目录
BinaryOnly bool // 无法从源重建（有//go:binary-only-package注释）
// 源文件
GoFiles []string // .go源文件（不包括CgoFiles，TestGoFiles，XTestGoFiles）
CgoFiles []string // .go导入“C”的源文件
IgnoredGoFiles []string // .go源文件被忽略为此版本
InvalidGoFiles []string // .go源文件检测到问题（解析错误，包名错误等）
CFiles []string // .c源文件
CXXFiles []string // .cc，.cpp和.cxx源文件
MFiles []string // .m（Objective-C）源文件
HFiles []string // .h，.hh，.hpp和.hxx源文件
FFiles []string // .f，.F，.for和.f90 Fortran源文件
SFiles []string // .s源文件
SwigFiles []string // .swig文件
SwigCXXFiles []string // .swigcxx文件
SysoFiles []string // .syso系统对象文件添加到存档
// Cgo 指令
CgoCFLAGS []string // Cgo CFLAGS 指令
CgoCPPFLAGS []string // Cgo CPPFLAGS 指令
CgoCXXFLAGS []string // Cgo CXXFLAGS 指令
CgoFFLAGS []string // Cgo FFLAGS 指令
CgoLDFLAGS []string // Cgo LDFLAGS 指令
CgoPkgConfig []string // Cgo pkg-config 指令
// 依赖性信息
Imports []string // 从GoFiles，CgoFiles导入路径
ImportPos map[string][]token.Position // Imports的行信息
// Test information
TestGoFiles []string // 包中的_test.go文件
TestImports []string // 从TestGoFiles导入路径
TestImportPos map[string][]token.Position // TestImports的行信息
XTestGoFiles []string // 包外的_test.go文件
XTestImports []string // 从XTestGoFiles导入路径
XTestImportPos map[string][]token.Position // XTestImports的行信息
}
func Import（显示源代码）
func Import(path, srcDir string, mode ImportMode) (*Package, error)
Import 是 Default.Import 的简写。
func ImportDir（显示源代码）
func ImportDir(dir string, mode ImportMode) (*Package, error)
ImportDir 是 Default.ImportDir 的简写。
func (*Package) IsCommand（显示源代码）
func (p *Package) IsCommand() bool
IsCommand 报告包是否被视为要安装的命令（不仅仅是库）。名为“main”的软件包被视为命令。
