toolchain

Documentation

Index

• Constants
• func Bundle(toolchainDir, outputDir string, variants []Variant, dryRun, verbose bool) (bundles []string, err error)
• func ChooseTool(op, unitType string) (*srclib.ToolRef, error)
• func Command(path string) (string, 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 Config
• type Info
  • func List() ([]*Info, error)
  • func Lookup(path string) (*Info, error)
  • func (t *Info) ReadConfig() (*Config, error)
• type ToolInfo
• 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.

Functions

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 Command

func Command(path string) (string, error)

Command returns the path to the executable program for the toolchain with the given path.

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 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.
	Program string `json:",omitempty"`
}

Info describes a toolchain.

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 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 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