Package gcexportdata
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.
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://golang.org/issue/15651.)
- 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, path string) (*types.Package, error)
- func ReadBundle(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
- func WriteBundle(out io.Writer, fset *token.FileSet, pkgs []*types.Package) error
Package files
gcexportdata.go
importer.go
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 go command.
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.
Deprecated: Use the higher-level API in golang.org/x/tools/go/packages,
which is more efficient.
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.
Deprecated: Use the higher-level API in golang.org/x/tools/go/packages,
which is more efficient.
▾ Example
ExampleNewImporter demonstrates usage of NewImporter to provide type
information for dependencies when type-checking Go source code.
Code:
const src = `package myrpc
// choosing a package that doesn't change across releases
import "net/rpc"
const serverError rpc.ServerError = ""
`
fset := token.NewFileSet()
f, err := parser.ParseFile(fset, "myrpc.go", src, 0)
if err != nil {
log.Fatal(err)
}
packages := make(map[string]*types.Package)
imp := gcexportdata.NewImporter(fset, packages)
conf := types.Config{Importer: imp}
pkg, err := conf.Check("myrpc", fset, []*ast.File{f}, nil)
if err != nil {
log.Fatal(err)
}
pi := packages["net/rpc"].Scope().Lookup("ServerError")
fmt.Printf("type %s.%s %s // %s\n",
pi.Pkg().Path(),
pi.Name(),
pi.Type().Underlying(),
slashify(fset.Position(pi.Pos())),
)
twopi := pkg.Scope().Lookup("serverError")
fmt.Printf("const %s %s = %s // %s\n",
twopi.Name(),
twopi.Type(),
twopi.(*types.Const).Val(),
slashify(fset.Position(twopi.Pos())),
)
Output:
type net/rpc.ServerError string // $GOROOT/src/net/rpc/client.go:20:1
const serverError net/rpc.ServerError = "" // myrpc.go:6:7
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(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 path (effectively its linker symbol prefix) is
specified by path, since unlike the package name, this information
may not be recorded in the export data.
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.
▾ Example
ExampleRead uses gcexportdata.Read to load type information for the
"fmt" package from the fmt.a file produced by the gc compiler.
Code:
filename, path := gcexportdata.Find("fmt", "")
if filename == "" {
log.Fatalf("can't find export data for fmt")
}
fmt.Printf("Package path: %s\n", path)
f, err := os.Open(filename)
if err != nil {
log.Fatal(err)
}
defer f.Close()
r, err := gcexportdata.NewReader(f)
if err != nil {
log.Fatalf("reading export data %s: %v", filename, err)
}
fset := token.NewFileSet()
imports := make(map[string]*types.Package)
pkg, err := gcexportdata.Read(r, fset, imports, path)
if err != nil {
log.Fatal(err)
}
members := pkg.Scope().Names()
foundPrintln := false
for _, member := range members {
if member == "Println" {
foundPrintln = true
break
}
}
fmt.Print("Package members: ")
if foundPrintln {
fmt.Println("Println found")
} else {
fmt.Println("Println not found")
}
println := pkg.Scope().Lookup("Println")
typ := strings.ReplaceAll(println.Type().String(), "interface{}", "any")
fmt.Printf("Println type: %s\n", typ)
posn := fset.Position(println.Pos())
posn.Line = 123
fmt.Printf("Println location: %s\n", slashify(posn))
Output:
Package path: fmt
Package members: Println found
Println type: func(a ...any) (n int, err error)
Println location: $GOROOT/src/fmt/print.go:123:1
func ReadBundle(in io.Reader, fset *token.FileSet, imports map[string]*types.Package) ([]*types.Package, error)
ReadBundle reads an export bundle from in, decodes it, and returns type
information for the packages.
File position information is added to fset.
ReadBundle may inspect and add to the imports map to ensure that references
within the export bundle to other packages are consistent.
On return, the state of the reader is undefined.
Experimental: This API is experimental and may change in the future.
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.
func WriteBundle(out io.Writer, fset *token.FileSet, pkgs []*types.Package) error
WriteBundle writes encoded type information for the specified packages to out.
The FileSet provides file position information for named objects.
Experimental: This API is experimental and may change in the future.