toolchain

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"`
	}
}

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"`
}

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"`
}

type Variant map[string]string