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 ImportCError
  • func (e *ImportCError) Error() string
• 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) InstallPath() string
  • func (p *PackageData) InternalBuildContext() *build.Context
  • 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, packagePath 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) 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 ImportCError

type ImportCError struct {
	// contains filtered or unexported fields
}

ImportCError is returned when GopherJS attempts to build a package that uses CGo.

func (*ImportCError) Error

func (e *ImportCError) Error() string

type Options

type Options struct {
	GOROOT         string
	GOPATH         string
	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 []string
	// 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) 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) 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, packagePath 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) 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)

	// GOOS returns GOOS value the underlying build.Context is using.
	// This will become obsolete after https://github.com/gopherjs/gopherjs/issues/693.
	GOOS() string

	// 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.