golang

Documentation

Overview

Package golang produces Kythe compilation units for each Go import path specified. Compilations are extracted incrementally, so that partial results are available to the caller.

Usage:

var c golang.Extractor
if _, err := c.Locate("fmt"); err != nil {
  log.Fatalf(`Unable to locate package "fmt": %v`, err)
}
c.Extract()
for _, pkg := range c.Packages {
  if pkg.Err != nil {
    log.Printf("Error extracting %q: %v", pkg.Path, pkg.Err)
  } else {
    writeOutput(pkg)
  }
}

Index

• type Extractor
  • func (e *Extractor) Extract() error
  • func (e *Extractor) ImportDir(dir string) (*Package, error)
  • func (e *Extractor) Locate(importPath string) (*Package, error)
• type MissingError
  • func (m *MissingError) Error() string
• type Package
  • func (p *Package) Extract() error
  • func (p *Package) Store(ctx context.Context, a *indexpack.Archive) ([]string, error)

Types

type Extractor

type Extractor struct {
	// The build configuration to use for extraction.
	BuildContext build.Context

	// The packages that have been extracted so far (initially empty).
	Packages []*Package

	// The name of the corpus that should be attributed to packages whose
	// corpus is not specified and cannot be inferred (e.g., local imports).
	Corpus string

	// The local path against which relative imports should be resolved.
	LocalPath string

	// An alternative installation path for compiled packages.  If this is set,
	// and a compiled package cannot be found in the normal location, the
	// extractor will try in this location.
	AltInstallPath string

	// A function to generate a vname from a package's import path.  If nil,
	// the extractor will use govname.ForPackage.
	PackageVName func(corpus string, bp *build.Package) *spb.VName

	// A function to convert a directory path to an import path.  If nil, the
	// path is made relative to the first matching element of the build
	// context's GOROOT or GOPATH or the current working directory.
	DirToImport func(path string) (string, error)
	// contains filtered or unexported fields
}

An Extractor contains the state needed to extract Go compilations from build information. The zero value is ready for use with default settings.

func (*Extractor) Extract

func (e *Extractor) Extract() error

Extract invokes the Extract method of each package in the Packages list, and updates its Err field with the result. If there were errors in extraction, one of them is returned.

func (*Extractor) ImportDir

func (e *Extractor) ImportDir(dir string) (*Package, error)

ImportDir attempts to import the Go package located in the given directory. An import path is inferred from the directory path.

func (*Extractor) Locate

func (e *Extractor) Locate(importPath string) (*Package, error)

Locate attempts to locate the specified import path in the build context. If the package has already been located, its existing package is returned. Otherwise, if importing succeeds, a new *Package value is returned, and also appended to the Packages field.

type MissingError

type MissingError struct {
	Path    string   // The import path of the incomplete package
	Missing []string // The import paths of the missing dependencies
}

MissingError is the concrete type of errors about missing dependencies.

func (*MissingError) Error

func (m *MissingError) Error() string

type Package

type Package struct {
	Path         string                 // Import or directory path
	Err          error                  // Error discovered during processing
	BuildPackage *build.Package         // Package info from the go/build library
	VName        *spb.VName             // The package's Kythe vname
	Units        []*apb.CompilationUnit // Compilations generated from Package
	// contains filtered or unexported fields
}

Package represents a single Go package extracted from local files.

func (*Package) Extract

func (p *Package) Extract() error

Extract populates the Units field of p, and reports an error if any occurred.

After this method returns successfully, the require inputs for each of the Units are partially resolved, meaning we know their filesystem paths but not their contents. The filesystem paths are resolved to contents and digests by the Store method.

func (*Package) Store

func (p *Package) Store(ctx context.Context, a *indexpack.Archive) ([]string, error)

Store writes the compilation units of p to the specified archive and returns its unit file names. This has the side-effect of updating the required inputs of the compilations so that they contain the proper digest values.