build

Documentation

Overview

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.

Index

• Variables
• func IsPkgNotFound(err error) bool
• func NewMappingCallback(m *sourcemap.Map, goroot, gopath string, localMap bool) func(generatedLine, generatedColumn int, originalPos token.Position)
• type Env
  • func DefaultEnv() Env
• type JSFile
• type Options
  • func (o *Options) PrintError(format string, a ...interface{})
  • func (o *Options) PrintSuccess(format string, a ...interface{})
• type PackageData
  • func Import(path string, mode build.ImportMode, installSuffix string, buildTags []string) (*PackageData, error)
  • func ImportDir(dir string, mode build.ImportMode, installSuffix string, buildTags []string) (*PackageData, error)
  • func (p PackageData) FileModTime() time.Time
  • func (p *PackageData) InstallPath() string
  • func (p *PackageData) InternalBuildContext() *build.Context
  • func (p PackageData) String() string
  • func (p *PackageData) TestPackage() *PackageData
  • func (p *PackageData) XTestPackage() *PackageData
• type Session
  • func NewSession(options *Options) (*Session, error)
  • func (s *Session) BuildFiles(filenames []string, pkgObj string, cwd string) error
  • func (s *Session) BuildImportPath(path string) (*compiler.Archive, error)
  • func (s *Session) BuildPackage(pkg *PackageData) (*compiler.Archive, error)
  • func (s *Session) GoRelease() string
  • func (s *Session) ImportResolverFor(pkg *PackageData) func(string) (*compiler.Archive, error)
  • func (s *Session) InstallSuffix() string
  • func (s *Session) SourceMappingCallback(m *sourcemap.Map) func(generatedLine, generatedColumn int, originalPos token.Position)
  • func (s *Session) WaitForChange()
  • func (s *Session) WriteCommandPackage(archive *compiler.Archive, pkgObj string) error
  • func (s *Session) XContext() XContext
• type XContext
  • func NewBuildContext(installSuffix string, buildTags []string) XContext

Variables

var DefaultGOROOT = func() string {
	if goroot, ok := os.LookupEnv("GOPHERJS_GOROOT"); ok {

		return goroot
	}

	return build.Default.GOROOT
}()

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.

Functions

func IsPkgNotFound

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 NewMappingCallback

func NewMappingCallback(m *sourcemap.Map, goroot, gopath string, localMap bool) func(generatedLine, generatedColumn int, originalPos token.Position)

NewMappingCallback creates a new callback for source map generation.

Types

type Env

type Env struct {
	GOROOT string
	GOPATH string

	GOOS   string
	GOARCH string

	BuildTags     []string
	InstallSuffix string
}

Env contains build environment configuration required to define an instance of XContext.

func DefaultEnv

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.

type JSFile

type JSFile struct {
	Path    string // Full file path for the build context the file came from.
	ModTime time.Time
	Content []byte
}

JSFile represents a *.inc.js file metadata and content.

type Options

type Options struct {
	Verbose        bool
	Quiet          bool
	Watch          bool
	CreateMapFile  bool
	MapToLocalDisk bool
	Minify         bool
	Color          bool
	BuildTags      []string
	TestedPackage  string
	NoCache        bool
}

Options controls build process behavior.

func (*Options) PrintError

func (o *Options) PrintError(format string, a ...interface{})

PrintError message to the terminal.

func (*Options) PrintSuccess

func (o *Options) PrintSuccess(format string, a ...interface{})

PrintSuccess message to the terminal.

type PackageData

type PackageData struct {
	*build.Package
	JSFiles []JSFile
	// 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
}

PackageData is an extension of go/build.Package with additional metadata GopherJS requires.

func Import

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

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 (PackageData) FileModTime

func (p PackageData) 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 (*PackageData) InstallPath

func (p *PackageData) InstallPath() string

InstallPath returns the path where "gopherjs install" command should place the generated output.

func (*PackageData) InternalBuildContext

func (p *PackageData) 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 (PackageData) String

func (p PackageData) String() string

func (*PackageData) TestPackage

func (p *PackageData) TestPackage() *PackageData

TestPackage returns a variant of the package with "internal" tests.

func (*PackageData) XTestPackage

func (p *PackageData) XTestPackage() *PackageData

XTestPackage returns a variant of the package with "external" tests.

type Session

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
	Types            map[string]*types.Package
	Watcher          *fsnotify.Watcher
	// contains filtered or unexported fields
}

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.

func NewSession

func NewSession(options *Options) (*Session, error)

NewSession creates a new GopherJS build session.

func (*Session) BuildFiles

func (s *Session) 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 (*Session) BuildImportPath

func (s *Session) BuildImportPath(path string) (*compiler.Archive, error)

BuildImportPath loads and compiles package with the given import path.

Relative paths are interpreted relative to the current working dir.

func (*Session) BuildPackage

func (s *Session) BuildPackage(pkg *PackageData) (*compiler.Archive, error)

BuildPackage compiles an already loaded package.

func (*Session) GoRelease

func (s *Session) GoRelease() string

GoRelease returns Go release version this session is building with.

func (*Session) ImportResolverFor

func (s *Session) ImportResolverFor(pkg *PackageData) func(string) (*compiler.Archive, error)

ImportResolverFor returns a function which returns a compiled package archive given an import path.

func (*Session) InstallSuffix

func (s *Session) InstallSuffix() string

InstallSuffix returns the suffix added to the generated output file.

func (*Session) SourceMappingCallback

func (s *Session) SourceMappingCallback(m *sourcemap.Map) func(generatedLine, generatedColumn int, originalPos token.Position)

SourceMappingCallback returns a call back for compiler.SourceMapFilter configured for the current build session.

func (*Session) WaitForChange

func (s *Session) WaitForChange()

WaitForChange watches file system events and returns if either when one of the source files is modified.

func (*Session) WriteCommandPackage

func (s *Session) WriteCommandPackage(archive *compiler.Archive, pkgObj string) error

WriteCommandPackage writes the final JavaScript output file at pkgObj path.

func (*Session) XContext

func (s *Session) XContext() XContext

XContext returns the session's build context.

type XContext

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)
}

XContext is an extension of go/build.Context with GopherJS-specifc features.

It abstracts away several different sources GopherJS can load its packages from, with a minimal API.

func NewBuildContext

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.