toolchain

Documentation

Index

• Constants
• func MarshalArgs(v interface{}) ([]string, error)
• type Config
• type Info
  • func Get(path string) (*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
  • func ListTools(op string) ([]*ToolInfo, error)
• type ToolRef
  • func ChooseTool(op, unitType string) (*ToolRef, error)
  • func (t ToolRef) MarshalFlag() (string, error)
  • func (t ToolRef) String() string
  • func (t *ToolRef) UnmarshalFlag(value string) error
• 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 MarshalArgs

func MarshalArgs(v interface{}) ([]string, error)

MarshalArgs takes a struct with go-flags field tags and turns it into an equivalent []string for use as command-line args.

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) (*Info, error)

Get downloads the toolchain named by the toolchain path (if it does not already exist in the SRCLIBPATH).

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

func List

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

List finds all toolchains in the SRCLIBPATH.

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.

func ListTools

func ListTools(op string) ([]*ToolInfo, 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.

type ToolRef

type ToolRef struct {
	// Toolchain is the toolchain path of the toolchain that contains this tool.
	Toolchain string

	// Subcmd is the name of the toolchain subcommand that runs this tool.
	Subcmd string
}

A ToolRef identifies a tool inside a specific toolchain. It can be used to look up the tool.

func ChooseTool

func ChooseTool(op, unitType string) (*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 (ToolRef) MarshalFlag

func (t ToolRef) MarshalFlag() (string, error)

func (ToolRef) String

func (t ToolRef) String() string

func (*ToolRef) UnmarshalFlag

func (t *ToolRef) UnmarshalFlag(value string) error

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.