Bazel BUILD Files

External

• https://bazel.build/concepts/build-files
• https://bazel.build/reference/be/overview

Internal

• Bazel Concepts

Overview

A BUILD is a short program, an interpretable list of Starlark statements.

The BUILD file specified of how the files of a Bazel package can be used to produce artifacts.

There is a one-to-one relationship between a BUILD file and a Bazel package. The BUILD file resides in the package directory.

The BUILD file defines the package's targets.

The BUILD file can be named BUILD or BUILD.bazel and where both exist, BUILD.bazel takes precedence.

Example

A simple BUILD file that produces an executable whose source is written in Go and that are fist built into a library:

Simple BUILD File for a Go Project

General Syntax

Variables must be defined before they are used.

The relative order in which build rules are declared is unimportant.

The file cannot contain function definitions, for or if control statements. List comprehensions and if expressions are allowed.

Starlark programs can't perform arbitrary I/O, which makes the interpretation of the BUILD files hermetic.

BUILD files need to be updated whenever the dependencies of the underlying code change. IntelliJ does that via the "Sync" functionality.

Rules

A rule specifies the relationship between a set of input and a set of output files.

The inputs to a rule may be source files, but they also may be the outputs of other rules. It this case is said that the input of a rule is other rule.

The output files of rule always belong to the same package as the rule itself. It is not possible to generate files into another package. It is not uncommon for a rule's inputs to come from another package, though.

When a build rule function is executed, it creates a new target in the graph, which can later referred using a label, declared as name in the rule declaration.

The majority of build rules come in families, grouped together by language. For example, go_binary, go_library and go_test are the build rules for Go binaries, libraries, and tests, respectively.

*_binary rules build executable in a given language. After a build, the executable will reside in the build tool's binary output tree at the corresponding name for the rule's label, so //my:program would appear at $(BINDIR)/my/program. *_test rules are a specialization of a *_binary rule used for automated testing. *_library rules specify separately-compiled modules in the given programming language.

Go Rules

https://github.com/bazelbuild/rules_go

Core Rules

https://github.com/bazel-contrib/rules_go/blob/master/docs/go/core/rules.md

Three core rules may be used to build most projects: go_library, go_binary and go_test. These rules reimplement the low level commands of a normal go build invocation: compiling package's source files to archives, then linking archives into go binary.

go_library

go_library

go_binary

go_binary

go_test

go_test

go_source

https://github.com/bazel-contrib/rules_go/blob/master/docs/go/core/rules.md#go_source

go_path

https://github.com/bazel-contrib/rules_go/blob/master/docs/go/core/rules.md#go_path

Gazelle

Generating BUILD files with Gazelle

Gazelle | Generating BUILD Files

Repository Rules with Gazelle

Gazelle | Repository Rules

Build-time Code Analysis with nogo

nogo

Protocol Buffers

Protocol Buffers Rules

Other Go Rules

Uber gomock

Uber gomock Rule

Functions

Functions can be declared in .bzl files.

Extensions

Bazel extensions are files ending in .bzl. Symbols from an extension are imported with the load() statement:

load("//foo/bar:file.bzl", "some_library")
load("//meta/rules:go.bzl", "go_library")
load("//somewhere/gomock:defs.bzl", "gomock")

some_library(
  ...
)

go_library(
  ...
)

gomock(
  ...
)

This can be used to lad new build rules, functions or constants.

TODO: https://bazel.build/concepts/build-files#load

Dependency Management

The dependencies can be autogenerated with Gazelle. Add them to the Go source file and run gazelle.