language

Documentation

Overview

Package language provides an interface for language extensions in Gazelle. Support for a new language can be added by defining a package with a function named "New" that returns a value assignable to this interface.

TODO(jayconrod): document how to incorporate languages into a gazelle binary that can be run by Bazel.

Index

• type GenerateArgs
• type GenerateResult
• type ImportReposArgs
• type ImportReposResult
• type Language
• type RepoImporter
• type RepoUpdater
• type UpdateReposArgs
• type UpdateReposResult

Types

type GenerateArgs

type GenerateArgs struct {
	// Config is the configuration for the directory where rules are being
	// generated.
	Config *config.Config

	// Dir is the canonical absolute path to the directory.
	Dir string

	// Rel is the slash-separated path to the directory, relative to the
	// repository root ("" for the root directory itself). This may be used
	// as the package name in labels.
	Rel string

	// File is the build file for the directory. File is nil if there is
	// no existing build file.
	File *rule.File

	// Subdirs is a list of subdirectories in the directory, including
	// symbolic links to directories that Gazelle will follow.
	// RegularFiles is a list of regular files including other symbolic
	// links.
	// GeneratedFiles is a list of generated files in the directory
	// (usually these are mentioned as "out" or "outs" attributes in rules).
	Subdirs, RegularFiles, GenFiles []string

	// OtherEmpty is a list of empty rules generated by other languages.
	// OtherGen is a list of generated rules generated by other languages.
	OtherEmpty, OtherGen []*rule.Rule
}

GenerateArgs contains arguments for language.GenerateRules. Arguments are passed in a struct value so that new fields may be added in the future without breaking existing implementations.

type GenerateResult

type GenerateResult struct {
	// Gen is a list of rules generated from files found in the directory
	// GenerateRules was asked to process. These will be merged with existing
	// rules or added to the build file.
	Gen []*rule.Rule

	// Empty is a list of rules that cannot be built with the files found in the
	// directory GenerateRules was asked to process. These will be merged with
	// existing rules. If ther merged rules are empty, they will be deleted.
	Empty []*rule.Rule

	// Imports contains information about the imported libraries for each
	// rule in Gen. Gen and Imports must have the same length, since they
	// correspond. These values are passed to Resolve after merge. The type
	// is opaque since different languages may use different representations.
	Imports []interface{}
}

GenerateResult contains return values for language.GenerateRules. Results are returned through a struct value so that new (optional) fields may be added without breaking existing implementations.

type ImportReposArgs

type ImportReposArgs struct {
	// Config is the configuration for the main workspace.
	Config *config.Config

	// Path is the name of the configuration file to import.
	Path string

	// Prune indicates whether repository rules that are no longer needed
	// should be deleted. This means the Empty list in the result should be
	// filled in.
	Prune bool

	// Cache stores information fetched from the network and ensures that
	// the same request isn't made multiple times.
	Cache *repo.RemoteCache
}

ImportReposArgs contains arguments for RepoImporter.ImportRepos. Arguments are passed in a struct value so that new fields may be added in the future without breaking existing implementations.

EXPERIMENTAL: this may change or be removed.

type ImportReposResult

type ImportReposResult struct {
	// Gen is a list of imported repository rules.
	Gen []*rule.Rule

	// Empty is a list of repository rules that may be deleted. This should only
	// be set if ImportReposArgs.Prune is true.
	Empty []*rule.Rule

	// Error is any fatal error that occurred. Non-fatal errors should be logged.
	Error error
}

ImportReposResult contains return values for RepoImporter.ImportRepos. Results are returned through a struct so that new (optional) fields may be added without breaking existing implementations.

EXPERIMENTAL: this may change or be removed.

type Language

