developing-bazel-rules

What this skill does

# 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

| Phase | What Happens | Rule Author's Role |
|-------|--------------|-------------------|
| **Loading** | `BUILD` files evaluated, rules instantiated | Define rule with `rule()`, macros expand |
| **Analysis** | Implementation functions run | Register actions, return providers |
| **Execution** | Actions run (if needed) | Actions produce outputs |

## Quick Start: Minimal Rule

```python
# 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:

```python
MyInfo = 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:**
```python
"deps": attr.label_list(providers = [MyInfo])
```

### Depsets - Efficient Transitive Collections

Use depsets to avoid quadratic complexity:

```python
# 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

```python
# 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

| Type | Use Case |
|------|----------|
| `attr.label_list` | File/target inputs (`srcs`, `deps`) |
| `attr.label` | Single target (`_compiler`) |
| `attr.string` | Config value (`importpath`) |
| `attr.bool` | Toggle (`cgo = True`) |

**Private attributes** (underscore prefix) for implicit deps:
```python
"_stdlib": attr.label(default = "//go:stdlib")
```

**cfg for tools:**
```python
"_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

| Mistake | Fix |
|---------|-----|
| Flattening depsets in library | Keep as depset, flatten only in binary |
| Missing `cfg = "exec"` for tools | Add `cfg = "exec"` to tool attributes |
| Not returning DefaultInfo | Always return DefaultInfo with files |
| Reading files in analysis | Files can only be read by actions |
| Action without outputs | All actions must produce output files |

## 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