---

name: developing-bazel-rules description: Use when creating custom Bazel rules, toolchains, providers, or aspects. Use when extending Bazel for new languages, build systems, or custom actions. Use when debugging Starlark rule implementations or understanding Bazel build phases.

Developing Bazel Rules

Overview

Bazel rules define how to transform inputs into outputs through actions. A rule has an implementation function executed during analysis phase that registers actions for execution phase.

Core principle: Rules don't execute commands directly - they register actions that Bazel executes later based on dependency analysis.

When to Use

• Creating rules for new languages or tools
• Building custom toolchains
• Implementing providers for dependency propagation
• Creating aspects for cross-cutting concerns
• Wrapping existing tools with Bazel

Build Phases

Quick Start: Minimal Rule

Copy# my_rules.bzl
def _my_compile_impl(ctx):
    output = ctx.actions.declare_file(ctx.label.name + ".out")
    ctx.actions.run(
        mnemonic = "MyCompile",
        executable = ctx.executable._compiler,
        arguments = ["-o", output.path] + [f.path for f in ctx.files.srcs],
        inputs = ctx.files.srcs,
        outputs = [output],
    )
    return [DefaultInfo(files = depset([output]))]

my_compile = rule(
    implementation = _my_compile_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        "_compiler": attr.label(
            default = "//tools:compiler",
            executable = True,
            cfg = "exec",
        ),
    },
)

Core Concepts

Providers - Passing Data Between Rules

Providers are the mechanism for rules to communicate:

CopyMyInfo = provider(
    doc = "Information from my_library targets",
    fields = {
        "files": "depset of output files",
        "transitive_files": "depset of all transitive files",
    },
)

def _impl(ctx):
    # Collect from dependencies
    transitive = [dep[MyInfo].transitive_files for dep in ctx.attr.deps]

    # Return new provider
    return [
        DefaultInfo(files = depset([output])),
        MyInfo(
            files = depset([output]),
            transitive_files = depset([output], transitive = transitive),
        ),
    ]

Require providers in deps:

Copy"deps": attr.label_list(providers = [MyInfo])

Depsets - Efficient Transitive Collections

Use depsets to avoid quadratic complexity:

Copy# GOOD: O(1) per target
transitive_srcs = depset(
    direct = ctx.files.srcs,
    transitive = [dep[MyInfo].srcs for dep in ctx.attr.deps],
)

# BAD: O(n) copying - becomes O(n^2) across graph
transitive_srcs = list(ctx.files.srcs)
for dep in ctx.attr.deps:
    transitive_srcs.extend(dep[MyInfo].srcs.to_list())

Only call .to_list() in binary rules, never in libraries.

Actions - Registering Work

Copy# Run executable (preferred)
ctx.actions.run(
    mnemonic = "Compile",
    executable = ctx.executable._tool,
    arguments = [args],
    inputs = inputs,
    outputs = [output],
)

# Use args builder for large inputs
args = ctx.actions.args()
args.add("-o", output)
args.add_all(srcs)  # Deferred expansion - efficient!

# Write file content
ctx.actions.write(output, content, is_executable = True)

Attributes - Rule Parameters

Private attributes (underscore prefix) for implicit deps:

Copy"_stdlib": attr.label(default = "//go:stdlib")

cfg for tools:

Copy"_compiler": attr.label(executable = True, cfg = "exec")

Implementation Checklist

1. Get toolchain (if using): ctx.toolchains["//my:type"]
2. Access inputs: ctx.files.srcs, ctx.attr.deps
3. Declare outputs: ctx.actions.declare_file()
4. Build depsets for transitive data
5. Register actions: ctx.actions.run()
6. Return providers: [DefaultInfo(...), MyInfo(...)]

Common Mistakes

Reference Files

See references/ for detailed guides:

• api-reference.md - Starlark API quick reference
• providers.md - Provider design patterns
• toolchains.md - Toolchain development
• testing.md - Testing Bazel rules
• go-patterns.md - Patterns from rules_go