merger

Documentation

Overview

Package merger provides functions for merging generated rules into existing build files.

Gazelle's normal workflow is roughly as follows:

1. Read metadata from sources.

2. Generate new rules.

3. Merge newly generated rules with rules in the existing build file if there is one.

4. Build an index of merged library rules for dependency resolution.

5. Resolve dependencies (i.e., convert import strings to deps labels).

6. Merge the newly resolved dependencies.

7. Write the merged file back to disk.

This package is used for sets 3 and 6 above.

Index

• Constants
• func CheckGazelleLoaded(f *rule.File) error
• func FixLoads(f *rule.File, knownLoads []rule.LoadInfo)
• func Match(rules []*rule.Rule, x *rule.Rule, info rule.KindInfo) (*rule.Rule, error)
• func MergeFile(oldFile *rule.File, emptyRules, genRules []*rule.Rule, phase Phase, ...)
• type Phase

Constants

const UnstableInsertIndexKey = "_gazelle_insert_index"

UnstableInsertIndexKey is the name of an internal attribute that may be set on newly generated rules. When MergeFile is given a generated rule that doesn't match any existing rule, MergeFile will insert the rule at the index indicated by this key instead of at the end of the file.

This definition is unstable and may be removed in the future.

TODO(jayconrod): make this stable *or* find a better way to express it.

Functions

func CheckGazelleLoaded

func CheckGazelleLoaded(f *rule.File) error

CheckGazelleLoaded searches the given WORKSPACE file for a repository named "bazel_gazelle". If no such repository is found *and* the repo is not declared with a directive *and* at least one load statement mentions the repository, a descriptive error will be returned.

This should be called after modifications have been made to WORKSPACE (i.e., after FixLoads) before writing it to disk.

func FixLoads

func FixLoads(f *rule.File, knownLoads []rule.LoadInfo)

FixLoads removes loads of unused go rules and adds loads of newly used rules. This should be called after FixFile and MergeFile, since symbols may be introduced that aren't loaded.

This function calls File.Sync before processing loads.

func Match

func Match(rules []*rule.Rule, x *rule.Rule, info rule.KindInfo) (*rule.Rule, error)

Match searches for a rule that can be merged with x in rules.

A rule is considered a match if its kind is equal to x's kind AND either its name is equal OR at least one of the attributes in matchAttrs is equal.

If there are no matches, nil and nil are returned.

If a rule has the same name but a different kind, nill and an error are returned.

If there is exactly one match, the rule and nil are returned.

If there are multiple matches, match will attempt to disambiguate, based on the quality of the match (name match is best, then attribute match in the order that attributes are listed). If disambiguation is successful, the rule and nil are returned. Otherwise, nil and an error are returned.

func MergeFile

func MergeFile(oldFile *rule.File, emptyRules, genRules []*rule.Rule, phase Phase, kinds map[string]rule.KindInfo)

MergeFile combines information from newly generated rules with matching rules in an existing build file. MergeFile can also delete rules which are empty after merging.

oldFile is the file to merge. It must not be nil.

emptyRules is a list of stub rules (with no attributes other than name) which were not generated. These are merged with matching rules. The merged rules are deleted if they contain no attributes that make them buildable (e.g., srcs, deps, anything in rule.KindInfo.NonEmptyAttrs).

genRules is a list of newly generated rules. These are merged with matching rules. A rule matches if it has the same kind and name or if some other attribute in rule.KindInfo.MatchAttrs matches (e.g., "importpath" in go_library). Elements of genRules that don't match any existing rule are appended to the end of oldFile.

phase indicates whether this is a pre- or post-resolve merge. Different attributes (rule.KindInfo.MergeableAttrs or ResolveAttrs) will be merged.

kinds maps rule kinds (e.g., "go_library") to metadata that helps merge rules of that kind.

When a generated and existing rule are merged, each attribute is merged separately. If an attribute is mergeable (according to KindInfo), values from the existing attribute are replaced by values from the generated attribute. Comments are preserved on values that are present in both versions of the attribute. If at attribute is not mergeable, the generated version of the attribute will be added if no existing attribute is present; otherwise, the existing attribute will be preserved.

Note that "# keep" comments affect merging. If a value within an existing attribute is marked with a "# keep" comment, it will not be removed. If an attribute is marked with a "# keep" comment, it will not be merged. If a rule is marked with a "# keep" comment, the whole rule will not be modified.

Types

type Phase

type Phase int

Phase indicates which attributes should be merged in matching rules.

const (
	// The pre-resolve merge is performed before rules are indexed for dependency
	// resolution. All attributes not related to dependencies are merged
	// (i.e., rule.KindInfo.MergeableAttrs). This merge must be performed
	// before indexing because attributes related to indexing (e.g.,
	// srcs, importpath) will be affected.
	PreResolve Phase = iota

	// The post-resolve merge is performed after rules are indexed. All attributes
	// related to dependencies are merged (i.e., rule.KindInfo.ResolveAttrs).
	PostResolve
)