4.2.1 Rule Function

A rule function is the declaration of a new target kind. It gives Bazel a callable symbol for BUILD files, names the implementation function Bazel will run during analysis, declares the attributes users may set, and defines the boundary for outputs and providers.¹ The implementation does not execute the compiler, formatter, or generator itself. It describes the actions Bazel may run later, if the requested outputs need them.²

The Smallest Useful Rule

A Starlark rule starts in a .bzl file with two parts: a private implementation function and a global value assigned from rule().³

def _mini_message_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name + ".txt")
    ctx.actions.write(
        output = out,
        content = ctx.attr.message + "\n",
    )
    return [DefaultInfo(files = depset([out]))]

mini_message = rule(
    implementation = _mini_message_impl,
    attrs = {
        "message": attr.string(
            default = "hello",
            doc = "Text written into the generated file.",
        ),
    },
    doc = "Writes a small text file.",
)

The name mini_message is the rule kind users load and call from BUILD files. Each call instantiates a target with a normal name plus the rule's declared attributes.⁴

load("//tools/messages:defs.bzl", "mini_message")

mini_message(
    name = "greeting",
    message = "hello architect",
)

Even this tiny rule shows the whole skeleton: rule() defines the public shape, _mini_message_impl(ctx) receives the analyzed target, ctx.actions.declare_file() names a generated output, ctx.actions.write() registers the generating action, and DefaultInfo(files = ...) tells Bazel which file belongs to the target's default build result.⁵ When a shell one-liner is enough, stay with 3.4.1 Genrule (The Escape Hatch). Reach for a custom rule when you need providers, toolchains, or a reusable target kind.

rule() Defines The Target Contract

The rule() call is not a helper function that runs when the target builds. It creates a rule symbol, and Bazel requires that symbol to be stored in a global variable in a .bzl file.⁶ The global variable's name becomes the rule's public name, which is why production rulesets treat these exported rule symbols as API.

The most important parameters for a first rule are:

Other rule() parameters matter later: toolchains and exec_groups connect a rule to platform-aware tool selection, build_setting turns a rule into a typed configuration flag, and provides advertises the providers an implementation promises to return.¹¹ This article keeps those as boundary markers. Toolchain access belongs in 4.6.1 Platform Model for Rule Authors and 4.6.2 Defining, Registering & Accessing Toolchains. Build settings belong in 4.7.1 Build Settings for Rule Authors.

Normal build rules are also a different extension point from repository rules and module extensions. A build rule creates targets inside a package and runs in analysis. A repository rule materializes an external repository on demand during loading, so Bazel can then load its packages. 4.9 Repository Rules covers that mechanism. A module extension aggregates MODULE.bazel tags and usually calls repository rules, covered in 4.10 Authoring Module Extensions.

Attributes Are The BUILD-File API

Attributes are the public inputs to the rule. They can be simple values, such as attr.string(), attr.int(), and attr.bool(), or dependency attributes such as attr.label() and attr.label_list().¹² Dependency attributes add edges to the target graph: a label string in BUILD becomes a Target object in ctx.attr during analysis.¹³

Use the attribute schema to say what the rule actually accepts:

my_report = rule(
    implementation = _my_report_impl,
    attrs = {
        "src": attr.label(
            allow_single_file = [".json"],
            mandatory = True,
            doc = "Input JSON file.",
        ),
        "deps": attr.label_list(
            providers = [ReportInfo],
            doc = "Reports to merge before rendering.",
        ),
        "_renderer": attr.label(
            default = Label("//tools/report:renderer"),
            executable = True,
            cfg = "exec",
        ),
    },
)

Here src accepts one .json file, deps requires each dependency to expose ReportInfo, and _renderer is a private implicit dependency. Private attributes start with _, cannot be set at the call site, and must have defaults. They are commonly used for implementation tools.¹⁴ Because _renderer is executable, cfg = "exec" makes the tool build for the execution platform rather than the target platform.¹⁵ Full toolchain resolution is usually the better production answer once the tool varies by platform or ruleset setup, but a private exec-configured tool is the simplest first boundary.

The providers parameter on label attributes is an early design tool, not just validation polish. If a dependency must supply ReportInfo, encode that in attr.label_list(providers = [ReportInfo]) instead of checking later with a vague fail(). The attribute now states the dependency contract where users and documentation tools can see it.¹⁶

ctx Is The Analysis Handle

The implementation function takes exactly one parameter, conventionally named ctx.¹⁷ ctx lives only for that implementation call and exposes the target's label, attribute values, configuration, dependencies' providers, output declarations, and action APIs.¹⁸

The accessors differ by what you declared:

This is the first big difference from macros. A macro sees raw loading-phase values and stamps out other targets. A rule implementation sees configured attributes and analyzed dependency providers, so it can create a new target contract instead of just reshaping declarations. That is the rule side of the decision from 4.1.1 Macro vs Rule Decision Framework, grounded in the core/ruleset split introduced in P.2.3 Core vs Rulesets.

Outputs Must Cross An Action Boundary

Generated files are represented by File objects. During analysis, the implementation may declare output files or directories, but it cannot read or write their contents directly.²⁶ Every generated file must be produced by exactly one action. A file declared with no generating action is an error, and files an action writes outside its declared outputs are not available to consumers.²⁷

There are two common output shapes:

# Derived output: label is internal to the rule implementation.
out = ctx.actions.declare_file(ctx.label.name + ".txt")

# Predeclared output: user chooses a label through attr.output().
out = ctx.outputs.out

Use ctx.actions.declare_file() when the rule can derive a stable output name from the target. Use attr.output() when the user needs to choose the output label in BUILD. The deprecated outputs parameter on rule() still appears in old code, but current API docs direct new rules toward attr.output() or output groups instead.²⁸

Actions themselves are the next item, 4.2.2 Actions. For this article, keep one invariant: declaring an output only creates a File object. Registering an action is what tells Bazel how that file will be produced.

Providers Are The Return Boundary

A rule implementation returns a list of providers.²⁹ DefaultInfo is the universal provider every rule author should understand: its files field is the depset of default outputs built when the target is requested, and its executable and runfiles fields define the basic runtime contract for runnable targets.³⁰

For a first rule, return DefaultInfo(files = depset([out])) whenever the rule produces a normal file. Without an explicit DefaultInfo(files = ...), Bazel falls back to predeclared outputs, but rules that register actions should still expose useful default outputs so bazel build //pkg:target exercises the rule directly.³¹

Custom providers come later in 4.2.7 Custom Provider Declaration and 4.2.8 Provider-as-Interface Pattern. The early design rule is simple: return DefaultInfo for files Bazel and users should build by default. Add a custom provider only when another rule needs semantic information that file paths alone cannot express.

For a complete target kind built from this skeleton, inspect the mini-ruleset's glyph_library: its attrs enter through ctx, its implementation declares actions and outputs, and the rule returns both DefaultInfo and a domain provider.

When you want to isolate one design step at a time, compare the tagged versions of rules_go_simple: v1 starts with one executable rule, v2 adds a library and provider flow, and later tags add runfiles, execution-time tooling, toolchains, and a module extension.³² This is a teaching progression, not a production Go ruleset API.