type Language interface {
	// TODO(jayconrod): is embedding Configurer strictly necessary?
	config.Configurer
	resolve.Resolver

	// Kinds returns a map of maps rule names (kinds) and information on how to
	// match and merge attributes that may be found in rules of those kinds. All
	// kinds of rules generated for this language may be found here.
	Kinds() map[string]rule.KindInfo

	// Loads returns .bzl files and symbols they define. Every rule generated by
	// GenerateRules, now or in the past, should be loadable from one of these
	// files.
	Loads() []rule.LoadInfo

	// GenerateRules extracts build metadata from source files in a directory.
	// GenerateRules is called in each directory where an update is requested
	// in depth-first post-order.
	//
	// args contains the arguments for GenerateRules. This is passed as a
	// struct to avoid breaking implementations in the future when new
	// fields are added.
	//
	// A GenerateResult struct is returned. Optional fields may be added to this
	// type in the future.
	//
	// Any non-fatal errors this function encounters should be logged using
	// log.Print.
	GenerateRules(args GenerateArgs) GenerateResult

	// Fix repairs deprecated usage of language-specific rules in f. This is
	// called before the file is indexed. Unless c.ShouldFix is true, fixes
	// that delete or rename rules should not be performed.
	Fix(c *config.Config, f *rule.File)
}

Language describes an extension for Gazelle that provides support for a set of Bazel rules.

Languages are used primarily by the fix and update commands. The order in which languages are used matters, since languages may depend on one another. For example, go depends on proto, since go_proto_libraries are generated from metadata stored in proto_libraries.

A single instance of Language is created for each fix / update run. Some state may be stored in this instance, but stateless behavior is encouraged, especially since some operations may be concurrent in the future.

Tasks languages are used for

* Configuration (embedded interface config.Configurer). Languages may define command line flags and alter the configuration in a directory based on directives in build files.

* Fixing deprecated usage of rules in build files.

* Generating rules from source files in a directory.

* Resolving library imports (embedded interface resolve.Resolver). For example, import strings like "github.com/foo/bar" in Go can be resolved into Bazel labels like "@com_github_foo_bar//:go_default_library".

Tasks languages support

* Generating load statements: languages list files and symbols that may be loaded.

* Merging generated rules into existing rules: languages provide metadata that helps with rule matching, merging, and deletion.

type RepoImporter

type RepoImporter interface {
	// CanImport returns whether a given configuration file may be imported
	// with this extension. Only one extension may import any given file.
	// ImportRepos will not be called unless this returns true.
	CanImport(path string) bool

	// ImportRepos generates a list of repository rules by reading a
	// configuration file from another build system.
	ImportRepos(args ImportReposArgs) ImportReposResult
}

RepoImporter may be implemented by languages that support importing repository rules from another build system.

EXPERIMENTAL: this may change or be removed.

type RepoUpdater

type RepoUpdater interface {
	UpdateRepos(args UpdateReposArgs) UpdateReposResult
}

RepoUpdater may be implemented by languages that support updating repository rules that provide named libraries.

EXPERIMENTAL: this may change or be removed.

type UpdateReposArgs

type UpdateReposArgs struct {
	// Config is the configuration for the main workspace.
	Config *config.Config

	// Imports is a list of libraries to update. UpdateRepos should return
	// repository rules that provide these libraries. It may also return
	// repository rules providing transitive dependencies.
	Imports []string

	// Cache stores information fetched from the network and ensures that
	// the same request isn't made multiple times.
	Cache *repo.RemoteCache
}

UpdateReposArgs contains arguments for RepoUpdater.UpdateRepos. Arguments are passed in a struct value so that new fields may be added in the future without breaking existing implementations.

EXPERIMENTAL: this may change or be removed.

type UpdateReposResult

type UpdateReposResult struct {
	// Gen is a list of repository rules that provide libraries named by
	// UpdateImportArgs.Imports. These will be merged with existing rules or
	// added to WORKSPACE. This list may be shorter or longer than the list
	// of imports, since a single repository may provide multiple imports,
	// and additional repositories may be needed for transitive dependencies.
	Gen []*rule.Rule

	// Error is any fatal error that occurred. Non-fatal errors should be logged.
	Error error
}

UpdateReposResult contains return values for RepoUpdater.UpdateRepos. Results are returned through a struct so that new (optional) fields may be added without breaking existing implementations.

EXPERIMENTAL: this may change or be removed.