build
import "github.com/gopherjs/gopherjs/build"
Package build implements GopherJS build system.
WARNING: This package's API is treated as internal and currently doesn't provide any API stability guarantee, use it at your own risk. If you need a stable interface, prefer invoking the gopherjs CLI tool as a subprocess.
Variables
DefaultGOROOT is the default GOROOT value for builds.
It uses the GOPHERJS_GOROOT environment variable if it is set, or else the default GOROOT value of the system Go distribution.
var DefaultGOROOT = func() string {
if goroot, ok := os.LookupEnv("GOPHERJS_GOROOT"); ok {
return goroot
}
return build.Default.GOROOT
}()Functions
func DefaultEnv() Env
DefaultEnv creates a new instance of build Env according to environment variables.
By default, GopherJS will use GOOS=js GOARCH=ecmascript to build non-standard library packages. If GOOS or GOARCH environment variables are set and not empty, user-provided values will be used instead. This is done to facilitate transition from the legacy GopherJS behavior, which used native GOOS, and may be removed in future.
func Import(path string, mode build.ImportMode, installSuffix string, buildTags []string) (*PackageData, error)
Import returns details about the Go package named by the import path. 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 and .inc.js 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 nil *PackageData.
func ImportDir(dir string, mode build.ImportMode, installSuffix string, buildTags []string) (*PackageData, error)
ImportDir is like Import but processes the Go package found in the named directory.
func IsPkgNotFound(err error) bool
IsPkgNotFound returns true if the error was caused by package not found.
Unfortunately, go/build doesn't make use of typed errors, so we have to rely on the error message.
func NewBuildContext(installSuffix string, buildTags []string) XContext
NewBuildContext creates a build context for building Go packages with GopherJS compiler.
Core GopherJS packages (i.e., "github.com/gopherjs/gopherjs/js", "github.com/gopherjs/gopherjs/nosync") are loaded from gopherjspkg.FS virtual filesystem if not present in GOPATH or go.mod.
func NewSession(options *Options) (*Session, error)
NewSession creates a new GopherJS build session.
Types
type Env
Env contains build environment configuration required to define an instance of XContext.
type Env struct {
GOROOT string
GOPATH string
GOOS string
GOARCH string
BuildTags []string
InstallSuffix string
}Fields
GOROOT stringGOPATH stringGOOS stringGOARCH stringBuildTags []stringInstallSuffix string
type Options
Options controls build process behavior.
type Options struct {
Verbose bool
Quiet bool
Watch bool
CreateMapFile bool
MapToLocalDisk bool
Minify bool
Color bool
BuildTags []string
TestedPackage string
NoCache bool
}Fields
Verbose boolQuiet boolWatch boolCreateMapFile boolMapToLocalDisk boolMinify boolColor boolBuildTags []stringTestedPackage stringNoCache bool
func PrintError(format string, a ...any)
PrintError message to the terminal.
func PrintSuccess(format string, a ...any)
PrintSuccess message to the terminal.
type PackageData
PackageData is an extension of go/build.Package with additional metadata GopherJS requires.
type PackageData struct {
*build.Package
JSFiles []incjs.File
// IsTest is true if the package is being built for running tests.
IsTest bool
SrcModTime time.Time
UpToDate bool
// If true, the package does not have a corresponding physical directory on disk.
IsVirtual bool
// contains filtered or unexported fields
}Fields
*build.PackageJSFiles []incjs.FileIsTest boolIsTest is true if the package is being built for running tests.
SrcModTime time.TimeUpToDate boolIsVirtual boolIf true, the package does not have a corresponding physical directory on disk.
func FileModTime() time.Time
FileModTime returns the most recent modification time of the package's source files. This includes all .go and .inc.js that would be included in the build, but excludes any dependencies.
func InstallPath() (string, error)
InstallPath returns the path where "gopherjs install" command should place the generated output.
func InternalBuildContext() *build.Context
InternalBuildContext returns the build context that produced the package.
WARNING: This function is a part of internal API and will be removed in future.
func String() string
func TestPackage() *PackageData
TestPackage returns a variant of the package with "internal" tests.
func XTestPackage() *PackageData
XTestPackage returns a variant of the package with "external" tests.
type Session
Session manages internal state GopherJS requires to perform a build.
This is the main interface to GopherJS build system. Session lifetime is roughly equivalent to a single GopherJS tool invocation.
type Session struct {
// Binary archives produced during the current session and assumed to be
// up to date with input sources and dependencies. In the -w ("watch") mode
// must be cleared upon entering watching.
UpToDateArchives map[string]*compiler.Archive
Watcher *fsnotify.Watcher
// contains filtered or unexported fields
}Fields
UpToDateArchives map[string]*compiler.ArchiveBinary archives produced during the current session and assumed to be up to date with input sources and dependencies. In the -w ("watch") mode must be cleared upon entering watching.
Watcher *fsnotify.Watcher
func BuildFiles(filenames []string, pkgObj string, cwd string) error
BuildFiles passed to the GopherJS tool as if they were a package.
A ephemeral package will be created with only the provided files. This
function is intended for use with, for example, gopherjs run main.go.
func BuildProject(pkg *PackageData) (*compiler.Archive, error)
BuildProject builds a command project (one with a main method) or builds a test project (one with a synthesized test main package).
func EnableMapping(filter *sourcemapx.Filter, jsFileName string)
SourceMappingCallback returns a callback for [github.com/gopherjs/gopherjs/compiler.SourceMapFilter] configured for the current build session.
func GetSortedSources() []*sources.Sources
GetSortedSources returns the sources sorted by import path. The files in the sources may still not be sorted yet.
func GoRelease() string
GoRelease returns Go release version this session is building with.
func ImportResolverFor(srcDir string) func(string) (*compiler.Archive, error)
ImportResolverFor returns a function which returns a compiled package archive given an import path.
func InstallSuffix() string
InstallSuffix returns the suffix added to the generated output file.
func LoadPackages(pkg *PackageData) (*sources.Sources, error)
LoadPackages will recursively load and parse the given package and its dependencies. This will return the sources for the given package. The returned source and sources for the dependencies will be added to the session's sources map.
func SourcesForImport(path, srcDir string) (*sources.Sources, error)
func TestBinary() string
TestBinary returns the testBinary value that is normally passed into
cmd/link by a -X option. The testBinary value is defined in the STL at
testing/testing.go for the testing.Testing() bool function.
It is set to "1" if the binary (the JS output in our case) is built
with "go test" and "0" otherwise.
func WaitForChange()
WaitForChange watches file system events and returns if either when one of the source files is modified.
func WriteCommandPackage(archive *compiler.Archive, pkgObj string) error
WriteCommandPackage writes the final JavaScript output file at pkgObj path.
func XContext() XContext
XContext returns the session's build context.
type XContext
XContext is an extension of go/build.Context with GopherJS-specific features.
It abstracts away several different sources GopherJS can load its packages from, with a minimal API.
type XContext interface {
// Import returns details about the Go package named by the importPath,
// interpreting local import paths relative to the srcDir directory.
Import(path string, srcDir string, mode build.ImportMode) (*PackageData, error)
// Env returns build environment configuration this context has been set up for.
Env() Env
// Match explans build patterns into a set of matching import paths (see go help packages).
Match(patterns []string) ([]string, error)
}Methods
Import func(path string, srcDir string, mode build.ImportMode) (*PackageData, error)Import returns details about the Go package named by the importPath, interpreting local import paths relative to the srcDir directory.
Env func() EnvEnv returns build environment configuration this context has been set up for.
Match func(patterns []string) ([]string, error)Match explans build patterns into a set of matching import paths (see go help packages).
