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”的软件包被视为命令。