...

パッケージ build

import "go/build"
概要
目次

概要 ▾

build パッケージは, Go パッケージの情報を集めます。

Go パス

Go パスは, Go のソースコードを含むディレクトリツリーのリストです。 標準の Go ツリーには見つからないインポートを解決するために調べられます。 デフォルトパスは, GOPATH 環境変数の値で,オペレーティングシステムに適したパスリストとして解釈されます (UNIX の場合,変数はコロンで区切られた文字列, Windows の場合はセミコロンで区切られた文字列, Plan 9 の場合はリスト))

Go パスにリストされている各ディレクトリは,規定の構造を持っている必要があります。

src/ ディレクトリはソースコードを保持しています。 'src' の下のパスは,インポートパスまたは実行可能ファイル名を決定します。

pkg/ ディレクトリはインストールされたパッケージオブジェクトを保持しています。 Go ツリーと同様に,各ターゲットオペレーティングシステムとアーキテクチャのペアには, pkg という独自のサブディレクトリ (pkg/GOOS_GOARCH) があります。

DIR が Go パスにリストされているディレクトリである場合, DIR/src/foo/bar に source を持つパッケージは "foo/bar" としてインポートでき,コンパイルされた形式は "DIR/pkg/GOOS_GOARCH/foo/bar" にインストールされます。 (または, gccgo の場合は "DIR/pkg/gccgo/foo/libbar.a")

bin/ ディレクトリはコンパイルされたコマンドを保持します。 各コマンドはそのソースディレクトリの名前が付けられていますが,パス全体ではなく,最後の要素のみを使用しています。 つまり, DIR/src/foo/quux に source を指定したコマンドは, DIR/bin/foo/quux ではなく DIR/bin/quux にインストールされます。 あなたがインストールされたコマンドを取得するためにあなたの PATH に DIR/bin を追加することができるように foo/ は取り除かれます。

これがディレクトリレイアウトの例です。

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 ファイルでは build 句がパッケージ句の前になければならないことを意味します。

ビルド制約をパッケージの資料と区別するために,一連のビルド制約の後にブランク行を続けなければなりません。

A build constraint is evaluated as the OR of space-separated options. Each option evaluates as the AND of its comma-separated terms. Each term consists of letters, digits, underscores, and dots. A term may be negated with a preceding !. For example, the build constraint:

// +build linux,386 darwin,!cgo

ブール式に対応します。

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

ファイルには複数のビルド制約があります。 全体的な制約は個々の制約の AND です。 つまり,ビルドの制約は次のとおりです。

// +build linux darwin
// +build 386

ブール式に対応します。

(linux OR darwin) AND 386

特定のビルド中に,以下の単語が満たされます。

- the target operating system, as spelled by runtime.GOOS
- the target architecture, as spelled by runtime.GOARCH
- the compiler being used, either "gc" or "gccgo"
- "cgo", if ctxt.CgoEnabled is true
- "go1.1", from Go version 1.1 onward
- "go1.2", from Go version 1.2 onward
- "go1.3", from Go version 1.3 onward
- "go1.4", from Go version 1.4 onward
- "go1.5", from Go version 1.5 onward
- "go1.6", from Go version 1.6 onward
- "go1.7", from Go version 1.7 onward
- "go1.8", from Go version 1.8 onward
- "go1.9", from Go version 1.9 onward
- "go1.10", from Go version 1.10 onward
- "go1.11", from Go version 1.11 onward
- "go1.12", from Go version 1.12 onward
- "go1.13", from Go version 1.13 onward
- any additional words listed in 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 用のパッケージをビルドするときにのみ含まれるようになります。 同様に, math_386.s は, 32 ビット x86 用のパッケージをビルドするときにのみ含まれます。

GOOS=android を使用すると, android のタグやファイルに加えて GOOS=linux のようにタグやファイルを作成できます。

Using GOOS=illumos matches build tags and files as for GOOS=solaris in addition to illumos tags and files.

バイナリのみのパッケージ

In Go 1.12 and earlier, it was possible to distribute packages in binary form without including the source code used for compiling the package. The package was distributed with a source file not excluded by build constraints and containing a "//go:binary-only-package" comment. Like a build constraint, this comment appeared at the top of a file, preceded only by blank lines and other line comments and with a blank line following the comment, to separate it from the package documentation. Unlike build constraints, this comment is only recognized in non-test Go source files.

The minimal source code for a binary-only package was therefore:

//go:binary-only-package

package mypkg

The source code could include additional Go code. That code was never compiled but would be processed by tools like godoc and might be useful as end-user documentation.

"go build" and other commands no longer support binary-only-packages. Import and ImportDir will still set the BinaryOnly flag in packages containing these comments for use in tools and error messages.

変数

ToolDir is the directory containing build tools.

