go/gcexportdata/gcexportdata.go - tools - Git at Google

 // Copyright 2016 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 // Package gcexportdata provides functions for reading and writing
 // export data, which is a serialized description of the API of a Go
 // package including the names, kinds, types, and locations of all
 // exported declarations.
 //
 // The standard Go compiler (cmd/compile) writes an export data file
 // for each package it compiles, which it later reads when compiling
 // packages that import the earlier one. The compiler must thus
 // contain logic to both write and read export data.
 // (See the "Export" section in the cmd/compile/README file.)
 //
 // The [Read] function in this package can read files produced by the
 // compiler, producing [go/types] data structures. As a matter of
 // policy, Read supports export data files produced by only the last
 // two Go releases plus tip; see https://go.dev/issue/68898. The
 // export data files produced by the compiler contain additional
 // details related to generics, inlining, and other optimizations that
 // cannot be decoded by the [Read] function.
 //
 // In files written by the compiler, the export data is not at the
 // start of the file. Before calling Read, use [NewReader] to locate
 // the desired portion of the file.
 //
 // The [Write] function in this package encodes the exported API of a
 // Go package ([types.Package]) as a file. Such files can be later
 // decoded by Read, but cannot be consumed by the compiler.
 //
 // # Future changes
 //
 // Although Read supports the formats written by both Write and the
 // compiler, the two are quite different, and there is an open
 // proposal (https://go.dev/issue/69491) to separate these APIs.
 //
 // Under that proposal, this package would ultimately provide only the
 // Read operation for compiler export data, which must be defined in
 // this module (golang.org/x/tools), not in the standard library, to
 // avoid version skew for developer tools that need to read compiler
 // export data both before and after a Go release, such as from Go
 // 1.23 to Go 1.24. Because this package lives in the tools module,
 // clients can update their version of the module some time before the
 // Go 1.24 release and rebuild and redeploy their tools, which will
 // then be able to consume both Go 1.23 and Go 1.24 export data files,
 // so they will work before and after the Go update. (See discussion
 // at https://go.dev/issue/15651.)
 //
 // The operations to import and export [go/types] data structures
 // would be defined in the go/types package as Import and Export.
 // [Write] would (eventually) delegate to Export,
 // and [Read], when it detects a file produced by Export,
 // would delegate to Import.
 //
 // # Deprecations
 //
 // The [NewImporter] and [Find] functions are deprecated and should
 // not be used in new code. The [WriteBundle] and [ReadBundle]
 // functions are experimental, and there is an open proposal to
 // deprecate them (https://go.dev/issue/69573).
 package gcexportdata

 import (
 	"bufio"
 	"bytes"
 	"encoding/json"
 	"fmt"
 	"go/token"
 	"go/types"
 	"io"
 	"os/exec"

 	"golang.org/x/tools/internal/gcimporter"
 )

 // 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 Find(importPath, srcDir string) (filename, path string) {
 	cmd := exec.Command("go", "list", "-json", "-export", "--", importPath)
 	cmd.Dir = srcDir
 	out, err := cmd.Output()
 	if err != nil {
 		return "", ""
 	}
 	var data struct {
 		ImportPath string
 		Export     string
 	}
 	json.Unmarshal(out, &data)
 	return data.Export, data.ImportPath
 }

 // 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 NewReader(r io.Reader) (io.Reader, error) {
 	buf := bufio.NewReader(r)
 	size, err := gcimporter.FindExportData(buf)
 	if err != nil {
 		return nil, err
 	}

 	// We were given an archive and found the __.PKGDEF in it.
 	// This tells us the size of the export data, and we don't
 	// need to return the entire file.
 	return &io.LimitedReader{
 		R: buf,
 		N: size,
 	}, nil
 }

 // readAll works the same way as io.ReadAll, but avoids allocations and copies
 // by preallocating a byte slice of the necessary size if the size is known up
 // front. This is always possible when the input is an archive. In that case,
 // NewReader will return the known size using an io.LimitedReader.
 func readAll(r io.Reader) ([]byte, error) {
 	if lr, ok := r.(*io.LimitedReader); ok {
 		data := make([]byte, lr.N)
 		_, err := io.ReadFull(lr, data)
 		return data, err
 	}
 	return io.ReadAll(r)
 }

 // Read reads export data from in, decodes it, and returns type
 // information for the package.
 //
 // Read is capable of reading export data produced by [Write] at the
 // same source code version, or by the last two Go releases (plus tip)
 // of the standard Go compiler. Reading files from older compilers may
 // produce an error.
 //
 // 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.
 func Read(in io.Reader, fset *token.FileSet, imports map[string]*types.Package, path string) (*types.Package, error) {
 	data, err := readAll(in)
 	if err != nil {
 		return nil, fmt.Errorf("reading export data for %q: %v", path, err)
 	}

 	if bytes.HasPrefix(data, []byte("!<arch>")) {
 		return nil, fmt.Errorf("can't read export data for %q directly from an archive file (call gcexportdata.NewReader first to extract export data)", path)
 	}

 	// The indexed export format starts with an 'i'; the older
 	// binary export format starts with a 'c', 'd', or 'v'
 	// (from "version"). Select appropriate importer.
 	if len(data) > 0 {
 		switch data[0] {
 		case 'v', 'c', 'd':
 			// binary, produced by cmd/compile till go1.10
 			return nil, fmt.Errorf("binary (%c) import format is no longer supported", data[0])

 		case 'i':
 			// indexed, produced by cmd/compile till go1.19,
 			// and also by [Write].
 			//
 			// If proposal #69491 is accepted, go/types
 			// serialization will be implemented by
 			// types.Export, to which Write would eventually
 			// delegate (explicitly dropping any pretence at
 			// inter-version Write-Read compatibility).
 			// This [Read] function would delegate to types.Import
 			// when it detects that the file was produced by Export.
 			_, pkg, err := gcimporter.IImportData(fset, imports, data[1:], path)
 			return pkg, err

 		case 'u':
 			// unified, produced by cmd/compile since go1.20
 			_, pkg, err := gcimporter.UImportData(fset, imports, data[1:], path)
 			return pkg, err

 		default:
 			l := len(data)
 			if l > 10 {
 				l = 10
 			}
 			return nil, fmt.Errorf("unexpected export data with prefix %q for path %s", string(data[:l]), path)
 		}
 	}
 	return nil, fmt.Errorf("empty export data for %s", path)
 }

 // Write writes encoded type information for the specified package to out.
 // The FileSet provides file position information for named objects.
 func Write(out io.Writer, fset *token.FileSet, pkg *types.Package) error {
 	if _, err := io.WriteString(out, "i"); err != nil {
 		return err
 	}
 	return gcimporter.IExportData(out, fset, pkg)
 }

 // 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 ReadBundle(in io.Reader, fset *token.FileSet, imports map[string]*types.Package) ([]*types.Package, error) {
 	data, err := readAll(in)
 	if err != nil {
 		return nil, fmt.Errorf("reading export bundle: %v", err)
 	}
 	return gcimporter.IImportBundle(fset, imports, data)
 }

 // 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.
 func WriteBundle(out io.Writer, fset *token.FileSet, pkgs []*types.Package) error {
 	return gcimporter.IExportBundle(out, fset, pkgs)
 }
	// Copyright 2016 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	// Package gcexportdata provides functions for reading and writing
	// export data, which is a serialized description of the API of a Go
	// package including the names, kinds, types, and locations of all
	// exported declarations.
	//
	// The standard Go compiler (cmd/compile) writes an export data file
	// for each package it compiles, which it later reads when compiling
	// packages that import the earlier one. The compiler must thus
	// contain logic to both write and read export data.
	// (See the "Export" section in the cmd/compile/README file.)
	//
	// The [Read] function in this package can read files produced by the
	// compiler, producing [go/types] data structures. As a matter of
	// policy, Read supports export data files produced by only the last
	// two Go releases plus tip; see https://go.dev/issue/68898. The
	// export data files produced by the compiler contain additional
	// details related to generics, inlining, and other optimizations that
	// cannot be decoded by the [Read] function.
	//
	// In files written by the compiler, the export data is not at the
	// start of the file. Before calling Read, use [NewReader] to locate
	// the desired portion of the file.
	//
	// The [Write] function in this package encodes the exported API of a
	// Go package ([types.Package]) as a file. Such files can be later
	// decoded by Read, but cannot be consumed by the compiler.
	//
	// # Future changes
	//
	// Although Read supports the formats written by both Write and the
	// compiler, the two are quite different, and there is an open
	// proposal (https://go.dev/issue/69491) to separate these APIs.
	//
	// Under that proposal, this package would ultimately provide only the
	// Read operation for compiler export data, which must be defined in
	// this module (golang.org/x/tools), not in the standard library, to
	// avoid version skew for developer tools that need to read compiler
	// export data both before and after a Go release, such as from Go
	// 1.23 to Go 1.24. Because this package lives in the tools module,
	// clients can update their version of the module some time before the
	// Go 1.24 release and rebuild and redeploy their tools, which will
	// then be able to consume both Go 1.23 and Go 1.24 export data files,
	// so they will work before and after the Go update. (See discussion
	// at https://go.dev/issue/15651.)
	//
	// The operations to import and export [go/types] data structures
	// would be defined in the go/types package as Import and Export.
	// [Write] would (eventually) delegate to Export,
	// and [Read], when it detects a file produced by Export,
	// would delegate to Import.
	//
	// # Deprecations
	//
	// The [NewImporter] and [Find] functions are deprecated and should
	// not be used in new code. The [WriteBundle] and [ReadBundle]
	// functions are experimental, and there is an open proposal to
	// deprecate them (https://go.dev/issue/69573).
	package gcexportdata

	import (
	"bufio"
	"bytes"
	"encoding/json"
	"fmt"
	"go/token"
	"go/types"
	"io"
	"os/exec"

	"golang.org/x/tools/internal/gcimporter"
	)

	// 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 Find(importPath, srcDir string) (filename, path string) {
	cmd := exec.Command("go", "list", "-json", "-export", "--", importPath)
	cmd.Dir = srcDir
	out, err := cmd.Output()
	if err != nil {
	return "", ""
	}
	var data struct {
	ImportPath string
	Export string
	}
	json.Unmarshal(out, &data)
	return data.Export, data.ImportPath
	}

	// 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 NewReader(r io.Reader) (io.Reader, error) {
	buf := bufio.NewReader(r)
	size, err := gcimporter.FindExportData(buf)
	if err != nil {
	return nil, err
	}

	// We were given an archive and found the __.PKGDEF in it.
	// This tells us the size of the export data, and we don't
	// need to return the entire file.
	return &io.LimitedReader{
	R: buf,
	N: size,
	}, nil
	}

	// readAll works the same way as io.ReadAll, but avoids allocations and copies
	// by preallocating a byte slice of the necessary size if the size is known up
	// front. This is always possible when the input is an archive. In that case,
	// NewReader will return the known size using an io.LimitedReader.
	func readAll(r io.Reader) ([]byte, error) {
	if lr, ok := r.(*io.LimitedReader); ok {
	data := make([]byte, lr.N)
	_, err := io.ReadFull(lr, data)
	return data, err
	}
	return io.ReadAll(r)
	}

	// Read reads export data from in, decodes it, and returns type
	// information for the package.
	//
	// Read is capable of reading export data produced by [Write] at the
	// same source code version, or by the last two Go releases (plus tip)
	// of the standard Go compiler. Reading files from older compilers may
	// produce an error.
	//
	// 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.
	func Read(in io.Reader, fset token.FileSet, imports map[string]types.Package, path string) (*types.Package, error) {
	data, err := readAll(in)
	if err != nil {
	return nil, fmt.Errorf("reading export data for %q: %v", path, err)
	}

	if bytes.HasPrefix(data, []byte("!<arch>")) {
	return nil, fmt.Errorf("can't read export data for %q directly from an archive file (call gcexportdata.NewReader first to extract export data)", path)
	}

	// The indexed export format starts with an 'i'; the older
	// binary export format starts with a 'c', 'd', or 'v'
	// (from "version"). Select appropriate importer.
	if len(data) > 0 {
	switch data[0] {
	case 'v', 'c', 'd':
	// binary, produced by cmd/compile till go1.10
	return nil, fmt.Errorf("binary (%c) import format is no longer supported", data[0])

	case 'i':
	// indexed, produced by cmd/compile till go1.19,
	// and also by [Write].
	//
	// If proposal #69491 is accepted, go/types
	// serialization will be implemented by
	// types.Export, to which Write would eventually
	// delegate (explicitly dropping any pretence at
	// inter-version Write-Read compatibility).
	// This [Read] function would delegate to types.Import
	// when it detects that the file was produced by Export.
	_, pkg, err := gcimporter.IImportData(fset, imports, data[1:], path)
	return pkg, err

	case 'u':
	// unified, produced by cmd/compile since go1.20
	_, pkg, err := gcimporter.UImportData(fset, imports, data[1:], path)
	return pkg, err

	default:
	l := len(data)
	if l > 10 {
	l = 10
	}
	return nil, fmt.Errorf("unexpected export data with prefix %q for path %s", string(data[:l]), path)
	}
	}
	return nil, fmt.Errorf("empty export data for %s", path)
	}

	// Write writes encoded type information for the specified package to out.
	// The FileSet provides file position information for named objects.
	func Write(out io.Writer, fset token.FileSet, pkg types.Package) error {
	if _, err := io.WriteString(out, "i"); err != nil {
	return err
	}
	return gcimporter.IExportData(out, fset, pkg)
	}

	// 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 ReadBundle(in io.Reader, fset token.FileSet, imports map[string]types.Package) ([]*types.Package, error) {
	data, err := readAll(in)
	if err != nil {
	return nil, fmt.Errorf("reading export bundle: %v", err)
	}
	return gcimporter.IImportBundle(fset, imports, data)
	}

	// 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.
	func WriteBundle(out io.Writer, fset token.FileSet, pkgs []types.Package) error {
	return gcimporter.IExportBundle(out, fset, pkgs)
	}