# How to Configure Build Tags in Generated protobuf Go Code with protoc-gen-go-lite

> Easily configure build tags in generated protobuf Go code using protoc-gen-go-lite. Add //go:build directives with simple protoc parameter for optimized Go builds.

- Repository: [Aperture Robotics/protobuf-go-lite](https://github.com/aperturerobotics/protobuf-go-lite)
- Tags: how-to-guide
- Published: 2026-02-25

---

**Use the `--go-lite_out=buildTag=<tag>:.` parameter when invoking `protoc` to inject a `//go:build` directive at the top of every generated [`.pb.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/.pb.go) file.**

The `protoc-gen-go-lite` plugin from the `aperturerobotics/protobuf-go-lite` repository provides a lightweight alternative to the official Go protobuf compiler. When you need to conditionally compile generated protobuf code—such as excluding it from certain build targets or enabling alternative implementations—configuring build tags directly during code generation streamlines your workflow.

## Understanding the Build Tag Mechanism

The plugin exposes a `buildTag` option that maps directly to Go's build constraint syntax. When provided, the generator prepends a `//go:build` line followed by the legacy `// +build` line for backward compatibility.

### Where the Option is Defined

The command-line flag is registered in [`cmd/protoc-gen-go-lite/main.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/cmd/protoc-gen-go-lite/main.go):

```go
// cmd/protoc-gen-go-lite/main.go
f.StringVar(&cfg.BuildTag, "buildTag", "", "the go:build tag to set on generated files")

```

This populates the `BuildTag` field in the `Config` struct defined in [`generator/generator.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/generator/generator.go).

### How the Tag is Applied

The actual injection happens in [`generator/helpers.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/generator/helpers.go) via the `addBuildTag` helper function. When `cfg.BuildTag` is non-empty, the generator writes:

```go
//go:build <your-tag>
// +build <your-tag>

```

This appears immediately before the `package` declaration in every generated [`.pb.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/.pb.go) file.

## Configuring Build Tags in protoc-gen-go-lite

To configure build tags, pass the `buildTag` key inside the `--go-lite_out` parameter string using the `key=value` syntax.

### Basic Syntax for Single Tags

Supply the tag as a comma-separated parameter before the colon separator:

```bash
protoc -I=. \
  --go-lite_out=buildTag=lite:. \
  myproto.proto

```

This generates [`myproto.pb.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/myproto.pb.go) with the following header:

```go
//go:build lite
// +build lite

package myproto

```

### Combining with Other Options

The `buildTag` parameter works alongside other `protoc-gen-go-lite` options. For example, combining with `allowEmpty`:

```bash
protoc -I=. \
  --go-lite_out=buildTag=lite,allowEmpty=true:. \
  myproto.proto

```

Parameter order in the comma-separated list does not affect functionality.

### Using Build Tags in Makefiles

For build automation, define the tag as a variable:

```makefile
PROTOC      = protoc
PROTO_FILES = $(wildcard *.proto)
GO_OUT      = .

# Default build tag, override with make TAG=debug

TAG ?= lite

all:
	$(PROTOC) -I=. \
	  --go-lite_out=buildTag=$(TAG):$(GO_OUT) \
	  $(PROTO_FILES)

```

Running `make` uses the `lite` tag, while `make TAG=debug` generates files with `//go:build debug`.

## Disabling Build Tags

To generate files without any build constraints, either omit the `buildTag` parameter entirely or pass an empty value:

```bash
protoc -I=. --go-lite_out=:. myproto.proto

```

Since the default value for `buildTag` is an empty string, the `addBuildTag` helper skips injection when the value is blank, resulting in standard generated files without build directives.

## Summary

- **Flag Location**: The `buildTag` option is defined in [`cmd/protoc-gen-go-lite/main.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/cmd/protoc-gen-go-lite/main.go) and stored in the `Config` struct in [`generator/generator.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/generator/generator.go).
- **Syntax**: Pass `buildTag=<tag>` inside the `--go-lite_out` parameter string before the colon separator.
- **Output**: Generates `//go:build <tag>` and `// +build <tag>` at the top of every [`.pb.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/.pb.go) file via [`generator/helpers.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/generator/helpers.go).
- **Default Behavior**: Omitting the parameter or using an empty value generates files without build constraints.

## Frequently Asked Questions

### What file does protoc-gen-go-lite modify to add build tags?

The plugin modifies every generated [`.pb.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/.pb.go) file by prepending the build constraint lines. The logic resides in [`generator/helpers.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/generator/helpers.go), specifically in the `addBuildTag` function, which checks the `BuildTag` field from the `Config` struct defined in [`generator/generator.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/generator/generator.go).

### Can I use multiple build tags with protoc-gen-go-lite?

The current implementation accepts a single string value for the `buildTag` parameter. To use multiple build constraints, pass them as a single space-separated string within the parameter value, such as `buildTag="linux amd64"`. This generates `//go:build linux amd64` which Go interprets as requiring both constraints.

### How do I conditionally compile protobuf code in Go?

Use the `buildTag` option when generating code with `protoc-gen-go-lite` to inject `//go:build` constraints. Then use the `go build -tags=<tag>` command to include or exclude the generated files from compilation. Files with build tags are only compiled when the tag is explicitly provided during the build process.

### Where is the build tag configuration stored in the generator?

The configuration is stored in the `BuildTag` field of the `Config` struct located in [`generator/generator.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/generator/generator.go). This field is populated from the command-line flag defined in [`cmd/protoc-gen-go-lite/main.go`](https://github.com/aperturerobotics/protobuf-go-lite/blob/main/cmd/protoc-gen-go-lite/main.go), where the `buildTag` flag binds directly to `cfg.BuildTag` via `f.StringVar`.