toolchain

Documentation

Index

• Constants
• func Add(dir, toolchainPath string) error
• func ChooseTool(op, unitType string) (*srclib.ToolRef, error)
• func ListTools(op string) ([]*srclib.ToolRef, error)
• type Config
• type Info
  • func Get(path string, update bool) (*Info, error)
  • func List() ([]*Info, error)
  • func Lookup(path string) (*Info, error)
  • func (t *Info) ReadConfig() (*Config, error)
• type Mode
  • func (m Mode) String() string
• type Tool
  • func OpenTool(toolchain, subcmd string, mode Mode) (Tool, error)
• type ToolInfo
• type Toolchain
  • func Open(path string, mode Mode) (Toolchain, error)

Constants

const ConfigFilename = "Srclibtoolchain"

ConfigFilename is the filename of the toolchain configuration file. The presence of this file in a directory signifies that a srclib toolchain is defined in that directory.

Functions

func Add

func Add(dir, toolchainPath string) error

Add creates a symlink in the SRCLIBPATH so that the toolchain in dir is available at the toolchainPath.

func ChooseTool

func ChooseTool(op, unitType string) (*srclib.ToolRef, error)

ChooseTool determines which toolchain and tool to use to run op (graph, depresolve, etc.) on a source unit of the given type. If no tools fit the criteria, an error is returned.

The selection algorithm is currently very simplistic: if exactly one tool is found that can perform op on the source unit type, it is returned. If zero or more than 1 are found, then an error is returned. TODO(sqs): extend this to choose the "best" tool when multiple tools would suffice.

func ListTools

func ListTools(op string) ([]*srclib.ToolRef, error)

ListTools lists all tools in all available toolchains (returned by List). If op is non-empty, only tools that perform that operation are returned.

Types

type Config

type Config struct {
	// Tools is the list of this toolchain's tools and their definitions.
	Tools []*ToolInfo
}

Config represents a Srclibtoolchain file, which defines a srclib toolchain.

type Info

type Info struct {
	// Path is the toolchain's path (not a directory path) underneath the
	// SRCLIBPATH. It consists of the URI of this repository's toolchain plus
	// its subdirectory path within the repository. E.g., "github.com/foo/bar"
	// for a toolchain defined in the root directory of that repository.
	Path string

	// Dir is the filesystem directory that defines this toolchain.
	Dir string

	// ConfigFile is the path to the Srclibtoolchain file, relative to Dir.
	ConfigFile string

	// Program is the path to the executable program (relative to Dir) to run to
	// invoke this toolchain, for the program execution method.
	Program string `json:",omitempty"`

	// Dockerfile is the path to the Dockerfile (relative to Dir) that defines
	// the image to build and run to invoke this toolchain, for the Docker
	// container execution method.
	Dockerfile string `json:",omitempty"`
}

Info describes a toolchain.

func Get

func Get(path string, update bool) (*Info, error)

Get downloads the toolchain named by the toolchain path (if it does not already exist in the SRCLIBPATH). If update is true, it uses the network to update the toolchain.

Assumes that the clone URL is "https://" + path + ".git".

func List

func List() ([]*Info, error)

List finds all toolchains in the SRCLIBPATH.

List does not find nested toolchains; i.e., if DIR is a toolchain dir (with a DIR/Srclibtoolchain file), then none of DIR's subdirectories are searched for toolchains.

func Lookup

func Lookup(path string) (*Info, error)

Lookup finds a toolchain by path in the SRCLIBPATH. For each DIR in SRCLIBPATH, it checks for the existence of DIR/PATH/Srclibtoolchain.

func (*Info) ReadConfig

func (t *Info) ReadConfig() (*Config, error)

ReadConfig reads and parses the Srclibtoolchain config file for the toolchain.

type Mode

type Mode uint

A Mode value is a set of flags (or 0) that control how toolchains are used.

const (
	// AsProgram enables the use of program toolchains.
	AsProgram Mode = 1 << iota

	// AsDockerContainer enables the use of Docker container toolchains.
	AsDockerContainer
)

func (Mode) String

func (m Mode) String() string

type Tool

type Tool interface {
	// Command returns an *exec.Cmd suitable for running this tool.
	Command() (*exec.Cmd, error)

	// Run executes this tool with args (sending the JSON-serialization of input
	// on stdin, if input is non-nil) and parses the JSON response into resp.
	Run(arg []string, input, resp interface{}) error
}

A Tool is a subcommand of a Toolchain that performs an single operation, such as one type of analysis on a source unit.

func OpenTool

func OpenTool(toolchain, subcmd string, mode Mode) (Tool, error)

OpenTool opens a tool in toolchain (which is a toolchain path) named subcmd. The mode parameter controls how the toolchain is opened.

type ToolInfo

type ToolInfo struct {
	// Subcmd is the subcommand name of this tool.
	//
	// By convention, this is the same as Op in toolchains that only have one
	// tool that performs this operation (e.g., a toolchain's "graph" subcommand
	// performs the "graph" operation).
	Subcmd string

	// Op is the operation that this tool performs (e.g., "scan", "graph",
	// "deplist", etc.).
	Op string

	// SourceUnitTypes is a list of source unit types (e.g., "GoPackage") that
	// this tool can operate on.
	//
	// If this tool doesn't operate on source units (for example, it operates on
	// directories or repositories, such as the "blame" tools), then this will
	// be empty.
	//
	// TODO(sqs): determine how repository- or directory-level tools will be
	// defined.
	SourceUnitTypes []string `json:",omitempty"`
}

ToolInfo describes a tool in a toolchain.

type Toolchain

type Toolchain interface {
	// Command returns an *exec.Cmd that will execute this toolchain. Do not use
	// this to execute a tool in this toolchain; use OpenTool instead.
	//
	// Do not modify the returned Cmd's Dir field; some implementations of
	// Toolchain use dir to construct other parts of the Cmd, so it's important
	// that all references to the working directory are consistent.
	Command() (*exec.Cmd, error)

	// Build prepares the toolchain, if needed. For example, for Dockerized
	// toolchains, it builds the Docker image.
	Build() error

	// IsBuilt returns whether the toolchain is built and can be executed (using
	// Command).
	IsBuilt() (bool, error)
}

A Toolchain is either a local executable program or a Docker container that wraps such a program. Toolchains contain tools (as subcommands), which perform actions or analysis on a project's source code.

func Open

func Open(path string, mode Mode) (Toolchain, error)

Open opens a toolchain by path. The mode parameter controls how it is opened.