config

Documentation

Overview

Package config provides extensible configuration for Gazelle libraries.

Packages may define Configurers which add support for new command-line options and directive comments in build files. Note that the language.Language interface embeds Configurer, so each language extension has the opportunity

When Gazelle walks the directory trees in a repository, it calls the Configure method of each Configurer to produce a Config object. Config objects are passed as arguments to most functions in Gazelle, so this mechanism may be used to control many aspects of Gazelle's behavior.

Index

• Constants
• Variables
• type CommonConfigurer
  • func (cc *CommonConfigurer) CheckFlags(fs *flag.FlagSet, c *Config) error
  • func (cc *CommonConfigurer) Configure(c *Config, rel string, f *rule.File)
  • func (cc *CommonConfigurer) KnownDirectives() []string
  • func (cc *CommonConfigurer) RegisterFlags(fs *flag.FlagSet, cmd string, c *Config)
• type Config
  • func New() *Config
  • func (c *Config) Clone() *Config
  • func (c *Config) DefaultBuildFileName() string
  • func (c *Config) IsValidBuildFileName(name string) bool
• type Configurer
• type MappedKind

Constants

const (
	// RulesGoRepoName is the canonical name of the rules_go repository. It must
	// match the workspace name in WORKSPACE.
	// TODO(jayconrod): move to language/go.
	RulesGoRepoName = "io_bazel_rules_go"

	// GazelleImportsKey is an internal attribute that lists imported packages
	// on generated rules. It is replaced with "deps" during import resolution.
	GazelleImportsKey = "_gazelle_imports"
)

Variables

var DefaultValidBuildFileNames = []string{"BUILD.bazel", "BUILD"}

Types

type CommonConfigurer

type CommonConfigurer struct {
	// contains filtered or unexported fields
}

CommonConfigurer handles language-agnostic command-line flags and directives, i.e., those that apply to Config itself and not to Config.Exts.

func (*CommonConfigurer) CheckFlags

func (cc *CommonConfigurer) CheckFlags(fs *flag.FlagSet, c *Config) error

func (*CommonConfigurer) Configure

func (cc *CommonConfigurer) Configure(c *Config, rel string, f *rule.File)

func (*CommonConfigurer) KnownDirectives

func (cc *CommonConfigurer) KnownDirectives() []string

func (*CommonConfigurer) RegisterFlags

func (cc *CommonConfigurer) RegisterFlags(fs *flag.FlagSet, cmd string, c *Config)

type Config

type Config struct {
	// WorkDir is the effective working directory, used to resolve relative
	// paths on the command line. When Gazelle is invoked with 'bazel run',
	// this is set by BUILD_WORKSPACE_DIRECTORY.
	WorkDir string

	// RepoRoot is the absolute, canonical path to the root directory of the
	// repository with all symlinks resolved.
	RepoRoot string

	// RepoName is the name of the repository.
	RepoName string

	// ReadBuildFilesDir is the absolute path to a directory where
	// build files should be read from instead of RepoRoot.
	ReadBuildFilesDir string

	// WriteBuildFilesDir is the absolute path to a directory where
	// build files should be written to instead of RepoRoot.
	WriteBuildFilesDir string

	// ValidBuildFileNames is a list of base names that are considered valid
	// build files. Some repositories may have files named "BUILD" that are not
	// used by Bazel and should be ignored. Must contain at least one string.
	ValidBuildFileNames []string

	// ShouldFix determines whether Gazelle attempts to remove and replace
	// usage of deprecated rules.
	ShouldFix bool

	// Strict determines how Gazelle handles build file and directive errors. When
	// set, Gazelle will exit with non-zero value after logging such errors.
	Strict bool

	// IndexLibraries determines whether Gazelle should build an index of
	// libraries in the workspace for dependency resolution
	IndexLibraries bool

	// KindMap maps from a kind name to its replacement. It provides a way for
	// users to customize the kind of rules created by Gazelle, via
	// # gazelle:map_kind.
	KindMap map[string]MappedKind

	// Repos is a list of repository rules declared in the main WORKSPACE file
	// or in macros called by the main WORKSPACE file. This may affect rule
	// generation and dependency resolution.
	Repos []*rule.Rule

	// Langs is a list of language names which Gazelle should process.
	// An empty list means "all languages".
	Langs []string

	// Exts is a set of configurable extensions. Generally, each language
	// has its own set of extensions, but other modules may provide their own
	// extensions as well. Values in here may be populated by command line
	// arguments, directives in build files, or other mechanisms.
	Exts map[string]interface{}

	// Whether Gazelle is loaded as a Bzlmod 'bazel_dep'.
	Bzlmod bool

	// ModuleToApparentName is a function that maps the name of a Bazel module
	// to the apparent name (repo_name) specified in the MODULE.bazel file. It
	// returns the empty string if the module is not found.
	ModuleToApparentName func(string) string
}

Config holds information about how Gazelle should run. This is based on command line arguments, directives, other hints in build files.

A Config applies to a single directory. A Config is created for the repository root directory, then copied and modified for each subdirectory.

Config itself contains only general information. Most configuration information is language-specific and is stored in Exts. This information is modified by extensions that implement Configurer.

func New

func New() *Config

func (*Config) Clone

func (c *Config) Clone() *Config

Clone creates a copy of the configuration for use in a subdirectory. Note that the Exts map is copied, but its contents are not. Configurer.Configure should do this, if needed.

func (*Config) DefaultBuildFileName

func (c *Config) DefaultBuildFileName() string

DefaultBuildFileName returns the base name used to create new build files.

func (*Config) IsValidBuildFileName

func (c *Config) IsValidBuildFileName(name string) bool

IsValidBuildFileName returns true if a file with the given base name should be treated as a build file.

type Configurer

type Configurer interface {
	// RegisterFlags registers command-line flags used by the extension. This
	// method is called once with the root configuration when Gazelle
	// starts. RegisterFlags may set an initial values in Config.Exts. When flags
	// are set, they should modify these values.
	RegisterFlags(fs *flag.FlagSet, cmd string, c *Config)

	// CheckFlags validates the configuration after command line flags are parsed.
	// This is called once with the root configuration when Gazelle starts.
	// CheckFlags may set default values in flags or make implied changes.
	CheckFlags(fs *flag.FlagSet, c *Config) error

	// KnownDirectives returns a list of directive keys that this Configurer can
	// interpret. Gazelle prints errors for directives that are not recoginized by
	// any Configurer.
	KnownDirectives() []string

	// Configure modifies the configuration using directives and other information
	// extracted from a build file. Configure is called in each directory.
	//
	// c is the configuration for the current directory. It starts out as a copy
	// of the configuration for the parent directory.
	//
	// rel is the slash-separated relative path from the repository root to
	// the current directory. It is "" for the root directory itself.
	//
	// f is the build file for the current directory or nil if there is no
	// existing build file.
	Configure(c *Config, rel string, f *rule.File)
}

Configurer is the interface for language or library-specific configuration extensions. Most (ideally all) modifications to Config should happen via this interface.

type MappedKind

type MappedKind struct {
	FromKind, KindName, KindLoad string
}

MappedKind describes a replacement to use for a built-in kind.