Namespace: go.std.go.build

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms
• Types

Summary

Provides a low-level interface to the go/build package.

Package build gathers information about Go packages.

# Go Path

The Go path is a list of directory trees containing Go source code.
It is consulted to resolve imports that cannot be found in the standard
Go tree. The default path is the value of the GOPATH environment
variable, interpreted as a path list appropriate to the operating system
(on Unix, the variable is a colon-separated string;
on Windows, a semicolon-separated string;
on Plan 9, a list).

Each directory listed in the Go path must have a prescribed structure:

The src/ directory holds source code. The path below 'src' determines
the import path or executable name.

The pkg/ directory holds installed package objects.
As in the Go tree, each target operating system and
architecture pair has its own subdirectory of pkg
(pkg/GOOS_GOARCH).

If DIR is a directory listed in the Go path, a package with
source in DIR/src/foo/bar can be imported as "foo/bar" and
has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a"
(or, for gccgo, "DIR/pkg/gccgo/foo/libbar.a").

The bin/ directory holds compiled commands.
Each command is named for its source directory, but only
using the final element, not the entire path. That is, the
command with source in DIR/src/foo/quux is installed into
DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped
so that you can add DIR/bin to your PATH to get at the
installed commands.

Here's an example directory layout:

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 Constraints

A build constraint, also known as a build tag, is a condition under which a
file should be included in the package. Build constraints are given by a
line comment that begins

//go:build

Build constraints may also be part of a file's name
(for example, source_windows.go will only be included if the target
operating system is windows).

