proto

Documentation

Overview

Package proto provides support for protocol buffer rules. It generates proto_library rules only (not go_proto_library or any other language-specific implementations).

Configuration

Configuration is largely controlled by Mode. In disable mode, proto rules are left alone (neither generated nor deleted). In legacy mode, filegroups are emitted containing protos. In default mode, proto_library rules are emitted. The proto mode may be set with the -proto command line flag or the "# gazelle:proto" directive.

The configuration is largely public, and other languages may depend on it. For example, go uses Mode to determine whether to generate go_proto_library rules and ignore static .pb.go files.

Rule generation

Currently, Gazelle generates at most one proto_library per directory. Protos in the same package are grouped together into a proto_library. If there are sources for multiple packages, the package name that matches the directory name will be chosen; if there is no such package, an error will be printed. We expect to provide support for multiple proto_libraries in the future when Go has support for multiple packages and we have better rule matching. The generated proto_library will be named after the directory, not the proto or the package. For example, for foo/bar/baz.proto, a proto_library rule will be generated named //foo/bar:bar_proto.

Dependency resolution

proto_library rules are indexed by their srcs attribute. Gazelle attempts to resolve proto imports (e.g., import foo/bar/bar.proto) to the proto_library that contains the named source file (e.g., //foo/bar:bar_proto). If no indexed proto_library provides the source file, Gazelle will guess a label, following conventions.

No attempt is made to resolve protos to rules in external repositories, since there's no indication that a proto import comes from an external repository. In the future, build files in external repos will be indexed, so we can support this (#12).

Gazelle has special cases for Well Known Types (i.e., imports of the form google/protobuf/*.proto). These are resolved to rules in @com_google_protobuf.

Index

• Constants
• func NewLanguage() language.Language
• func RuleName(names ...string) string
• type FileInfo
• type Mode
  • func ModeFromString(s string) (Mode, error)
  • func (m Mode) ShouldGenerateRules() bool
  • func (m Mode) ShouldIncludePregeneratedFiles() bool
  • func (m Mode) ShouldUseKnownImports() bool
  • func (m Mode) String() string
• type Option
• type Package
• type ProtoConfig
  • func GetProtoConfig(c *config.Config) *ProtoConfig

Constants

const (
	// PackageInfoKey is the name of a private attribute set on generated
	// proto_library rules. This attribute contains a Package record which
	// describes the library and its sources.
	PackageKey = "_package"
)

Functions

func NewLanguage

func NewLanguage() language.Language

func RuleName

func RuleName(names ...string) string

RuleName returns a name for a proto_library derived from the given strings. For each string, RuleName will look for a non-empty suffix of identifier characters and then append "_proto" to that.

Types

type FileInfo

type FileInfo struct {
	Path, Name string

	PackageName string

	Options []Option
	Imports []string

	HasServices bool
}

FileInfo contains metadata extracted from a .proto file.

type Mode

type Mode int

Mode determines how proto rules are generated.

const (
	// DefaultMode generates proto_library rules. Other languages should generate
	// library rules based on these (e.g., go_proto_library) and should ignore
	// checked-in generated files (e.g., .pb.go files) when there is a .proto
	// file with a similar name.
	DefaultMode Mode = iota

	// DisableMode ignores .proto files and generates empty proto_library rules.
	// Checked-in generated files (e.g., .pb.go files) should be treated as
	// normal sources.
	DisableMode

	// DisableGlobalMode is similar to DisableMode, but it also prevents
	// the use of special cases in dependency resolution for well known types
	// and Google APIs.
	DisableGlobalMode

	// LegacyMode generates filegroups for .proto files if .pb.go files are
	// present in the same directory.
	LegacyMode

	// PackageMode generates a proto_library for each set of .proto files with
	// the same package name in each directory.
	PackageMode

	// FileMode generates a proto_library for each .proto file.
	FileMode
)

func ModeFromString

func ModeFromString(s string) (Mode, error)

func (Mode) ShouldGenerateRules

func (m Mode) ShouldGenerateRules() bool

func (Mode) ShouldIncludePregeneratedFiles

func (m Mode) ShouldIncludePregeneratedFiles() bool

func (Mode) ShouldUseKnownImports

func (m Mode) ShouldUseKnownImports() bool

func (Mode) String

func (m Mode) String() string

type Option

type Option struct {
	Key, Value string
}

Option represents a top-level option statement in a .proto file. Only string options are supported for now.

type Package

type Package struct {
	Name        string
	RuleName    string // if not set, defaults to Name
	Files       map[string]FileInfo
	Imports     map[string]bool
	Options     map[string]string
	HasServices bool
}

Package contains metadata for a set of .proto files that have the same package name. This translates to a proto_library rule.

type ProtoConfig

type ProtoConfig struct {
	// Mode determines how rules are generated for protos.
	Mode Mode

	// ModeExplicit indicates whether the proto mode was set explicitly.
	ModeExplicit bool

	// GoPrefix is the current Go prefix (the Go extension may set this in the
	// root directory only). Used to generate proto rule names in the root
	// directory when there are no proto files or the proto package name
	// can't be determined.
	// TODO(jayconrod): deprecate and remove Go-specific behavior.
	GoPrefix string

	// StripImportPrefix The prefix to strip from the paths of the .proto files.
	// If set, Gazelle will apply this value to the strip_import_prefix attribute
	// within the proto_library_rule.
	StripImportPrefix string

	// ImportPrefix The prefix to add to the paths of the .proto files.
	// If set, Gazelle will apply this value to the import_prefix attribute
	// within the proto_library_rule.
	ImportPrefix string
	// contains filtered or unexported fields
}

ProtoConfig contains configuration values related to protos.

This type is public because other languages need to generate rules based on protos, so this configuration may be relevant to them.

func GetProtoConfig

func GetProtoConfig(c *config.Config) *ProtoConfig

GetProtoConfig returns the proto language configuration. If the proto extension was not run, it will return nil.