var ToolDir = getToolDir()

func ArchChar

func ArchChar(goarch string) (string, error)

ArchChar returns "?" and an error. In earlier versions of Go, the returned string was used to derive the compiler and linker tool names, the default object file suffix, and the default linker output name. As of Go 1.5, those strings no longer vary by architecture; they are compile, link, .o, and a.out, respectively.

func IsLocalImport

func IsLocalImport(path string) bool

IsLocalImport reports whether the import path is a local import path, like ".", "..", "./foo", or "../foo".

type Context

Context は,ビルドをサポートするコンテキストを指定します。

type Context struct {
    GOARCH      string // ターゲットアーキテクチャ
    GOOS        string // ターゲットオペレーティングシステム
    GOROOT      string // Go root
    GOPATH      string // Go path
    CgoEnabled  bool   // cgo ファイルが含まれているかどうか
    UseAllFiles bool   // +build lines, file namesに関係なくファイルを使用する
    Compiler    string // ターゲットパスを計算するときに想定するコンパイラ

    // build タグと release タグは,ビルド行を処理するときに満たされると見なされるべきビルド制約を指定します。
    // 新しいコンテキストを作成するクライアントは BuildTags をカスタマイズすることができます。
    // デフォルトは空ですが,通常 ReleaseTags をカスタマイズすることはエラーです。
    // デフォルトは現在のリリースと互換性のある Go リリースのリストです。
    // デフォルトのビルドコンテキストに BuildTags は設定されていません。
    // BuildTags と ReleaseTags に加えて,ビルド制約は GOARCH と GOOS の値も制約を満たすタグと見なします。
    // ReleaseTags の最後の要素は現在のリリースと見なされます。
    BuildTags   []string
    ReleaseTags []string // Go 1.1

    // インストールサフィックスは,インストールディレクトリの名前に使用するサフィックスを指定します。
    // デフォルトでは空ですが,出力を別々にしておく必要があるカスタムビルドは InstallSuffix をそうするように設定できます。
    // 例えば,競合検出機能を使用している場合, go コマンドは InstallSuffix = "race" を使用するため, Linux/386 システムでは,パッケージは通常の "linux_386" ではなく "linux_386_race" という名前のディレクトリに書き込まれます。
    InstallSuffix string // Go 1.1

    // JoinPath は,パスフラグメントのシーケンスを 1 つのパスに結合します。
    // 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 が語彙的にルートのサブディレクトリであるかどうかを報告します。
    // おそらく複数レベル下にあります。
    // dir が存在するかどうかを確認しようとしません。
    // もしそうであれば, 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)

Import は, srcDir ディレクトリを基準としたローカルインポートパスを解釈して,インポートパスで指定された Go パッケージに関する詳細を返します。 パスが標準のインポートパスを使用してインポートできるパッケージの名前を付けたローカルインポートパスである場合,返されるパッケージは p.ImportPath をそのパスに設定します。

パッケージを含むディレクトリでは, .go, .c, .h ,および .s ファイルは,以下を除いてパッケージの一部と見なされます。

- パッケージドキュメントの .go ファイル
- _ または . で始まるファイル。(おそらくエディタ一時ファイル)
- コンテキストによって満たされないビルド制約を持つファイル

エラーが発生した場合, Import は nil 以外のエラーと部分的な情報を含む nil 以外の *Package を返します。

func (*Context) ImportDir

func (ctxt *Context) ImportDir(dir string, mode ImportMode) (*Package, error)

ImportDir は Import に似ていますが,指定されたディレクトリにある Go パッケージを処理します。

func (*Context) MatchFile 1.2

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 が設定されている場合,インポートはパッケージのソースを含むべきディレクトリを見つけた後に停止します。
    // ディレクトリ内のファイルは読み込まれません。
    FindOnly ImportMode = 1 << iota

    // AllowBinary が設定されている場合,インポートは,対応するソースがなくてもコンパイル済みパッケージオブジェクトによって満たされます。
    //
    // 非推奨 : コンパイル専用パッケージを作成するためのサポートされている方法は,ファイルの先頭に //go:binary-only-package コメントを含むソースコードを書くことです。
    // そのようなパッケージは,このフラグ設定に関係なく (ソースコードがあるため) 認識され,返される Package では BinaryOnly が true に設定されます。
    AllowBinary

    // ImportComment が設定されている場合,パッケージステートメントのインポートコメントを解析します。
    // 理解できないコメントが見つかった場合,または複数のソースファイルで競合するコメントが見つかった場合, Import はエラーを返します。
    // 詳細については golang.org/s/go14customimport を参照してください。
    ImportComment

    // デフォルトでは, Import は GOROOT と GOPATH のルートを検索する前に,与えられたソースディレクトリに適用されるベンダーディレクトリを検索します。
    // Import がベンダーディレクトリを使ってパッケージを見つけて返す場合,結果の ImportPath はパッケージへの完全なパスで, "vendor" までのパス要素を含みます。
    // たとえば, Import("y", "x/subdir", 0) が "x/vendor/y" を見つけた場合,返されるパッケージの ImportPath は "x/vendor/y" であり,単なる "y" ではありません。
    // 詳しくは golang.org/s/go15vendor をご覧ください。
    //
    // IgnoreVendor を設定すると,ベンダーのディレクトリは無視されます。
    //
    // パッケージの ImportPath とは対照的に,返されるパッケージの Imports, TestImports ,および XTestImports は常にソースファイルからの正確なインポートパスです。
    // インポートはこれらのパスを解決または確認しようとしません。
    IgnoreVendor
)

