toolchain

Documentation

Index

• Constants
• Variables
• func Add(dir, toolchainPath string, opt *AddOpt) error
• func Bundle(toolchainDir, outputDir string, variants []Variant, dryRun, verbose bool) (bundles []string, err error)
• func ChooseTool(op, unitType string) (*srclib.ToolRef, error)
• func Dir(toolchainPath string) (string, error)
• func ListTools(op string) ([]*srclib.ToolRef, error)
• func Unbundle(toolchainPath, archiveName string, r io.Reader) (err error)
• type AddOpt
• type Config
• type Info
  • func CloneOrUpdate(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)
• type Variant
  • func ParseVariant(s string) Variant
  • func (v Variant) String() string

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.

Variables

var (
	// NoToolchains operates srclib in no-toolchain mode, where it
	// does not try to look for system toolchains in your SRCLIBPATH.
	NoToolchains, _ = strconv.ParseBool(os.Getenv("SRCLIB_NO_TOOLCHAINS"))
)

Functions

func Add

func Add(dir, toolchainPath string, opt *AddOpt) error

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

func Bundle

func Bundle(toolchainDir, outputDir string, variants []Variant, dryRun, verbose bool) (bundles []string, err error)

Bundle builds all variants of the toolchain and creates separate archive files for each variant in a temporary directory. It returns a list of variants and the archive files produced from them.

If variants is nil, all variants specified in the Srclibtoolchain file are built.

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 Dir

func Dir(toolchainPath string) (string, error)

Dir returns the directory where the named toolchain lives (under the SRCLIBPATH). If the toolchain already exists in any of the entries of SRCLIBPATH, that directory is returned. Otherwise a nonexistent directory in the first SRCLIBPATH entry is returned.

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.

func Unbundle

func Unbundle(toolchainPath, archiveName string, r io.Reader) (err error)

Unbundle unpacks the archive r to the toolchain named by the given toolchain path. The archiveName indicates what type of archive r contains; e.g., "foo.tar.gz" is a gzipped tar archive, "foo.tar" is just a tar archive, etc. An error is returned if archiveName's suffix isn't that of a recognized format.

Types

type AddOpt

type AddOpt struct {
	// Force add a toolchain, overwriting any existing toolchains.
	Force bool
}

type Config

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

	// Bundle configures the way that this toolchain is built and
	// archived. If Bundle is not set, it means that the toolchain
	// can't be bundled.
	Bundle *struct {
		// Paths is a list of path globs whose matches are included in
		// the toolchain bundle archive file (created, e.g., using
		// "srclib toolchain bundle <PATH>"). It should contain all of
		// the files necessary to execute the toolchain. For
		// toolchains whose entrypoint is a static binary or JAR, this
		// is typically the entrypoint plus any shell scripts or
		// support files necessary.
		//
		// Go's filepath.Glob is used for globbing. In addition, if a
		// dir is specified, all of its entries are included
		// recursively.
		//
		// "Srclibtoolchain" and ".bin/{basename}" (where {basename}
		// is this toolchain's path's final path component) MUST
		// always be included in this list, or else when unarchived
		// the bundle won't be a valid toolchain.
		Paths []string `json:",omitempty"`

		// Commands is the list of commands to run in order to build
		// the files to archive. (E.g., "go build ...".) Sometimes
		// these commands just consist of a "make install" or similar
		// invocation.
		//
		// All commands are passed to `sh -c`.
		Commands []string `json:",omitempty"`

		// Variants is the set of possible bundles. Typically these
		// define products such as "linux-amd64", "linux-386",
		// "darwin-amd64", etc., for binary outputs.
		//
		// The key-value pairs specified in each variant are available
		// to the commands (in the Commands list). Each command's
		// variable references ($foo or ${foo}) are expanded using the
		// values in the Variant, and they are run with the Variant's
		// properties set as environment variables.
		Variants []Variant `json:",omitempty"`
	}
}

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 CloneOrUpdate

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

CloneOrUpdate 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

	// SetLogger sets the logger for Tool to l.
	SetLogger(l *log.Logger)
}

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.

type Variant

type Variant map[string]string

Variant represents a single permutation of variables that produces a single product (for toolchain bundles); e.g., {"os":"linux", "arch": "amd64"}.

func ParseVariant

func ParseVariant(s string) Variant

ParseVariant parses a variant string (e.g., "arch-386_os-linux") into its key-value pairs ({"arch": "386", "os": "linux"}).

func (Variant) String

func (v Variant) String() string