gcimporter

Documentation

Overview

Package gcimporter provides various functions for reading gc-generated object files that can be used to implement the Importer interface defined by the Go 1.5 standard library package.

The encoding is deterministic: if the encoder is applied twice to the same types.Package data structure, both encodings are equal. This property may be important to avoid spurious changes in applications such as build systems.

However, the encoder is not necessarily idempotent. Importing an exported package may yield a types.Package that, while it represents the same set of Go types as the original, may differ in the details of its internal representation. Because of these differences, re-encoding the imported package may yield a different, but equally valid, encoding of the package.

Index

• func BExportData(fset *token.FileSet, pkg *types.Package) (b []byte, err error)
• func BImportData(fset *token.FileSet, imports map[string]*types.Package, data []byte, ...) (_ int, pkg *types.Package, err error)
• func FindExportData(r *bufio.Reader) (hdr string, size int64, err error)
• func FindPkg(path, srcDir string) (filename, id string)
• func IExportBundle(out io.Writer, fset *token.FileSet, pkgs []*types.Package) error
• func IExportData(out io.Writer, fset *token.FileSet, pkg *types.Package) error
• func IExportShallow(fset *token.FileSet, pkg *types.Package) ([]byte, error)
• func IImportBundle(fset *token.FileSet, imports map[string]*types.Package, data []byte) ([]*types.Package, error)
• func IImportData(fset *token.FileSet, imports map[string]*types.Package, data []byte, ...) (int, *types.Package, error)
• func IImportShallow(fset *token.FileSet, getPackage GetPackageFunc, data []byte, path string, ...) (*types.Package, error)
• func Import(packages map[string]*types.Package, path, srcDir string, ...) (pkg *types.Package, err error)
• func UImportData(fset *token.FileSet, imports map[string]*types.Package, data []byte, ...) (_ int, pkg *types.Package, err error)
• type GetPackageFunc
  • func GetPackageFromMap(m map[string]*types.Package) GetPackageFunc
• type InsertType

Functions

func BExportData

func BExportData(fset *token.FileSet, pkg *types.Package) (b []byte, err error)

BExportData returns binary export data for pkg. If no file set is provided, position info will be missing.

func BImportData

func BImportData(fset *token.FileSet, imports map[string]*types.Package, data []byte, path string) (_ int, pkg *types.Package, err error)

BImportData imports a package from the serialized package data and returns the number of bytes consumed and a reference to the package. If the export data version is not recognized or the format is otherwise compromised, an error is returned.

func FindExportData

func FindExportData(r *bufio.Reader) (hdr string, size int64, err error)

FindExportData positions the reader r at the beginning of the export data section of an underlying GC-created object/archive file by reading from it. The reader must be positioned at the start of the file before calling this function. The hdr result is the string before the export data, either "$$" or "$$B". The size result is the length of the export data in bytes, or -1 if not known.

func FindPkg

func FindPkg(path, srcDir string) (filename, id string)

FindPkg returns the filename and unique package id for an import path based on package information provided by build.Import (using the build.Default build.Context). A relative srcDir is interpreted relative to the current working directory. If no file was found, an empty filename is returned.

func IExportBundle

func IExportBundle(out io.Writer, fset *token.FileSet, pkgs []*types.Package) error

IExportBundle writes an indexed export bundle for pkgs to out.

func IExportData

func IExportData(out io.Writer, fset *token.FileSet, pkg *types.Package) error

IExportData writes indexed export data for pkg to out.

If no file set is provided, position info will be missing. The package path of the top-level package will not be recorded, so that calls to IImportData can override with a provided package path.

func IExportShallow

func IExportShallow(fset *token.FileSet, pkg *types.Package) ([]byte, error)

IExportShallow encodes "shallow" export data for the specified package.

No promises are made about the encoding other than that it can be decoded by the same version of IIExportShallow. If you plan to save export data in the file system, be sure to include a cryptographic digest of the executable in the key to avoid version skew.

func IImportBundle

func IImportBundle(fset *token.FileSet, imports map[string]*types.Package, data []byte) ([]*types.Package, error)

IImportBundle imports a set of packages from the serialized package bundle.

func IImportData

func IImportData(fset *token.FileSet, imports map[string]*types.Package, data []byte, path string) (int, *types.Package, error)

IImportData imports a package from the serialized package data and returns 0 and a reference to the package. If the export data version is not recognized or the format is otherwise compromised, an error is returned.

func IImportShallow

func IImportShallow(fset *token.FileSet, getPackage GetPackageFunc, data []byte, path string, insert InsertType) (*types.Package, error)

IImportShallow decodes "shallow" types.Package data encoded by IExportShallow in the same executable. This function cannot import data from cmd/compile or gcexportdata.Write.

func Import

func Import(packages map[string]*types.Package, path, srcDir string, lookup func(path string) (io.ReadCloser, error)) (pkg *types.Package, err error)

Import imports a gc-generated package given its import path and srcDir, adds the corresponding package object to the packages map, and returns the object. The packages map must contain all packages already imported.

func UImportData

func UImportData(fset *token.FileSet, imports map[string]*types.Package, data []byte, path string) (_ int, pkg *types.Package, err error)

Types

type GetPackageFunc

type GetPackageFunc = func(path, name string) *types.Package

A GetPackageFunc is a function that gets the package with the given path from the importer state, creating it (with the specified name) if necessary. It is an abstraction of the map historically used to memoize package creation.

Two calls with the same path must return the same package.

If the given getPackage func returns nil, the import will fail.

func GetPackageFromMap

func GetPackageFromMap(m map[string]*types.Package) GetPackageFunc

GetPackageFromMap returns a GetPackageFunc that retrieves packages from the given map of package path -> package.

The resulting func may mutate m: if a requested package is not found, a new package will be inserted into m.

type InsertType

type InsertType = func(pkg *types.Package, name string)

InsertType is the type of a function that creates a types.TypeName object for a named type and inserts it into the scope of the specified Package.