See 'go help buildconstraint'
(https://golang.org/cmd/go/#hdr-Build_constraints) for details.

# Binary-Only Packages

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.

Index

• *Context
• *ImportMode
• *MultiplePackageError
• *NoGoError
• *Package
• AllowBinary
• ArchChar
• Context
• Default
• FindOnly
• IgnoreVendor
• Import
• ImportComment
• ImportDir
• ImportMode
• IsLocalImport
• MultiplePackageError
• NoGoError
• Package
• ToolDir
• arrayOfContext
• arrayOfImportMode
• arrayOfMultiplePackageError
• arrayOfNoGoError
• arrayOfPackage

Legend

Constant Variable Function Macro Special form Type GoVar Receiver/Method

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

(None.)

Variables

• AllowBinary

  GoObject v1.0

  If AllowBinary is set, Import can be satisfied by a compiled
  package object without corresponding sources.
  
  Deprecated:
  The supported way to create a compiled-only package is to
  write source code containing a //go:binary-only-package comment at
  the top of the file. Such a package will be recognized
  regardless of this flag setting (because it has source code)
  and will have BinaryOnly set to true in the returned Package.
  

• Default

  Var v1.0

  Default is the default Context for builds.
  It uses the GOARCH, GOOS, GOROOT, and GOPATH environment variables
  if set, or else the compiled code's GOARCH, GOOS, and GOROOT.
  

• FindOnly

  GoObject v1.0

  If FindOnly is set, Import stops after locating the directory
  that should contain the sources for a package. It does not
  read any files in the directory.
  

• IgnoreVendor

  GoObject v1.0

  By default, Import searches vendor directories
  that apply in the given source directory before searching
  the GOROOT and GOPATH roots.
  If an Import finds and returns a package using a vendor
  directory, the resulting ImportPath is the complete path
  to the package, including the path elements leading up
  to and including "vendor".
  For example, if Import("y", "x/subdir", 0) finds
  "x/vendor/y", the returned package's ImportPath is "x/vendor/y",
  not plain "y".
  See golang.org/s/go15vendor for more information.
  
  Setting IgnoreVendor ignores vendor directories.
  
  In contrast to the package's ImportPath,
  the returned package's Imports, TestImports, and XTestImports
  are always the exact import paths from the source files:
  Import makes no attempt to resolve or check those paths.
  

• ImportComment

  GoObject v1.0

  If ImportComment is set, parse import comments on package statements.
  Import returns an error if it finds a comment it cannot understand
  or finds conflicting comments in multiple source files.
  See golang.org/s/go14customimport for more information.
  

• ToolDir

  Var v1.0

  ToolDir is the directory containing build tools.
  

Functions, Macros, and Special Forms

• ArchChar

  Function v1.0

  (ArchChar goarch)
  

  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.
  
  Go input arguments: (goarch string)
  
  Go returns: (string, error)
  
  Joker input arguments: [^String goarch]
  
  Joker returns: [^String, ^Error]

• Import

  Function v1.0

  (Import path srcDir mode)
  

  Import is shorthand for Default.Import.
  
  Go input arguments: (path string, srcDir string, mode ImportMode)
  
  Go returns: (*Package, error)
  
  Joker input arguments: [^String path, ^String srcDir, ^ImportMode mode]
  
  Joker returns: [^*Package, ^Error]

• ImportDir

  Function v1.0

  (ImportDir dir mode)
  

  ImportDir is shorthand for Default.ImportDir.
  
  Go input arguments: (dir string, mode ImportMode)
  
  Go returns: (*Package, error)
  
  Joker input arguments: [^String dir, ^ImportMode mode]
  
  Joker returns: [^*Package, ^Error]

• IsLocalImport

  Function v1.0

  (IsLocalImport path)
  

  IsLocalImport reports whether the import path is
  a local import path, like ".", "..", "./foo", or "../foo".
  
  Go input arguments: (path string)
  
  Go returns: bool
  
  Joker input arguments: [^String path]
  
  Joker returns: ^Boolean

Types

• *Context

  Concrete Type v1.0

  A Context specifies the supporting context for a build.
  

• Import

  Receiver for *Context v1.0

  ([path srcDir mode])
  

  Import returns details about the Go package named by the import path,
  interpreting local import paths relative to the srcDir directory.
  If the path is a local import path naming a package that can be imported
  using a standard import path, the returned package will set p.ImportPath
  to that path.
  
  In the directory containing the package, .go, .c, .h, and .s files are
  considered part of the package except for:
  
  - .go files in package documentation
  - files starting with _ or . (likely editor temporary files)
  - files with build constraints not satisfied by the context
  
  If an error occurs, Import returns a non-nil error and a non-nil
  *Package containing partial information.
  

• ImportDir

  Receiver for *Context v1.0

  ([dir mode])
  

  ImportDir is like Import but processes the Go package found in
  the named directory.
  

• MatchFile

  Receiver for *Context v1.0

  ([dir name])
  

  MatchFile reports whether the file with the given name in the given directory
  matches the context and would be included in a Package created by ImportDir
  of that directory.
  
  MatchFile considers the name of the file and may use ctxt.OpenFile to
  read some or all of the file's content.
  

• SrcDirs

  Receiver for *Context v1.0

  ([])
  

  SrcDirs returns a list of package source root directories.
  It draws from the current Go root and Go path but omits directories
  that do not exist.
  

• *ImportMode

  Concrete Type v1.0

  An ImportMode controls the behavior of the Import method.
  

• *MultiplePackageError

  Concrete Type v1.0

  MultiplePackageError describes a directory containing
  multiple buildable Go source files for multiple packages.
  

• Error

  Receiver for *MultiplePackageError v1.0

  ([])
  

• *NoGoError

  Concrete Type v1.0

  NoGoError is the error used by Import to describe a directory
  containing no buildable Go source files. (It may still contain
  test files, files hidden by build tags, and so on.)
  

• Error

  Receiver for *NoGoError v1.0

  ([])
  

• *Package

  Concrete Type v1.0

  A Package describes the Go package found in a directory.
  

• IsCommand

  Receiver for *Package v1.0

  ([])
  

  IsCommand reports whether the package is considered a
  command to be installed (not just a library).
  Packages named "main" are treated as commands.
  

• Context

  Concrete Type v1.0

  A Context specifies the supporting context for a build.
  

• ImportMode

  Concrete Type v1.0

  An ImportMode controls the behavior of the Import method.
  

• MultiplePackageError

  Concrete Type v1.0

  MultiplePackageError describes a directory containing
  multiple buildable Go source files for multiple packages.
  

• NoGoError

  Concrete Type v1.0

  NoGoError is the error used by Import to describe a directory
  containing no buildable Go source files. (It may still contain
  test files, files hidden by build tags, and so on.)
  

• Package

  Concrete Type v1.0

  A Package describes the Go package found in a directory.
  

• arrayOfContext

  Concrete Type v1.0

  A Context specifies the supporting context for a build.
  

• arrayOfImportMode

  Concrete Type v1.0

  An ImportMode controls the behavior of the Import method.
  

• arrayOfMultiplePackageError

  Concrete Type v1.0

  MultiplePackageError describes a directory containing
  multiple buildable Go source files for multiple packages.
  

• arrayOfNoGoError

  Concrete Type v1.0

  NoGoError is the error used by Import to describe a directory
  containing no buildable Go source files. (It may still contain
  test files, files hidden by build tags, and so on.)
  

• arrayOfPackage

  Concrete Type v1.0

  A Package describes the Go package found in a directory.