compiler

Documentation

Overview

Package compiler implements GopherJS compiler logic.

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

• Constants
• func CheckGoVersion(goroot string) error
• func ErrorAt(err error, fset *token.FileSet, pos token.Pos) error
• func GoRelease(goroot string) string
• func WriteArchive(a *Archive, w io.Writer) error
• func WritePkgCode(pkg *Archive, dceSelection map[*Decl]struct{}, gls goLinknameSet, minify bool, ...) error
• func WriteProgramCode(pkgs []*Archive, w *SourceMapFilter, goVersion string) error
• type Archive
  • func Compile(importPath string, files []*ast.File, fileSet *token.FileSet, ...) (_ *Archive, err error)
  • func ImportDependencies(archive *Archive, importPkg func(string) (*Archive, error)) ([]*Archive, error)
  • func ReadArchive(path string, r io.Reader) (*Archive, error)
  • func (a *Archive) RegisterTypes(packages map[string]*types.Package) error
  • func (a Archive) String() string
• type Decl
• type Dependency
• type ErrorList
  • func (err ErrorList) Error() string
  • func (err ErrorList) Normalize() error
• type FatalError
  • func (b FatalError) Error() string
  • func (b FatalError) Unwrap() error
  • func (b *FatalError) Write(p []byte) (n int, err error)
• type GoLinkname
• type ImportContext
• type SourceMapFilter
  • func (f *SourceMapFilter) Write(p []byte) (n int, err error)
• type SymName
  • func (n SymName) String() string

Constants

const GoVersion = 18

GoVersion is the current Go 1.x version that GopherJS is compatible with.

const Version = "1.18.0+go1.18.4"

Version is the GopherJS compiler version string.

Functions

func CheckGoVersion

func CheckGoVersion(goroot string) error

CheckGoVersion checks the version of the Go distribution at goroot, and reports an error if it's not compatible with this version of the GopherJS compiler.

func ErrorAt

func ErrorAt(err error, fset *token.FileSet, pos token.Pos) error

ErrorAt annotates an error with a position in the source code.

func GoRelease

func GoRelease(goroot string) string

GoRelease does a best-effort to identify Go release we are building with. If unable to determin the precise version for the given GOROOT, falls back to the best guess available.

func WriteArchive

func WriteArchive(a *Archive, w io.Writer) error

WriteArchive writes compiled package archive on disk for later reuse.

func WritePkgCode

func WritePkgCode(pkg *Archive, dceSelection map[*Decl]struct{}, gls goLinknameSet, minify bool, w *SourceMapFilter) error

func WriteProgramCode

func WriteProgramCode(pkgs []*Archive, w *SourceMapFilter, goVersion string) error

Types

type Archive

type Archive struct {
	// Package's full import path, e.g. "some/package/name".
	ImportPath string
	// Package's name as per "package" statement at the top of a source file.
	// Usually matches the last component of import path, but may differ in
	// certain cases (e.g. main or test packages).
	Name string
	// A list of full package import paths that the current package imports across
	// all source files. See go/types.Package.Imports().
	Imports []string
	// Serialized contents of go/types.Package in a binary format. This information
	// is used by the compiler to type-check packages that import this one. See
	// gcexportdata.Write().
	//
	// TODO(nevkontakte): It would be more convenient to store go/types.Package
	// itself and only serialize it when writing the archive onto disk.
	ExportData []byte
	// Compiled package-level symbols.
	Declarations []*Decl
	// Concatenated contents of all raw .inc.js of the package.
	IncJSCode []byte
	// JSON-serialized contents of go/token.FileSet. This is used to obtain source
	// code locations for various symbols (e.g. for sourcemap generation). See
	// token.FileSet.Write().
	//
	// TODO(nevkontakte): This is also more convenient to store as the original
	// object and only serialize before writing onto disk.
	FileSet []byte
	// Whether or not the package was compiled with minification enabled.
	Minified bool
	// A list of go:linkname directives encountered in the package.
	GoLinknames []GoLinkname
	// Time when this archive was built.
	BuildTime time.Time
}

Archive contains intermediate build outputs of a single package.

This is a logical equivalent of an object file in traditional compilers.

func Compile

func Compile(importPath string, files []*ast.File, fileSet *token.FileSet, importContext *ImportContext, minify bool) (_ *Archive, err error)

func ImportDependencies