type MultiplePackageError 1.4

MultiplePackageError は,複数のパッケージ用の複数のビルド可能な Go ソースファイルを含むディレクトリを記述します。

type MultiplePackageError struct {
    Dir      string   // ファイルを含むディレクトリ
    Packages []string // パッケージ名が見つかりました
    Files    []string // 対応するファイル : Files[i] はパッケージ Packages[i] を宣言します
}

func (*MultiplePackageError) Error 1.4

func (e *MultiplePackageError) Error() string

type NoGoError

NoGoError は,ビルド可能な Go ソースファイルを含まないディレクトリを記述するために Import によって使用されるエラーです。 (テストファイル, build タグによって隠されたファイルなどを含むかもしれません。)

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   // パッケージステートメントのインポートコメント内のパス; added in Go 1.4
    Doc           string   // ドキュメンテーションの概要
    ImportPath    string   // パッケージのインポートパス (不明な場合は "")
    Root          string   // このパッケージが存在する Go ツリーのルート
    SrcRoot       string   // パッケージソースのルートディレクトリ (不明な場合は "")
    PkgRoot       string   // パッケージインストールルートディレクトリ (不明な場合は "")
    PkgTargetRoot string   // アーキテクチャ依存のインストールルートディレクトリ (不明な場合は ""); added in Go 1.5
    BinDir        string   // コマンドインストールディレクトリ (不明な場合は "")
    Goroot        bool     // Go root で見つけたパッケージ
    PkgObj        string   // インストールされた .a ファイル
    AllTags       []string // このディレクトリのファイル選択に影響を与える可能性のあるタグ; added in Go 1.2
    ConflictDir   string   // このディレクトリは, $GOPATH 内の Dir をシャドウします。; added in Go 1.2
    BinaryOnly    bool     // ソースから再構築することはできません (//go:binary-only- パッケージコメントがあります); added in Go 1.7

    // ソースファイル
    GoFiles        []string // .go ソースファイル (CgoFiles , TestGoFiles , XTestGoFiles を除く)
    CgoFiles       []string // "C" をインポートする .go ソースファイル
    IgnoredGoFiles []string // このビルドでは無視される .go ソースファイル; added in Go 1.1
    InvalidGoFiles []string // 問題が検出された .go ソースファイル (解析エラー,誤ったパッケージ名など); added in Go 1.6
    CFiles         []string // .c ソースファイル
    CXXFiles       []string // .cc, .cpp ,および .cxx のソースファイル; added in Go 1.2
    MFiles         []string // .m (Objective-C) ソースファイル; added in Go 1.3
    HFiles         []string // .h, .hh, .hpp ,および .hxx のソースファイル
    FFiles         []string // .f, .F, .for ,および .f90 Fortran ソースファイル; added in Go 1.7
    SFiles         []string // .s ソースファイル
    SwigFiles      []string // .swig ファイル; added in Go 1.1
    SwigCXXFiles   []string // .swigcxx ファイル; added in Go 1.1
    SysoFiles      []string // アーカイブに追加する .syso システムオブジェクトファイル

    // Cgo ディレクティブ
    CgoCFLAGS    []string // Cgo CFLAGS ディレクティブ
    CgoCPPFLAGS  []string // Cgo CPPFLAGS ディレクティブ; added in Go 1.2
    CgoCXXFLAGS  []string // Cgo CXXFLAGS ディレクティブ; added in Go 1.2
    CgoFFLAGS    []string // Cgo FFLAGS ディレクティブ; added in Go 1.7
    CgoLDFLAGS   []string // Cgo LDFLAGS ディレクティブ
    CgoPkgConfig []string // Cgo pkg-config ディレクティブ

    // 依存関係情報
    Imports   []string                    // GoFiles, CgoFiles からのパスのインポート
    ImportPos map[string][]token.Position // インポートの行情報

    // テスト情報
    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)

インポートは 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" という名前のパッケージはコマンドとして扱われます。