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