func ImportDependencies(archive *Archive, importPkg func(string) (*Archive, error)) ([]*Archive, error)

func ReadArchive

func ReadArchive(path string, r io.Reader) (*Archive, error)

ReadArchive reads serialized compiled archive of the importPath package.

func (*Archive) RegisterTypes

func (a *Archive) RegisterTypes(packages map[string]*types.Package) error

RegisterTypes adds package type information from the archive into the provided map.

func (Archive) String

func (a Archive) String() string

type Decl

type Decl struct {
	// The package- or receiver-type-qualified name of function or method obj.
	// See go/types.Func.FullName().
	FullName string
	// A logical equivalent of a symbol name in an object file in the traditional
	// Go compiler/linker toolchain. Used by GopherJS to support go:linkname
	// directives. Must be set for decls that are supported by go:linkname
	// implementation.
	LinkingName SymName
	// A list of package-level JavaScript variable names this symbol needs to declare.
	Vars []string
	// JavaScript code that declares basic information about a symbol. For a type
	// it configures basic information about the type and its identity. For a function
	// or method it contains its compiled body.
	DeclCode []byte
	// JavaScript code that initializes reflection metadata about type's method list.
	MethodListCode []byte
	// JavaScript code that initializes the rest of reflection metadata about a type
	// (e.g. struct fields, array type sizes, element types, etc.).
	TypeInitCode []byte
	// JavaScript code that needs to be executed during the package init phase to
	// set the symbol up (e.g. initialize package-level variable value).
	InitCode []byte
	// Symbol's identifier used by the dead-code elimination logic, not including
	// package path. If empty, the symbol is assumed to be alive and will not be
	// eliminated. For methods it is the same as its receiver type identifier.
	DceObjectFilter string
	// The second part of the identified used by dead-code elimination for methods.
	// Empty for other types of symbols.
	DceMethodFilter string
	// List of fully qualified (including package path) DCE symbol identifiers the
	// symbol depends on for dead code elimination purposes.
	DceDeps []string
	// Set to true if a function performs a blocking operation (I/O or
	// synchronization). The compiler will have to generate function code such
	// that it can be resumed after a blocking operation completes without
	// blocking the main thread in the meantime.
	Blocking bool
}

Decl represents a package-level symbol (e.g. a function, variable or type).

It contains code generated by the compiler for this specific symbol, which is grouped by the execution stage it belongs to in the JavaScript runtime.

type Dependency

type Dependency struct {
	Pkg    string
	Type   string
	Method string
}

type ErrorList

type ErrorList []error

func (ErrorList) Error

func (err ErrorList) Error() string

func (ErrorList) Normalize

func (err ErrorList) Normalize() error

type FatalError

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

FatalError is an error compiler panics with when it encountered a fatal error.

FatalError implements io.Writer, which can be used to record any free-form debugging details for human consumption. This information will be included into String() result along with the rest.

func (FatalError) Error

func (b FatalError) Error() string

func (FatalError) Unwrap

func (b FatalError) Unwrap() error

func (*FatalError) Write

func (b *FatalError) Write(p []byte) (n int, err error)

Write implements io.Writer and can be used to store free-form debugging clues.

type GoLinkname

type GoLinkname struct {
	Implementation SymName
	Reference      SymName
}

GoLinkname describes a go:linkname compiler directive found in the source code.

GopherJS treats these directives in a way that resembles a symbolic link, where for a single given symbol implementation there may be zero or more symbols referencing it. This is subtly different from the upstream Go implementation, which simply overrides symbol name the linker will use.

type ImportContext

type ImportContext struct {
	Packages map[string]*types.Package
	Import   func(string) (*Archive, error)
}

type SourceMapFilter

type SourceMapFilter struct {
	Writer          io.Writer
	MappingCallback func(generatedLine, generatedColumn int, originalPos token.Position)
	// contains filtered or unexported fields
}

func (*SourceMapFilter) Write

func (f *SourceMapFilter) Write(p []byte) (n int, err error)

type SymName

type SymName struct {
	PkgPath string // Full package import path.
	Name    string // Symbol name.
}

SymName uniquely identifies a named submol within a program.

This is a logical equivalent of a symbol name used by traditional linkers. The following properties should hold true:

• Each named symbol within a program has a unique SymName.
• Similarly named methods of different types will have different symbol names.
• The string representation is opaque and should not be attempted to reversed to a struct form.

func (SymName) String

func (n SymName) String() string