BaseLang implements the minimum of language.Language interface. This is not meant to be used directly by Gazelle, but to be used by a downstream struct through composition. End users could use this to write an extensions iteratively without having to implement every functions in the interface right away.
Example usage:
type MyLang struct {
language.BaseLang
}
func NewLanguage() language.Language {
return &MyLang{}
}
type BaseLang struct{}
func (b *BaseLang) CheckFlags(fs *flag.FlagSet, c *config.Config) error
func (b *BaseLang) Configure(c *config.Config, rel string, f *rule.File)
func (b *BaseLang) Embeds(r *rule.Rule, from label.Label) []label.Label
func (b *BaseLang) Fix(c *config.Config, f *rule.File)
func (b *BaseLang) GenerateRules(args GenerateArgs) GenerateResult
func (b *BaseLang) Imports(c *config.Config, r *rule.Rule, f *rule.File) []resolve.ImportSpec
func (b *BaseLang) Kinds() map[string]rule.KindInfo
func (b *BaseLang) KnownDirectives() []string
func (b *BaseLang) Loads() []rule.LoadInfo
func (b *BaseLang) Name() string
func (b *BaseLang) RegisterFlags(fs *flag.FlagSet, cmd string, c *config.Config)
func (b *BaseLang) Resolve(c *config.Config, ix *resolve.RuleIndex, rc *repo.RemoteCache, r *rule.Rule, imports interface{}, from label.Label)
type BaseLifecycleManager struct{}
func (m *BaseLifecycleManager) AfterResolvingDeps(ctx context.Context)
func (m *BaseLifecycleManager) Before(ctx context.Context)
func (m *BaseLifecycleManager) DoneGeneratingRules()
FinishableLanguage allows a Language to be notified when Generate is finished being called.
type FinishableLanguage interface {
// DoneGeneratingRules is called when all calls to GenerateRules have been
// completed.
// This allows for hooks to be called, for instance to release resources
// such as shutting down a background server.
// No further calls will be made to GenerateRules on this Language instance
// after this method has been called.
DoneGeneratingRules()
}
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 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
}
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 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 the 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{}
}
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 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
}
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 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
}
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.
* 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".
* 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 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
// 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
// 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.
//
// Deprecated: Implement ModuleAwareLanguage's ApparentLoads.
Loads() []rule.LoadInfo
// 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)
}
LifecycleManager allows an extension to initialize and free up resources at different points. Extensions should embed BaseLifecycleManager instead of implementing this interface directly.
type LifecycleManager interface {
FinishableLanguage
Before(ctx context.Context)
AfterResolvingDeps(ctx context.Context)
}
type ModuleAwareLanguage interface {
// ApparentLoads 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.
//
// The moduleToApparentName argument is a function that resolves a given
// Bazel module name to the apparent repository name configured for this
// module in the MODULE.bazel file, or the empty string if there is no such
// module or the MODULE.bazel file doesn't exist. Languages should use the
// non-empty value returned by this function to form the repository part of
// the load statements they return and fall back to using the legacy
// WORKSPACE name otherwise.
//
// See https://bazel.build/external/overview#concepts for more information
// on repository names.
//
// Example: For a project with these lines in its MODULE.bazel file:
//
// bazel_dep(name = "rules_go", version = "0.38.1", repo_name = "my_rules_go")
// bazel_dep(name = "gazelle", version = "0.27.0")
//
// moduleToApparentName["rules_go"] == "my_rules_go"
// moduleToApparentName["gazelle"] == "gazelle"
// moduleToApparentName["foobar"] == ""
ApparentLoads(moduleToApparentName func(string) string) []rule.LoadInfo
}
RepoImporter may be implemented by languages that support importing repository rules from another build system.
EXPERIMENTAL: this may change or be removed.
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
}
RepoUpdater may be implemented by languages that support updating repository rules that provide named libraries.
EXPERIMENTAL: this may change or be removed.
type RepoUpdater interface {
UpdateRepos(args UpdateReposArgs) UpdateReposResult
}
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 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
}
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.
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
}
| Name | Synopsis |
|---|---|
| .. | |
| bazel | |
| visibility | |
| go | Package golang provides support for Go and Go proto rules. |
| gen_std_package_list | gen_std_package_list reads a text file containing a list of packages (one per line) and generates a .go file containing a set of package names. |
| proto | Package proto provides support for protocol buffer rules. |
| gen | |