Documentation
¶
Overview ¶
Package bazel provides integration between Buffalo and the Bazel build system.
Buffalo can detect Bazel workspaces, parse proto_library targets from BUILD files, generate code respecting Bazel's dependency graph, and produce BUILD.bazel files for the generated output so that downstream Bazel targets can depend on it.
Two collaboration modes are supported:
Proto-library mode: Bazel defines proto_library targets, Buffalo discovers them, compiles proto files, and generates language-specific BUILD targets.
Filegroup mode: Bazel uses filegroup(srcs = glob(["**/*.proto"])) to declare proto sources. Buffalo compiles them and generates filegroup + library targets for the output so downstream services can depend on them via compile_data / deps.
Index ¶
- func FindBuildFiles(root string) (map[string]string, error)
- func HasBazelFile(dir string) bool
- func IsBazelAvailable() bool
- func IsBazelWorkspace(dir string) bool
- func ResolveProtoFiles(ws *Workspace, target BazelTarget) []string
- type BazelError
- type BazelQuerier
- func (q *BazelQuerier) BuildQueryResult(ctx context.Context, targets []string) (*QueryResult, error)
- func (q *BazelQuerier) FindProtoTargets(ctx context.Context, pattern string) ([]string, error)
- func (q *BazelQuerier) GetDeps(ctx context.Context, target string) ([]string, error)
- func (q *BazelQuerier) GetProtoSources(ctx context.Context, target string) ([]string, error)
- func (q *BazelQuerier) GetTransitiveDeps(ctx context.Context, target string) ([]string, error)
- func (q *BazelQuerier) SetBazelPath(path string)
- type BazelTarget
- type ExistingBuildInfo
- type GeneratedBuild
- type Generator
- type Integrator
- func (it *Integrator) CreateSyncPlan(ctx context.Context, targets []BazelTarget, languages []string, ...) (*SyncPlan, error)
- func (it *Integrator) DiscoverProtoTargets(ctx context.Context, patterns []string) ([]BazelTarget, error)
- func (it *Integrator) GetSyncMode() SyncMode
- func (it *Integrator) GetWorkspace() *Workspace
- func (it *Integrator) ResolveProtoFilePaths(targets []BazelTarget) []string
- func (it *Integrator) SetBazelPath(path string)
- func (it *Integrator) SyncAfterBuild(ctx context.Context, targets []BazelTarget, languages []string, ...) error
- func (it *Integrator) WriteBuildFiles(builds []GeneratedBuild) error
- type LanguageBinding
- type QueryResult
- type SyncMode
- type SyncPlan
- type Workspace
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FindBuildFiles ¶
FindBuildFiles discovers all BUILD and BUILD.bazel files under root.
func HasBazelFile ¶
HasBazelFile returns true if the specific directory contains a BUILD file.
func IsBazelAvailable ¶
func IsBazelAvailable() bool
IsBazelAvailable checks if the bazel binary is available in PATH.
func IsBazelWorkspace ¶
IsBazelWorkspace returns true if the given directory (or a parent) is a Bazel workspace.
func ResolveProtoFiles ¶
func ResolveProtoFiles(ws *Workspace, target BazelTarget) []string
ResolveProtoFiles resolves the actual file paths for a target's srcs, relative to the workspace root and the target's package directory. For filegroup targets with glob patterns, it expands the globs on disk.
Types ¶
type BazelError ¶
BazelError wraps errors from bazel commands.
func (*BazelError) Error ¶
func (e *BazelError) Error() string
func (*BazelError) Unwrap ¶
func (e *BazelError) Unwrap() error
type BazelQuerier ¶
type BazelQuerier struct {
// contains filtered or unexported fields
}
BazelQuerier runs `bazel query` / `bazel cquery` to inspect the build graph.
func NewQuerier ¶
func NewQuerier(workspaceRoot string) *BazelQuerier
NewQuerier creates a querier rooted at the given workspace.
func (*BazelQuerier) BuildQueryResult ¶
func (q *BazelQuerier) BuildQueryResult(ctx context.Context, targets []string) (*QueryResult, error)
BuildQueryResult runs bazel query for a set of targets and returns a structured QueryResult with deps and source files.
func (*BazelQuerier) FindProtoTargets ¶
FindProtoTargets uses `bazel query` to find all proto_library targets.
func (*BazelQuerier) GetProtoSources ¶
GetProtoSources returns the proto source files for a target using --output=xml.
func (*BazelQuerier) GetTransitiveDeps ¶
GetTransitiveDeps returns all transitive deps of a target.
func (*BazelQuerier) SetBazelPath ¶
func (q *BazelQuerier) SetBazelPath(path string)
SetBazelPath overrides the bazel binary path.
type BazelTarget ¶
type BazelTarget struct {
// Name is the Bazel target name (e.g., "user_proto").
Name string
// Rule is the Bazel rule name (e.g., "proto_library", "filegroup").
Rule string
// Package is the Bazel package path (e.g., "//proto/user").
Package string
// Srcs lists source files declared in srcs = [...].
Srcs []string
// Deps lists dependency labels declared in deps = [...].
Deps []string
// Visibility lists visibility labels.
Visibility []string
// StripImportPrefix is the strip_import_prefix attribute.
StripImportPrefix string
// ImportPrefix is the import_prefix attribute.
ImportPrefix string
// ProtoSourceRoot is the proto_source_root attribute.
ProtoSourceRoot string
// Tags are build tags.
Tags []string
// Extra holds any additional attributes as key-value pairs.
Extra map[string]string
// GlobPatterns holds the glob patterns from srcs = glob([...]) if present.
GlobPatterns []string
}
BazelTarget represents a target parsed from a BUILD/BUILD.bazel file.
func FilterLangProtoTargets ¶
func FilterLangProtoTargets(targets []BazelTarget, lang string) []BazelTarget
FilterLangProtoTargets returns language-specific proto library targets.
func FilterProtoTargets ¶
func FilterProtoTargets(targets []BazelTarget) []BazelTarget
FilterProtoTargets returns targets that provide proto files (proto_library rules and filegroups with proto srcs/globs).
func ParseBuildFile ¶
func ParseBuildFile(path string, pkg string) ([]BazelTarget, error)
ParseBuildFile parses a BUILD/BUILD.bazel file and extracts proto_library targets.
func (BazelTarget) IsProtoSource ¶ added in v1.30.1
func (t BazelTarget) IsProtoSource() bool
IsProtoSource returns true if the target provides proto files (either proto_library or a filegroup with proto globs).
type ExistingBuildInfo ¶ added in v1.30.1
type ExistingBuildInfo struct {
// Path is the file path.
Path string
// Targets are all targets already defined in the file.
Targets []BazelTarget
// HasBuffaloMarker is true if the file contains "Generated by Buffalo".
HasBuffaloMarker bool
// RawContent is the file content.
RawContent string
}
ExistingBuildInfo holds parsed information about an existing BUILD.bazel file that should not be overwritten but may need to be updated.
func ReadExistingBuild ¶ added in v1.30.1
func ReadExistingBuild(path string) (*ExistingBuildInfo, error)
ReadExistingBuild reads and parses an existing BUILD.bazel file.
type GeneratedBuild ¶
type GeneratedBuild struct {
// Path is the relative path where the BUILD.bazel should be written.
Path string
// Content is the rendered BUILD.bazel content.
Content string
// Bindings are the language bindings declared in this BUILD file.
Bindings []LanguageBinding
}
GeneratedBuild represents a BUILD.bazel file to be written for generated code.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator creates BUILD.bazel files for generated protobuf code.
func NewGenerator ¶
NewGenerator creates a new BUILD.bazel generator.
func (*Generator) GenerateBuildFiles ¶
func (g *Generator) GenerateBuildFiles(targets []BazelTarget, languages []string, outputDir string) ([]GeneratedBuild, error)
GenerateBuildFiles produces BUILD.bazel files for the generated code based on the proto_library targets that were compiled and the target languages.
func (*Generator) GenerateFilegroupBuilds ¶ added in v1.30.1
func (g *Generator) GenerateFilegroupBuilds(languages []string, outputDir string) ([]GeneratedBuild, error)
GenerateFilegroupBuilds generates BUILD.bazel files for filegroup mode. In this mode Buffalo owns proto compilation and creates: - filegroup targets for generated .rs/.go/.py files (usable via compile_data) - language library targets (py_library, go_library) where applicable
func (*Generator) SetPreserveExisting ¶ added in v1.30.1
SetPreserveExisting controls whether existing non-Buffalo BUILD files are kept.
type Integrator ¶
type Integrator struct {
// contains filtered or unexported fields
}
Integrator is the main entry point for Buffalo ↔ Bazel integration. It detects a Bazel workspace, discovers proto_library targets, resolves proto files, and after compilation generates BUILD.bazel files.
Two modes of operation:
proto_library mode: Bazel defines proto_library rules, Buffalo discovers them and generates language-specific BUILD targets (go_proto_library, etc.).
filegroup mode: Bazel declares proto sources via filegroup(glob()), Buffalo compiles them and generates filegroup/library BUILD targets for downstream services (compile_data, deps).
func NewIntegrator ¶
func NewIntegrator(dir string) (*Integrator, error)
NewIntegrator creates an Integrator for the given directory. Returns (nil, nil) if no Bazel workspace is detected.
func NewIntegratorFromWorkspace ¶
func NewIntegratorFromWorkspace(ws *Workspace) *Integrator
NewIntegratorFromWorkspace creates an Integrator from an already-detected workspace.
func (*Integrator) CreateSyncPlan ¶
func (it *Integrator) CreateSyncPlan(ctx context.Context, targets []BazelTarget, languages []string, outputDir string) (*SyncPlan, error)
CreateSyncPlan builds a plan describing what Buffalo will compile and what BUILD files it will generate.
func (*Integrator) DiscoverProtoTargets ¶
func (it *Integrator) DiscoverProtoTargets(ctx context.Context, patterns []string) ([]BazelTarget, error)
DiscoverProtoTargets finds all proto-providing targets in the workspace. Uses `bazel query` when available, otherwise falls back to file parsing. Auto-detects the sync mode based on discovered targets.
func (*Integrator) GetSyncMode ¶ added in v1.30.1
func (it *Integrator) GetSyncMode() SyncMode
GetSyncMode returns the detected sync mode.
func (*Integrator) GetWorkspace ¶
func (it *Integrator) GetWorkspace() *Workspace
GetWorkspace returns the detected workspace.
func (*Integrator) ResolveProtoFilePaths ¶
func (it *Integrator) ResolveProtoFilePaths(targets []BazelTarget) []string
ResolveProtoFilePaths resolves all proto-providing targets to actual file paths on disk, relative to the workspace root.
func (*Integrator) SetBazelPath ¶
func (it *Integrator) SetBazelPath(path string)
SetBazelPath sets a custom bazel binary path.
func (*Integrator) SyncAfterBuild ¶
func (it *Integrator) SyncAfterBuild(ctx context.Context, targets []BazelTarget, languages []string, outputDir string) error
SyncAfterBuild is called after Buffalo compilation completes. It generates and writes BUILD.bazel files for the generated code.
func (*Integrator) WriteBuildFiles ¶
func (it *Integrator) WriteBuildFiles(builds []GeneratedBuild) error
WriteBuildFiles writes the generated BUILD.bazel files to disk. Existing non-Buffalo BUILD files are preserved.
type LanguageBinding ¶
type LanguageBinding struct {
// Language is the target language (e.g., "go", "python", "cpp", "rust", "typescript").
Language string
// Rule is the Bazel rule to generate (e.g., "go_proto_library").
Rule string
// TargetName is the generated target name.
TargetName string
// ProtoTarget is the label of the source proto_library.
ProtoTarget string
// Deps are language-specific dependencies.
Deps []string
// Importpath is language-specific import path (Go module, Python package, etc.).
Importpath string
// Options are extra rule attributes.
Options map[string]string
}
LanguageBinding maps a proto_library target to language-specific generated library targets (go_proto_library, py_proto_library, etc.).
type QueryResult ¶
type QueryResult struct {
// Targets lists discovered target labels.
Targets []string
// Deps maps a target label to its transitive dependency labels.
Deps map[string][]string
// ProtoFiles maps a target label to its resolved proto source files.
ProtoFiles map[string][]string
}
QueryResult holds results from `bazel query` or `bazel cquery`.
type SyncMode ¶ added in v1.30.1
type SyncMode string
SyncMode describes how Buffalo cooperates with Bazel.
type SyncPlan ¶
type SyncPlan struct {
// TargetsToCompile lists proto_library targets to compile.
TargetsToCompile []BazelTarget
// BuildFilesToGenerate lists BUILD.bazel files to create/update.
BuildFilesToGenerate []GeneratedBuild
// Languages are the target languages.
Languages []string
// OutputDir is the output root.
OutputDir string
// Mode is the sync mode (proto_library or filegroup).
Mode SyncMode
}
SyncPlan describes what Buffalo will do to synchronize with Bazel.
type Workspace ¶
type Workspace struct {
// Root is the absolute path to the workspace root.
Root string
// Type is "bzlmod" (MODULE.bazel) or "workspace" (WORKSPACE/WORKSPACE.bazel).
Type string
// ModuleName is the module name from MODULE.bazel (bzlmod only).
ModuleName string
// ProtoTargets are all proto_library targets discovered in the workspace.
ProtoTargets []BazelTarget
// BuildFiles maps Bazel package paths to their BUILD file paths on disk.
BuildFiles map[string]string
}
Workspace describes a detected Bazel workspace.
func DetectWorkspace ¶
DetectWorkspace searches upward from dir looking for a Bazel workspace root. Returns nil if no workspace is found.