gcexportdata

Documentation

Overview

Package gcexportdata provides functions for locating, reading, and writing export data files containing type information produced by the gc compiler. This package supports go1.7 export data format and all later versions.

This package replaces the deprecated golang.org/x/tools/go/gcimporter15 package, which will be deleted in October 2017.

Although it might seem convenient for this package to live alongside go/types in the standard library, this would cause version skew problems for developer tools that use it, since they must be able to consume the outputs of the gc compiler both before and after a Go update such as from Go 1.7 to Go 1.8. Because this package lives in golang.org/x/tools, sites can update their version of this repo some time before the Go 1.8 release and rebuild and redeploy their developer tools, which will then be able to consume both Go 1.7 and Go 1.8 export data files, so they will work before and after the Go update. (See discussion at https://github.com/golang/go/issues/15651.)

Index

• func Find(importPath, srcDir string) (filename, path string)
• func NewImporter(fset *token.FileSet, imports map[string]*types.Package) types.ImporterFrom
• func NewReader(r io.Reader) (io.Reader, error)
• func Read(in io.Reader, fset *token.FileSet, imports map[string]*types.Package, ...) (*types.Package, error)
• func Write(out io.Writer, fset *token.FileSet, pkg *types.Package) error

Functions

func Find

func Find(importPath, srcDir string) (filename, path string)

Find returns the name of an object (.o) or archive (.a) file containing type information for the specified import path, using the workspace layout conventions of go/build. If no file was found, an empty filename is returned.

A relative srcDir is interpreted relative to the current working directory.

Find also returns the package's resolved (canonical) import path, reflecting the effects of srcDir and vendoring on importPath.

func NewImporter

func NewImporter(fset *token.FileSet, imports map[string]*types.Package) types.ImporterFrom

NewImporter returns a new instance of the types.Importer interface that reads type information from export data files written by gc. The Importer also satisfies types.ImporterFrom.

Export data files are located using "go build" workspace conventions and the build.Default context.

Use this importer instead of go/importer.For("gc", ...) to avoid the version-skew problems described in the documentation of this package, or to control the FileSet or access the imports map populated during package loading.

func NewReader

func NewReader(r io.Reader) (io.Reader, error)

NewReader returns a reader for the export data section of an object (.o) or archive (.a) file read from r. The new reader may provide additional trailing data beyond the end of the export data.

func Read

func Read(in io.Reader, fset *token.FileSet, imports map[string]*types.Package, path string) (*types.Package, error)

Read reads export data from in, decodes it, and returns type information for the package. The package name is specified by path. File position information is added to fset.

Read may inspect and add to the imports map to ensure that references within the export data to other packages are consistent. The caller must ensure that imports[path] does not exist, or exists but is incomplete (see types.Package.Complete), and Read inserts the resulting package into this map entry.

On return, the state of the reader is undefined.

func Write

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

Write writes encoded type information for the specified package to out. The FileSet provides file position information for named objects.