1// Copyright 2016 The Go Authors. All rights reserved.
  2// Use of this source code is governed by a BSD-style
  3// license that can be found in the LICENSE file.
  4
  5// Package gcexportdata provides functions for locating, reading, and
  6// writing export data files containing type information produced by the
  7// gc compiler.  This package supports go1.7 export data format and all
  8// later versions.
  9//
 10// Although it might seem convenient for this package to live alongside
 11// go/types in the standard library, this would cause version skew
 12// problems for developer tools that use it, since they must be able to
 13// consume the outputs of the gc compiler both before and after a Go
 14// update such as from Go 1.7 to Go 1.8.  Because this package lives in
 15// golang.org/x/tools, sites can update their version of this repo some
 16// time before the Go 1.8 release and rebuild and redeploy their
 17// developer tools, which will then be able to consume both Go 1.7 and
 18// Go 1.8 export data files, so they will work before and after the
 19// Go update. (See discussion at https://golang.org/issue/15651.)
 20//
 21package gcexportdata // import "golang.org/x/tools/go/gcexportdata"
 22
 23import (
 24	"bufio"
 25	"bytes"
 26	"fmt"
 27	"go/token"
 28	"go/types"
 29	"io"
 30	"io/ioutil"
 31
 32	"golang.org/x/tools/go/internal/gcimporter"
 33)
 34
 35// Find returns the name of an object (.o) or archive (.a) file
 36// containing type information for the specified import path,
 37// using the workspace layout conventions of go/build.
 38// If no file was found, an empty filename is returned.
 39//
 40// A relative srcDir is interpreted relative to the current working directory.
 41//
 42// Find also returns the package's resolved (canonical) import path,
 43// reflecting the effects of srcDir and vendoring on importPath.
 44func Find(importPath, srcDir string) (filename, path string) {
 45	return gcimporter.FindPkg(importPath, srcDir)
 46}
 47
 48// NewReader returns a reader for the export data section of an object
 49// (.o) or archive (.a) file read from r.  The new reader may provide
 50// additional trailing data beyond the end of the export data.
 51func NewReader(r io.Reader) (io.Reader, error) {
 52	buf := bufio.NewReader(r)
 53	_, err := gcimporter.FindExportData(buf)
 54	// If we ever switch to a zip-like archive format with the ToC
 55	// at the end, we can return the correct portion of export data,
 56	// but for now we must return the entire rest of the file.
 57	return buf, err
 58}
 59
 60// Read reads export data from in, decodes it, and returns type
 61// information for the package.
 62// The package name is specified by path.
 63// File position information is added to fset.
 64//
 65// Read may inspect and add to the imports map to ensure that references
 66// within the export data to other packages are consistent.  The caller
 67// must ensure that imports[path] does not exist, or exists but is
 68// incomplete (see types.Package.Complete), and Read inserts the
 69// resulting package into this map entry.
 70//
 71// On return, the state of the reader is undefined.
 72func Read(in io.Reader, fset *token.FileSet, imports map[string]*types.Package, path string) (*types.Package, error) {
 73	data, err := ioutil.ReadAll(in)
 74	if err != nil {
 75		return nil, fmt.Errorf("reading export data for %q: %v", path, err)
 76	}
 77
 78	if bytes.HasPrefix(data, []byte("!<arch>")) {
 79		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)
 80	}
 81
 82	// The App Engine Go runtime v1.6 uses the old export data format.
 83	// TODO(adonovan): delete once v1.7 has been around for a while.
 84	if bytes.HasPrefix(data, []byte("package ")) {
 85		return gcimporter.ImportData(imports, path, path, bytes.NewReader(data))
 86	}
 87
 88	// The indexed export format starts with an 'i'; the older
 89	// binary export format starts with a 'c', 'd', or 'v'
 90	// (from "version"). Select appropriate importer.
 91	if len(data) > 0 && data[0] == 'i' {
 92		_, pkg, err := gcimporter.IImportData(fset, imports, data[1:], path)
 93		return pkg, err
 94	}
 95
 96	_, pkg, err := gcimporter.BImportData(fset, imports, data, path)
 97	return pkg, err
 98}
 99
100// Write writes encoded type information for the specified package to out.
101// The FileSet provides file position information for named objects.
102func Write(out io.Writer, fset *token.FileSet, pkg *types.Package) error {
103	b, err := gcimporter.BExportData(fset, pkg)
104	if err != nil {
105		return err
106	}
107	_, err = out.Write(b)
108	return err
109}