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 ¶
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" )
Variables ¶
This section is empty.
Functions ¶
func NewLanguage ¶
Types ¶
type FileInfo ¶
type FileInfo struct {
Path, Name string
PackageName string
Options []Option
Imports []string
HasServices bool
Services []string
Messages []string
Enums []string
}
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 (Mode) ShouldGenerateRules ¶
func (Mode) ShouldIncludePregeneratedFiles ¶
func (Mode) ShouldUseKnownImports ¶
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.