buck2-rule-basics

Original source / Raw SKILL.md

---
name: buck2-rule-basics
description: Guide users through writing their first Buck2 rule to learn fundamental concepts including rules, actions, targets, configurations, analysis, and select(). Use this skill when users want to learn Buck2 basics hands-on or need help understanding rule writing.
---

@nolint

# Buck2 Rule Basics - Interactive Tutorial

## Overview

This is an **interactive, step-by-step tutorial** that teaches Buck2
fundamentals through hands-on practice. You'll guide users through writing a
simple text processing rule that converts text to uppercase, explaining core
concepts as they encounter them.

## Reference Materials

This skill includes additional reference documentation that you can use to answer deeper questions:

- **`references/concepts.md`** - Deep dive into Buck2 core concepts including:
  - The Buck2 build model (load, configuration, analysis, execution phases)
  - Targets in depth (unconfigured vs configured, cells, dependencies)
  - Artifacts (source vs build artifacts, bound vs unbound)
  - Actions (properties, caching, inputs/outputs)
  - Providers (built-in and custom, provider propagation)
  - Configurations (platforms, select() resolution, multi-platform builds)
  - Analysis phase details
  - Build graph structure and queries (uquery, cquery, aquery)

- **`references/advanced_patterns.md`** - Production-ready patterns including:
  - Custom providers (library with transitive headers)
  - Transitive dependencies (collection patterns, transitive sets/tsets)
  - Toolchain dependencies (defining and using toolchains)
  - Multiple outputs (output directories, sub-targets)
  - Command line building (complex commands, conditional arguments)
  - Configuration-dependent rules
  - Testing rules (test runners, test data)

**When to use these references:**
- User asks "how does X work in Buck2?" → Check `concepts.md`
- User asks "what's the best way to do Y?" → Check `advanced_patterns.md`
- User wants to go beyond the tutorial → Direct them to these files
- User encounters advanced concepts → Read relevant sections to explain

Always read from these files when users ask questions that go beyond the basic tutorial content.

## Critical: Interactive Teaching Approach

**DO NOT dump all content at once!** This is an interactive tutorial. Follow
these rules:

### 1. Always Start by Assessing Current State

When the skill launches, FIRST check what the user has already done:

- Check if tutorial directory exists and what files are present
- Read existing files to understand their progress
- Determine which step they're on (or if starting fresh)
- Ask the user if they want to start from scratch or continue

### 2. Present One Step at a Time

- Introduce ONE concept/step
- Implement the code for that step
- Test it together
- Explain what happened
- **Show file changes**: After each step, summarize what files were created/modified
- **Remind about editor**: Tell users they can open the files in their editor to see the changes
- STOP and wait for user confirmation to continue

### 3. Use AskUserQuestion Between Major Steps

After completing each major step (1-8), ask the user:

- Do they understand the concept?
- Are they ready to move to the next step?
- Do they want to explore more about the current topic?

### 4. Be Adaptive

- If user seems confused, provide more examples
- If they're advanced, offer to skip basic explanations
- If they want to experiment, encourage it and help debug
- If they ask questions, answer them before moving forward

### 5. Track Progress Visually

Use TodoWrite to show:

- Which steps are completed ✓
- Current step (in progress)
- Upcoming steps
- This helps users see the journey

## Important: Use System Buck2 Command

This tutorial uses the **system `buck2` command**, NOT `./buck2.py`.

- Use: `buck2 build`, `buck2 test`, `buck2 cquery`, etc.
- Do NOT use: `./buck2.py` (that's for Buck2 development/self-bootstrap)

This ensures the tutorial works for all users with Buck2 installed.

## Tutorial Structure

The tutorial has 8 progressive steps:

### Step 0: Setup

Create a new directory for the tutorial and navigate into it:

**Run this:**

```bash
mkdir 'buck2-tutorial'
cd buck2-tutorial
```

All following steps will be done in this directory.

**Step 1: Create Minimal Rule Stub** - Returns empty DefaultInfo() **Step 2: Add
Source File Attribute** - Accept input files **Step 3: Declare Output
Artifact** - Promise to produce output (will error) **Step 4: Create an
Action** - Actually produce the output **Step 5: Understanding Targets** -
Unconfigured vs Configured **Step 6: Add Configuration Support** - Use select()
for platform-specific behavior **Step 7: Add Dependencies** - Make rules compose
**Step 8: Rules vs Macros** - Understand the difference

## Step-by-Step Implementation Guide

### Initial Setup (Always Do First)

```python
# 1. Determine working directory
# 2. Check if user has existing tutorial files
# 3. Create todo list showing all 8 steps
# 4. Ask user if they want to start fresh or continue
```

**Create todo list:**

```python
TodoWrite with 8 items (all pending initially)
```

**Check existing state:**

```python
- Does `uppercase.bzl` exist?
- Does `BUCK` exist?
- Does `input.txt` exist?
- If yes, read them to determine current step
```

**Ask user:**

```python
AskUserQuestion:
- "Start from scratch (will backup existing files)"
- "Continue from where I left off"
- "Review a specific step"
```

---

### Step 1: Create the Minimal Rule Stub

**Goal:** Get the simplest possible Buck2 rule working.

**What to do:**

1. Create `uppercase.bzl` with minimal implementation
2. Create `BUCK` file with target definition
3. Build it with `buck2 build`
4. Observe success (with warning about no outputs)

**Code to create:**

`uppercase.bzl`:

```starlark
# uppercase.bzl

def _uppercase_impl(ctx: AnalysisContext) -> list[Provider]:
    """Rule implementation function - called during analysis phase."""
    return [DefaultInfo()]

uppercase = rule(
    impl = _uppercase_impl,
    attrs = {},
)
```

`BUCK`:

```starlark
load(":uppercase.bzl", "uppercase")

uppercase(name = "hello")
```

**Testing:**

```bash
buck2 build :hello
# Expected: SUCCESS with warning "target does not have any outputs"
```

**Key concepts to explain AFTER successful build:**

- **Rule**: Defined with `rule()` function
- **Implementation function**: Takes `AnalysisContext`, returns `Provider` list
- **Analysis phase**: This runs during planning, not execution
- **DefaultInfo provider**: Minimum provider every rule must return

**Before moving on:**

```python
AskUserQuestion:
  question: "Ready to move to Step 2 where we'll accept input files?"
  options:
    - "Yes, let's continue"
    - "Explain these concepts more"
    - "Let me experiment first"
```

---

### Step 2: Add Source File Attribute

**Goal:** Make the rule accept an input file.

**What to do:**

1. Update `uppercase.bzl` to add `src` attribute
2. Update `BUCK` to pass a source file
3. Create `input.txt` test file
4. Build again

**Update `uppercase.bzl`:**

```starlark
def _uppercase_impl(ctx: AnalysisContext) -> list[Provider]:
    # Access the source file attribute
    src = ctx.attrs.src  # This is an Artifact

    return [DefaultInfo()]

uppercase = rule(
    impl = _uppercase_impl,
    attrs = {
        "src": attrs.source(),  # Declares this rule accepts a source file
    },
)
```

**Update `BUCK`:**

```starlark
load(":uppercase.bzl", "uppercase")

uppercase(
    name = "hello",
    src = "input.txt",
)
```

**Create `input.txt`:**

```
hello world
```

**Testing:**

```bash
buck2 build :hello
# Expected: SUCCESS (still no outputs, but accepts input now)
```

**Key concepts to explain:**

- **Attributes**: Defined in `attrs={}`, accessed via `ctx.attrs`
- **attrs.source()**: Declares an attribute accepting a source file
- **Artifact**: Represents a file (input or output)

**Before moving on:**

```python
AskUserQuestion:
  question: "Ready for Step 3 where we'll declare an output file?"
  options:
    - "Yes, continue"
    - "I have questions about attributes"
```

---

### Step 3: Declare Output Artifact

**Goal:** Declare that we'll produce an output (will cause expected error).

**What to do:**

1. Update implementation to declare output
2. Return it in DefaultInfo
3. Build and **expect failure**
4. Explain why it fails (declared but not produced)

**Update `uppercase.bzl` implementation:**

```starlark
def _uppercase_impl(ctx: AnalysisContext) -> list[Provider]:
    src = ctx.attrs.src

    # Declare an output artifact
    output = ctx.actions.declare_output("result.txt")

    # Return it as the default output
    return [DefaultInfo(default_output = output)]
```

**Testing:**

```bash
buck2 build :hello
# Expected: ERROR - "Artifact must be bound by now"
```

**Explain the error:** This error is **expected and good**! We declared an
output but haven't created an action to produce it. Buck2 is telling us: "You
promised an output, but didn't say how to make it!"

**Key concepts to explain:**

- **ctx.actions.declare_output()**: Declares an artifact that will be produced
- **default_output**: The main output users get when building
- **Declaration vs Production**: We declared it exists, but haven't created it
  yet

**Before moving on:**

```python
AskUserQuestion:
  question: "This error is expected! Ready for Step 4 where we'll fix it by creating an action?"
  options:
    - "Yes, let's create the action"
    - "Why did we get this error exactly?"
```

---

### Step 4: Create an Action

**Goal:** Actually produce the output file by running a command.

**What to do:**

1. Add shell script to transform input → output
2. Register action with `ctx.actions.run()`
3. Build and see it succeed
4. Check the output file content

**Update `uppercase.bzl` implementation:**

```starlark
def _uppercase_impl(ctx: AnalysisContext) -> list[Provider]:
    src = ctx.attrs.src
    output = ctx.actions.declare_output("result.txt")

    # Create a shell script that will run
    # Use Python to uppercase the file and write to output
    script = """
python3 -c "import sys; print(open(sys.argv[1]).read().upper(), end='')" "$1" > "$2"
"""

    # Register the action with Buck2
    ctx.actions.run(
        cmd_args([
            "/bin/bash",
            "-c",
            script,
            "--",
            src,  # Input artifact
            output.as_output(),  # Output artifact
        ]),
        category = "uppercase",  # Shows in buck2 output
    )

    return [DefaultInfo(default_output = output)]
```

**Testing:**

```bash
buck2 build :hello --show-full-output
# Expected: SUCCESS with output path shown

# Check the content
cat <output-path>
# Expected: HELLO WORLD
```

**Key concepts to explain:**

- **Action**: A command Buck2 will execute (bash script + Python)
- **cmd_args()**: Builds command line, handles artifacts properly
- **artifact.as_output()**: Marks artifact as output (Buck2 creates parent dirs)
- **ctx.actions.run()**: Registers action - doesn't execute yet, just declares
- **Shell redirection**: Use `>` in shell scripts (Buck2 doesn't support
  redirect_stdout)
- **Lazy execution**: Buck2 decides when/if to run based on what's needed

**Before moving on:**

```python
AskUserQuestion:
  question: "Great! Your rule now works. Ready to learn about targets and configurations?"
  options:
    - "Yes, let's learn about targets"
    - "Let me try modifying the rule first"
```

---

### Step 5: Understanding Targets

**Goal:** Understand target names, unconfigured vs configured targets.

**What to do:**

1. List available targets with `buck2 targets`
2. Understand the anatomy of target names
3. Query the target in unconfigured mode (`uquery`)
4. Query the target in configured mode (`cquery`)
5. Compare the differences

**Run commands:**

```bash
# List all targets in the current package
buck2 targets :

# Expected output shows targets like:
# fbcode//buck2/buck2-tutorial:hello
# fbcode//buck2/buck2-tutorial:goodbye
```

**Explain target name anatomy:**

A full Buck2 target name has three parts:

```
cell//package/path:target_name
└─┬┘ └─────┬──────┘ └────┬────┘
  │        │             └─ Target name (from 'name' attribute)
  │        └─────────────── Package path (directory containing BUCK file)
  └──────────────────────── Cell name (repository root)
```

**Examples with explanations:**

- `fbcode//buck2/buck2-tutorial:hello`
  - **Full target name** with all three parts explicitly specified
  - Always valid and unambiguous from anywhere
  - Use this when referring to targets from a different cell/repository

- `//buck2/buck2-tutorial:hello`
  - **Cell name omitted** - defaults to the current repository's cell
  - Since we're working in the fbcode repository, `//` is shorthand for `fbcode//`
  - Valid when referring to any target in the same repository/cell
  - This is the most common form you'll see in BUCK files

- `:hello`
  - **Cell and package path omitted** - only the target name
  - Only valid when you're in the same directory/package
  - Shortest form for referring to targets in the current BUCK file
  - When you run `buck2 build :hello` from the `buck2-tutorial` directory, Buck2 knows you mean `fbcode//buck2/buck2-tutorial:hello`

**Now query the targets:**

```bash
# Unconfigured - shows raw attributes
buck2 uquery :hello --output-attribute=src

# Configured - shows with platform config applied
buck2 cquery :hello --output-attribute=src
```

**Key concepts to explain:**

**Unconfigured Target** (`//path:name`):

- Raw definition from BUCK file
- `select()` expressions not yet resolved
- No platform-specific settings applied

**Configured Target** (`//path:name (cfg:...)`):

- Same target with specific configuration
- `select()` resolved based on platform (linux/windows/mac)
- Platform settings applied (os, cpu, compiler, etc.)

**Show the difference:**

- Unconfigured: `fbcode//buck2/buck2-tutorial:hello`
- Configured: `fbcode//buck2/buck2-tutorial:hello (cfg:dev-linux-x86_64-...)`

Notice the configuration suffix `(cfg:...)` is added when Buck2 applies platform-specific settings.

**Before moving on:**

```python
AskUserQuestion:
  question: "Ready to use select() to make your rule platform-aware?"
  options:
    - "Yes, show me select()"
    - "Tell me more about configurations"
```

---

### Step 6: Add Configuration Support with select()

**Goal:** Make the rule behave differently on different platforms.

**What to do:**

1. Add `output_name` attribute to the rule
2. Use `select()` in TARGETS to choose different names per platform
3. Query to see select() before and after resolution
4. Build and verify the platform-specific name is used

**Update rule in `uppercase.bzl`:**

```starlark
def _uppercase_impl(ctx: AnalysisContext) -> list[Provider]:
    src = ctx.attrs.src

    # Output filename can vary by platform
    output_name = ctx.attrs.output_name
    output = ctx.actions.declare_output(output_name)

    script = """
python3 -c "import sys; print(open(sys.argv[1]).read().upper(), end='')" "$1" > "$2"
"""

    ctx.actions.run(
        cmd_args([
            "/bin/bash",
            "-c",
            script,
            "--",
            src,
            output.as_output(),
        ]),
        category = "uppercase",
    )

    return [DefaultInfo(default_output = output)]

uppercase = rule(
    impl = _uppercase_impl,
    attrs = {
        "src": attrs.source(),
        "output_name": attrs.string(default = "result.txt"),
    },
)
```

**Update `BUCK` to use select():**

```starlark
load(":uppercase.bzl", "uppercase")

uppercase(
    name = "hello",
    src = "input.txt",
    output_name = select({
        "DEFAULT": "result.txt",
        "ovr_config//os:windows": "result_windows.txt",
        "ovr_config//os:linux": "result_linux.txt",
        "ovr_config//os:macos": "result_macos.txt",
    }),
)
```

**Testing:**

```bash
# See the raw select() expression
buck2 uquery :hello --output-attribute=output_name

# See the resolved value for your platform
buck2 cquery :hello --output-attribute=output_name

# Build with resolved configuration
buck2 build :hello --show-full-output
# Notice the output filename matches your OS!
```

**Key concepts to explain:**

- **select()**: Choose values based on configuration
- **Configuration keys**: Match against platform constraints (os, cpu, etc.)
- **DEFAULT**: Fallback if no other branch matches
- **Resolution**: During configuration phase, Buck2 picks one branch

**Before moving on:**

```python
AskUserQuestion:
  question: "Ready to learn about dependencies between targets?"
  options:
    - "Yes, show me dependencies"
    - "Let me try more select() examples"
```

---

### Step 7: Add Dependencies

**Goal:** Make rules that depend on other rules.

**What to do:**

1. Add `deps` attribute to the rule
2. Create a second target that depends on the first
3. Access dependency outputs in the rule implementation
4. Build and verify dependency graph

**Update rule in `uppercase.bzl`:**

```starlark
def _uppercase_impl(ctx: AnalysisContext) -> list[Provider]:
    src = ctx.attrs.src
    output_name = ctx.attrs.output_name
    output = ctx.actions.declare_output(output_name)

    # Collect outputs from dependencies
    dep_files = []
    for dep in ctx.attrs.deps:
        dep_output = dep[DefaultInfo].default_outputs
        dep_files.extend(dep_output)

    # Build a script that concatenates dep outputs with src, then uppercases
    # This demonstrates actually USING the dependency outputs!
    # Script expects: output_path dep_file1 dep_file2 ... src_file
    # Simple Python script to concatenate files with newlines and uppercase
    script = """
python3 -c "
import sys
contents = []
for path in sys.argv[2:]:  # Skip output path, read all input files
    with open(path) as f:
        contents.append(f.read())
with open(sys.argv[1], 'w') as out:
    out.write('\\n'.join(contents).upper())
" "$@"
"""

    # Build the command: bash -c script -- output dep1 dep2 ... src
    cmd = cmd_args([
        "/bin/bash",
        "-c",
        script,
        "--",
        output.as_output(),
    ])

    # Add all dependency outputs as inputs
    for dep_file in dep_files:
        cmd.add(dep_file)

    # Add our source file last
    cmd.add(src)

    ctx.actions.run(cmd, category = "uppercase")

    return [DefaultInfo(default_output = output)]

uppercase = rule(
    impl = _uppercase_impl,
    attrs = {
        "src": attrs.source(),
        "output_name": attrs.string(default = "result.txt"),
        "deps": attrs.list(attrs.dep(), default = []),
    },
)
```

**Add to `BUCK`:**

```starlark
# Create input2.txt first
# (You'll need to create this file)

uppercase(
    name = "goodbye",
    src = "input2.txt",
    output_name = "result2.txt",
    deps = [":hello"],  # Depends on the first target
)
```

**Create `input2.txt`:**

```
goodbye world
```

**Testing:**

```bash
# Build goodbye - will also build hello automatically
buck2 build :goodbye --show-full-output

# Check the content - it should contain BOTH files uppercased with newline between!
cat <output-path-for-goodbye>
# Expected:
# HELLO WORLD
# GOODBYE WORLD
# (concatenated hello's output + goodbye's input, separated by newline, all uppercased)

# See the dependency graph
buck2 cquery "deps(:goodbye)"
```

**Key concepts to explain:**

- **Dependencies**: Other targets this target needs
- **attrs.dep()**: Declares an attribute accepting another target
- **Providers**: Access dependency info via `dep[ProviderType]`
- **Using dep outputs**: We concatenate dep outputs with our src, showing real usage
- **Automatic ordering**: Buck2 builds deps first, ensuring outputs are ready
- **cmd.add()**: Dynamically add arguments to the command (for variable number of deps)

**Before moving on:**

```python
AskUserQuestion:
  question: "Final step! Ready to learn the difference between rules and macros?"
  options:
    - "Yes, what's the difference?"
    - "Let me practice with more dependencies first"
```

---

### Step 8: Rules vs Macros

**Goal:** Understand when to use rules vs macros.

**What to do:**

1. Explain that what they created is a RULE
2. Create a MACRO that wraps the rule
3. Use the macro in TARGETS
4. Build and compare

**Add macro to `uppercase.bzl`:**

```starlark
# This is a MACRO - just a function that wraps the rule
def uppercase_macro(name, src, prefix = "UPPER", **kwargs):
    """
    A convenience macro that adds a prefix to the output filename.
    Macros run during the loading phase, before analysis.
    """
    uppercase(
        name = name,
        src = src,
        output_name = prefix + "_" + src,  # Add prefix
        **kwargs
    )
```

**Add to `BUCK`:**

```starlark
uppercase_macro(
    name = "hello_macro",
    src = "input.txt",
    prefix = "PREFIXED",
)
```

**Testing:**

```bash
buck2 build :hello_macro --show-full-output
# Output filename will be: PREFIXED_input.txt
```

**Key concepts to explain:**

**Rules:**

- Core Buck2 primitives declared with `rule()`
- Run during analysis phase
- Create actions that produce artifacts
- Can be queried with `buck2 cquery`/`uquery`
- The fundamental building block

**Macros:**

- Just Starlark functions that call rules
- Run during loading phase (before analysis)
- Provide convenient interfaces with defaults
- The macro itself isn't visible to queries (only underlying rule)
- Syntactic sugar for users

**When to use macros:**

- Provide convenient interfaces
- Set common defaults
- Generate multiple targets from one call
- Abstract complexity for end users

**Final wrap-up:**

```python
AskUserQuestion:
  question: "Congratulations! You've completed the tutorial. What would you like to do?"
  options:
    - "Review a specific concept"
    - "Try building something custom"
    - "Clean up tutorial files"
    - "See next steps for learning more"
```

---

## Conversation Flow Example

Here's how a typical interactive session should flow:

**User:** "I want to learn Buck2"

**Claude:** "Great! I'll guide you through writing your first Buck2 rule. We'll
build a simple text converter that uppercases files. I'll guide you
step-by-step - there are 8 steps total, and we'll test after each one.

Let me check if you have any existing tutorial files..."

[Checks for files]

"Looks like you're starting fresh! I'll create a todo list to track our
progress."

[Creates todo list with 8 steps]

"Ready to start with Step 1: Creating a minimal rule?"

[Waits for confirmation]

**User:** "Yes"

**Claude:** "Perfect! Step 1 is about creating the simplest possible Buck2
rule - one that does nothing but is valid.

I'll create two files:

- `uppercase.bzl` - The rule definition
- `BUCK` - How to use the rule

[Creates files and builds]

"Success! The build worked (with a warning about no outputs, which is expected).

Let me explain what just happened:

- A **rule** is defined with the `rule()` function
- The **implementation function** runs during the analysis phase... [explains
  concepts]

Ready to move to Step 2 where we'll accept input files?"

[And continues this pattern through all 8 steps]

---

## Tips for Teaching

1. **Celebrate small wins**: "Great!", "Perfect!", "It worked!"
2. **Normalize errors**: "This error is expected!", "Let's see what Buck2 is
   telling us"
3. **Check understanding**: Regularly ask if concepts make sense
4. **Offer choices**: Let users explore or move forward
5. **Show don't tell**: Build and run, then explain
6. **Connect concepts**: "Remember in Step 2 when we learned about artifacts?
   Here's where that matters..."
7. **Show file changes after each step**: After creating or modifying files, briefly list what changed:
   - Example: "I just created `uppercase.bzl` with the rule definition and updated `BUCK` to use it."
   - Example: "I modified `uppercase.bzl` to add the `src` attribute."
8. **Remind users about the editor**: Tell users they can open the files in their editor to see the complete code:
   - Example: "You can open `uppercase.bzl` in your editor to see the full implementation."
   - Example: "Feel free to open these files in your editor to review the changes."

## Next Steps to Suggest After Completion

1. **Read the reference materials**: This skill includes detailed documentation:
   - `references/concepts.md` - Deep dive into Buck2 core concepts (build model, targets, artifacts, actions, providers, configurations, build graph)
   - `references/advanced_patterns.md` - Production-ready patterns (custom providers, transitive sets, toolchains, multiple outputs, testing rules)
2. **Explore Buck2's prelude**: See real production rules in `fbcode/buck2/prelude/`
3. **Try more complex rules**: Multiple outputs, custom providers, transitive dependencies
4. **Learn BXL**: Buck Extension Language for build introspection
5. **Build something real**: Apply what you learned to your project

**Pro tip:** After completing the tutorial, ask questions like "how do providers work in detail?" or "what are transitive sets?" and I'll reference the appropriate documentation to give you deeper explanations.

## Handling Special Cases

**User is stuck:** Offer to review previous concepts or try simpler examples

**User wants to skip ahead:** Allow it, but ensure prerequisites are met

**User found a bug:** Help debug and explain what went wrong

**User wants to experiment:** Encourage it! Help them try variations

**User is confused:** Go back a step, provide more examples, or explain
differently


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/concepts.md

```markdown
# Buck2 Core Concepts - Deep Dive

This reference provides detailed explanations of Buck2 core concepts for users
who want to go beyond the basic tutorial.

## Table of Contents

1. [The Buck2 Build Model](#the-buck2-build-model)
2. [Targets in Depth](#targets-in-depth)
3. [Artifacts](#artifacts)
4. [Actions](#actions)
5. [Providers](#providers)
6. [Configurations](#configurations)
7. [Analysis Phase](#analysis-phase)
8. [Build Graph](#build-graph)

---

## The Buck2 Build Model

Buck2 uses a **declarative, graph-based build model**:

1. **Load Phase**: Read and evaluate BUCK/BUILD files, create unconfigured
   targets
2. **Configuration Phase**: Apply configurations to targets, resolve `select()`
   expressions
3. **Analysis Phase**: Run rule implementations, declare actions and artifacts
4. **Execution Phase**: Run actions to produce artifacts

**Key insight:** Rules don't execute commands - they declare what commands
should be run. Buck2 decides when to actually run them.

---

## Targets in Depth

### Target Terminology

**Target** is an overloaded term in Buck2. Be precise:

#### 1. Unconfigured Target

- **What it is:** A target as written in BUCK files, before configuration is
  applied
- **Identifier:** `//package:name` (no configuration suffix)
- **Query tool:** `buck2 uquery`
- **Characteristics:**
  - Has all attributes from BUCK file
  - `select()` expressions are **not** resolved (still conditional)
  - No platform-specific information applied
  - Same for all configurations

**Example:**

```starlark
# BUCK file
cpp_binary(
    name = "app",
    srcs = select({
        "DEFAULT": ["main.cpp"],
        "ovr_config//os:windows": ["main_windows.cpp"],
    }),
)

# Unconfigured query shows the raw select():
# buck2 uquery //path:app --output-attribute=srcs
# Returns: select({"DEFAULT": ["main.cpp"], ...})
```

#### 2. Configured Target

- **What it is:** A target with a specific configuration applied
- **Identifier:** `//package:name (fbcode//platform/linux:configuration)`
- **Query tool:** `buck2 cquery`
- **Characteristics:**
  - `select()` expressions are resolved to concrete values
  - Platform-specific settings applied (os, cpu, compiler flags, etc.)
  - Different configurations of the same target are distinct build graph nodes

**Example:**

```starlark
# Same target as above, but configured for Linux:
# buck2 cquery //path:app --output-attribute=srcs
# Returns: ["main.cpp"]  (select() resolved to DEFAULT)

# Configured for Windows:
# Returns: ["main_windows.cpp"]  (select() resolved to windows branch)
```

#### 3. Target Label vs Target Pattern

**Target Label:** References a specific target

- With cell: `cell//package:name`
- Without cell: `//package:name` (uses current cell)

**Target Pattern:** Matches multiple targets

- With cell: `cell//package:...` (recursive), `cell//package:*` (package only)
- Without cell: `//package:...` (recursive), `//package:*` (package only)

**Understanding Cells:**

A **cell** is a repository or unit of code in Buck2. Cells allow Buck2 to work
with multiple repositories or isolated parts of a monorepo.

- **Explicit cell reference:** `fbcode//buck2/app:buck2`
  - `fbcode` = cell name
  - `buck2/app` = package path within that cell
  - `buck2` = target name
- **Implicit cell reference:** `//buck2/app:buck2`
  - Uses the current cell based on your working directory
  - Equivalent to `fbcode//buck2/app:buck2` if your current directory is under
    the `fbcode` cell folder (e.g., `/path/to/fbsource/fbcode/`)

**When to use explicit cells:**

- **Cross-cell dependencies:** Depend on targets in a different cell
  - Example: `fbcode//buck2:buck2` depending on `prelude//rules.bzl`
- **Clarity:** Make dependencies explicit, especially in shared code
- **Cell boundaries:** When working across repository or monorepo boundaries

**When implicit cells are sufficient:**

- **Same-cell dependencies:** Most dependencies within the same cell
- **Local references:** Targets in the same cell you're currently working in

### Target Dependencies

Targets form a **Directed Acyclic Graph (DAG)**:

```
//app:main
├── //lib:utils
│   └── //third-party:json
└── //lib:core
    └── //third-party:json  (shared dependency)
```

**Key properties:**

- **Acyclic**: No circular dependencies allowed
- **Declared**: Dependencies must be explicitly listed in `deps`
- **Typed**: Dependencies flow through providers (see Providers section)

---

## Artifacts

Artifacts represent files in Buck2's build model.

### Types of Artifacts

#### 1. Source Artifacts

- **Definition:** Files checked into version control
- **Location:** Your repo (e.g., `src/main.cpp`)
- **Characteristics:**
  - Immutable (within a build)
  - No action produces them
  - Directly referenced in BUCK files

#### 2. Build Artifacts

- **Definition:** Files produced by actions during the build
- **Location:** `buck-out/` directory
- **Characteristics:**
  - Created by actions
  - Cached based on inputs
  - "Remember" what action produces them

**Example:**

```starlark
def my_rule_impl(ctx: AnalysisContext):
    # Source artifact (from repo)
    src = ctx.attrs.src

    # Build artifact (will be produced)
    output = ctx.actions.declare_output("result.o")

    # output "remembers" it will be produced by this action:
    ctx.actions.run(cmd_args(["gcc", src, "-o", output.as_output()]))
```

### Artifact Paths

Buck2 tracks artifacts symbolically during analysis:

```starlark
output = ctx.actions.declare_output("foo.txt")
# At this point, output is just a promise - file doesn't exist yet!
# Buck2 knows: "If anyone needs foo.txt, run the action that produces it"
```

### Bound vs Unbound Artifacts

- **Bound artifact:** Has an action that produces it
- **Unbound artifact:** Declared but no action produces it (Buck2 error!)

```starlark
# This will error:
def bad_rule_impl(ctx: AnalysisContext):
    output = ctx.actions.declare_output("result.txt")  # Declared
    return [DefaultInfo(default_output = output)]      # But never bound to an action!
```

---

## Actions

Actions are the commands that actually run during the build.

### Action Properties

1. **Hermetic**: Given the same inputs, always produce the same outputs
2. **Cacheable**: Results are cached based on inputs
3. **Lazy**: Only run when their outputs are needed
4. **Declared, not executed**: Rule implementations don't run actions - they
   declare them

### Creating Actions

#### ctx.actions.run()

Execute a command:

```starlark
ctx.actions.run(
    cmd_args(["my_tool", input_file, "-o", output.as_output()]),
    category = "process",        # For Buck2 UI
    env = {"VAR": "value"},      # Environment variables
)
```

#### ctx.actions.write()

Write content to a file:

```starlark
config_file = ctx.actions.write("config.json", '{"key": "value"}')
# Returns an artifact that can be used as input to other actions
```

#### ctx.actions.copy_file()

Copy a file:

```starlark
copied = ctx.actions.copy_file("output.txt", src_artifact)
```

### Action Inputs and Outputs

Buck2 tracks dependencies automatically:

```starlark
def my_rule_impl(ctx: AnalysisContext):
    src = ctx.attrs.src               # Input artifact
    output = ctx.actions.declare_output("result.txt")

    cmd = cmd_args(["process", src, "-o", output.as_output()])
    #                          ^^^              ^^^
    #                       input              output

    ctx.actions.run(cmd)
    # Buck2 now knows:
    # - This action reads: src
    # - This action writes: output
    # - This action must run after any action that produces src
```

### Action Caching

Buck2 caches action results based on:

- Command line arguments
- Input file contents (hash)
- Environment variables
- Execution configuration

If inputs haven't changed, Buck2 reuses cached outputs.

---

## Providers

Providers are how rules expose information to their dependents.

### Why Providers?

Without providers, dependents can't access information from their dependencies:

```starlark
# How does a binary know what headers its library dependencies export?
# How does a test know what binary to run?
# Answer: Providers!
```

### Built-in Providers

#### DefaultInfo

Every rule must return this:

```starlark
DefaultInfo(
    default_outputs = [artifact],    # List of primary outputs
    sub_targets = {"foo": [...]}     # Named sub-outputs
)
```

**Used by `buck2 build`:** When you run `buck2 build //target:name`, Buck2
builds the artifacts listed in `default_outputs`. This is what determines which
files get built.

**Example:**

```bash
# Builds the artifacts in DefaultInfo.default_outputs
buck2 build //app:main

# Access sub-targets
buck2 build //app:main[foo]  # Builds artifacts from sub_targets["foo"]
```

#### RunInfo

For executable targets:

```starlark
RunInfo(
    args = cmd_args([binary, "--flag"])  # How to run this target
)
```

**Used by `buck2 run`:** When you run `buck2 run //target:name`, Buck2 executes
the command specified in `RunInfo.args`. The target must provide `RunInfo` to be
runnable.

**Example:**

```bash
# Runs the command from RunInfo.args
buck2 run //app:main -- additional_args

# Buck2 will:
# 1. Build the target (using DefaultInfo)
# 2. Execute the command from RunInfo with any additional arguments
```

### Custom Providers

Define your own to pass custom information:

```starlark
# Define the provider
MyLibraryInfo = provider(fields = {
    "headers": provider_field(typing.Any),    # Header files
    "link_flags": provider_field(typing.Any), # Linker flags
})

# Library rule returns it
def my_library_impl(ctx: AnalysisContext):
    # ... build library ...
    return [
        DefaultInfo(default_output = lib_artifact),
        MyLibraryInfo(
            headers = ctx.attrs.headers,
            link_flags = ["-lmylib"],
        ),
    ]

# Binary rule consumes it
def my_binary_impl(ctx: AnalysisContext):
    all_headers = []
    all_link_flags = []

    for dep in ctx.attrs.deps:
        # Get the provider from dependency
        if MyLibraryInfo in dep:
            lib_info = dep[MyLibraryInfo]
            all_headers.extend(lib_info.headers)
            all_link_flags.extend(lib_info.link_flags)

    # Use headers and flags in compilation...
```

### Provider Propagation

Providers flow through the dependency graph **along declared dependency edges**.
A target can only access providers from its dependencies (targets listed in its
`deps` attribute).

**Example dependency chain:**

```starlark
# BUCK file for //app:main
my_binary(
    name = "main",
    deps = ["//lib:utils"],  # main depends on utils
)

# BUCK file for //lib:utils
my_library(
    name = "utils",
    deps = ["//third-party:json"],  # utils depends on json
)

# BUCK file for //third-party:json
my_library(
    name = "json",
)
```

**Dependency and provider flow:**

```
//app:main (needs headers)
    │ deps = ["//lib:utils"] (dependency relationship ↓)
    │ MyLibraryInfo provider flows ↑
//lib:utils (provides headers, also depends on json)
    │ deps = ["//third-party:json"] (dependency relationship ↓)
    │ MyLibraryInfo provider flows ↑
//third-party:json (provides headers)
```

**Important:** Dependencies flow downward (from dependent to dependency), but
providers flow **upward** (from dependency to dependent). When `//app:main`
depends on `//lib:utils`, the provider information flows from `//lib:utils` up
to `//app:main`.

**Key points:**

- **Dependencies must be declared:** `//app:main` can access providers from
  `//lib:utils` only because `//lib:utils` is in its `deps`
- **Transitive access:** The binary can collect headers transitively from all
  dependencies if the providers are propagated correctly
- **No dependency = no provider access:** Without a dependency edge, providers
  cannot flow between targets

---

## Configurations

Configurations determine platform-specific behavior.

### What is a Configuration?

A configuration is a **set of constraint values** that determine how a target is
built. Conceptually, it represents information like:

```
{os = linux, cpu = x86_64, compiler = gcc-11, opt_level = opt, ...}
```

This is not actual Buck2 syntax - it's a conceptual representation.

### Configuration Platform Files

Defined in Starlark:

```starlark
# fbcode//platform/linux.bzl
platform(
    name = "linux-x86_64",
    constraint_values = [
        "ovr_config//os:linux",
        "ovr_config//cpu:x86_64",
    ],
)
```

### How Configurations Are Applied

1. User specifies a target: `buck2 build //app:main`
2. Buck2 applies default configuration (or user-specified one)
3. Configuration resolves `select()` expressions
4. Different platforms → different configured targets

### select() Resolution

```starlark
cpp_binary(
    name = "app",
    srcs = ["main.cpp"],
    compiler_flags = select({
        "ovr_config//os:linux": ["-DLINUX"],
        "ovr_config//os:macos": ["-DMACOS"],
        "DEFAULT": [],
    }),
)

# On Linux: compiler_flags = ["-DLINUX"]
# On macOS: compiler_flags = ["-DMACOS"]
# On other platforms: compiler_flags = []
```

### Multi-Platform Builds

The same unconfigured target can be built for multiple platforms simultaneously:

```bash
buck2 build //app:main --target-platforms fbcode//platform/linux:x86_64
buck2 build //app:main --target-platforms fbcode//platform/macos:arm64
```

These create two distinct configured targets in the build graph.

---

## Analysis Phase

The analysis phase is when rule implementations run.

### What Happens During Analysis

1. Buck2 walks the configured build graph
2. For each configured target, calls the rule's `impl` function
3. Rule declares actions and returns providers
4. No actions are executed - just registered
5. Result: Complete action graph ready for execution

### Analysis Context

The `ctx` parameter provides:

```starlark
def my_rule_impl(ctx: AnalysisContext):
    # Access attributes
    srcs = ctx.attrs.srcs
    deps = ctx.attrs.deps

    # Access actions API
    output = ctx.actions.declare_output("result.txt")
    ctx.actions.run(...)

    # Access configuration
    is_windows = ctx.attrs._target_os_type.is_windows

    # Access dependencies' providers
    for dep in deps:
        info = dep[MyProvider]
```

### Analysis vs Execution

| Phase         | What Happens                              | When                       |
| ------------- | ----------------------------------------- | -------------------------- |
| **Analysis**  | Rule impl functions run, actions declared | When target is analyzed    |
| **Execution** | Actions run, files created                | When outputs are requested |

**Example:**

```starlark
def my_rule_impl(ctx):
    print("Analysis!")  # Prints during buck2 build (analysis)

    ctx.actions.run(
        cmd_args(["bash", "-c", "echo Execution!"]),  # Runs later (execution)
        ...
    )
```

---

## Build Graph

The build graph is a DAG of configured targets and actions.

### Graph Structure

```
Configured Targets → Actions → Artifacts

//app:main (linux)
    ↓ analysis produces
    [Action: link]
        ↓ depends on
    app.o (artifact)
        ↓ produced by
    [Action: compile main.cpp]
```

### Graph Queries

Buck2 provides tools to inspect the graph:

#### uquery - Unconfigured target graph

```bash
buck2 uquery "deps(//app:main)"        # All dependencies
buck2 uquery "rdeps(//..., //lib:foo)" # Reverse dependencies
```

#### cquery - Configured target graph

```bash
buck2 cquery "deps(//app:main)"                    # With configs applied
buck2 cquery //app:main --output-attribute=srcs   # Show resolved attributes
```

#### aquery - Action graph

```bash
buck2 aquery "deps(//app:main)"  # Show actions that will run
```

### Incremental Builds

Buck2 uses the graph for incrementality:

1. User changes `src/util.cpp`
2. Buck2 identifies affected artifacts (util.o)
3. Identifies actions that depend on util.o (link action)
4. Identifies configured targets that depend on those actions (//app:main)
5. Only re-runs necessary actions

**Result:** Fast incremental builds even in huge repositories.

---

## Summary

- **Targets**: Nodes in the build graph (unconfigured → configured)
- **Artifacts**: Files (source or build)
- **Actions**: Commands that produce artifacts
- **Providers**: Data flow between targets
- **Configurations**: Platform-specific settings
- **Analysis**: When rules declare actions
- **Build Graph**: DAG of targets, actions, and artifacts enabling incremental
  builds

These concepts work together to make Buck2 fast, correct, and scalable.

```

### references/advanced_patterns.md

```markdown
# Advanced Buck2 Rule Patterns

Common patterns and best practices for writing production-ready Buck2 rules.

## Table of Contents

1. [Custom Providers](#custom-providers)
2. [Transitive Dependencies](#transitive-dependencies)
3. [Toolchain Dependencies](#toolchain-dependencies)
4. [Dynamic Output Names](#dynamic-output-names)
5. [Multiple Outputs](#multiple-outputs)
6. [Command Line Building](#command-line-building)
7. [Configuration-Dependent Rules](#configuration-dependent-rules)
8. [Testing Rules](#testing-rules)

---

## Custom Providers

### Pattern: Library with Transitive Headers

Libraries need to expose headers to dependents:

```starlark
# Define provider for library information
CxxLibraryInfo = provider(fields = {
    "headers": provider_field(typing.Any),            # Direct headers
    "transitive_headers": provider_field(typing.Any), # All headers (including deps)
    "objects": provider_field(typing.Any),            # Compiled objects
    "link_flags": provider_field(typing.Any),         # Linker flags
})

def cxx_library_impl(ctx: AnalysisContext) -> list[Provider]:
    # Compile source files
    objects = []
    for src in ctx.attrs.srcs:
        obj = ctx.actions.declare_output(src.short_path + ".o")
        ctx.actions.run(cmd_args([
            "g++", "-c", src, "-o", obj.as_output()
        ]))
        objects.append(obj)

    # Collect transitive headers from dependencies
    transitive_headers = []
    transitive_headers.extend(ctx.attrs.headers)  # Our own headers

    for dep in ctx.attrs.deps:
        if CxxLibraryInfo in dep:
            dep_info = dep[CxxLibraryInfo]
            transitive_headers.extend(dep_info.transitive_headers)

    # Create archive
    archive = ctx.actions.declare_output("lib" + ctx.label.name + ".a")
    ctx.actions.run(cmd_args(["ar", "rcs", archive.as_output()] + objects))

    return [
        DefaultInfo(default_output = archive),
        CxxLibraryInfo(
            headers = ctx.attrs.headers,
            transitive_headers = transitive_headers,
            objects = objects,
            link_flags = [],
        ),
    ]

cxx_library = rule(
    impl = cxx_library_impl,
    attrs = {
        "srcs": attrs.list(attrs.source()),
        "headers": attrs.list(attrs.source()),
        "deps": attrs.list(attrs.dep()),
    },
)
```

**Usage in binary rule:**

```starlark
def cxx_binary_impl(ctx: AnalysisContext) -> list[Provider]:
    # Collect all headers from dependencies
    all_headers = []
    all_archives = []

    for dep in ctx.attrs.deps:
        if CxxLibraryInfo in dep:
            lib_info = dep[CxxLibraryInfo]
            all_headers.extend(lib_info.transitive_headers)
            all_archives.append(dep[DefaultInfo].default_outputs[0])

    # Compile with all headers available
    # Link with all archives
    # ...
```

---

## Transitive Dependencies

### Pattern: Collecting Dependencies Recursively

Often you need to collect information from all transitive dependencies:

```starlark
def collect_transitive_deps(deps, provider_type, field_name):
    """Helper to collect a field transitively from dependencies."""
    result = []
    for dep in deps:
        if provider_type in dep:
            provider = dep[provider_type]
            field_value = getattr(provider, field_name)
            result.extend(field_value)
    return result

def my_rule_impl(ctx: AnalysisContext):
    # Collect all transitive shared libraries
    transitive_libs = collect_transitive_deps(
        ctx.attrs.deps,
        MyLibraryInfo,
        "transitive_shared_libs"
    )

    # Add our own
    transitive_libs.append(my_lib)

    return [
        MyLibraryInfo(
            transitive_shared_libs = transitive_libs,
        ),
    ]
```

### Pattern: Deduplicated Transitive Dependencies

Use `dedupe()` to avoid duplicates:

```starlark
def my_rule_impl(ctx: AnalysisContext):
    all_libs = []

    for dep in ctx.attrs.deps:
        if MyLibraryInfo in dep:
            all_libs.extend(dep[MyLibraryInfo].transitive_libs)

    # Deduplicate while preserving order
    all_libs = dedupe(all_libs)

    return [MyLibraryInfo(transitive_libs = all_libs)]
```

### ⚠️ Important: Use Transitive Sets in Production

**The manual collection patterns above are simple but inefficient.** In most
cases, you should use **transitive sets** (`tset`) instead. Transitive sets are
Buck2's optimized data structure for propagating information up dependency
trees.

**Why transitive sets?**

- **Memory efficient:** Low cost of creation and memory usage in Starlark
- **Execution efficient:** Edges can be shared instead of duplicating data
- **Automatic deduplication:** Handles DAG traversal correctly
- **Lazy evaluation:** Projections are computed only when needed

**Basic usage:**

```starlark
# 1. Declare the transitive set type with a projection
def _project_as_args(value: str):
    return cmd_args(value, format = "-I{}")

MyHeaderSet = transitive_set(
    args_projections = {"include_dirs": _project_as_args}
)

# 2. Create sets in your rule implementation
def my_library_impl(ctx: AnalysisContext):
    # Collect children sets from dependencies
    children = [
        dep[MyLibraryInfo].headers_tset
        for dep in ctx.attrs.deps
        if MyLibraryInfo in dep
    ]

    # Create our set with our value and children
    headers_tset = ctx.actions.tset(
        MyHeaderSet,
        value = ctx.attrs.include_dir,  # Our contribution
        children = children,             # Transitive dependencies
    )

    return [
        MyLibraryInfo(headers_tset = headers_tset),
    ]

# 3. Use the projection in command lines
def my_binary_impl(ctx: AnalysisContext):
    all_includes = ctx.attrs.deps[MyLibraryInfo].headers_tset.project_as_args("include_dirs")

    cmd = cmd_args(["gcc", ctx.attrs.src, all_includes, "-o", output.as_output()])
    ctx.actions.run(cmd)
```

**Key points:**

- Creating projections is **very cheap** (independent of set size)
- Projections can be used in command lines (`project_as_args`) or JSON
  (`project_as_json`)
- Avoid iterating over tsets (`traverse()`) unless absolutely necessary - use
  projections instead
- Different traversal orders available: `preorder`, `postorder`, `topological`,
  `bfs`

**When to use manual collection vs tsets:**

- **Use tsets:** For transitive dependencies (headers, link flags, libraries,
  etc.) - this is the recommended approach
- **Use manual collection:** Only for simple cases or when learning Buck2 basics

For complete details, see the Buck2 documentation on transitive sets
(https://buck2.build/docs/rule_authors/transitive_sets/).

---

## Toolchain Dependencies

### Pattern: Using Toolchains

Toolchains provide compiler/tool information. A complete toolchain
implementation consists of three parts:

**1. Define the toolchain info provider:**

```starlark
# In rust_toolchain.bzl
RustToolchainInfo = provider(fields = {
    "compiler": provider_field(typing.Any),  # RunInfo for rustc
    "rustc_flags": provider_field(typing.Any), # Default compiler flags
})
```

**2. Define the toolchain rule:**

```starlark
# In rust_toolchain.bzl
def _rust_toolchain_impl(ctx: AnalysisContext):
    return [
        DefaultInfo(),
        RustToolchainInfo(
            compiler = ctx.attrs.compiler[RunInfo],
            rustc_flags = ctx.attrs.rustc_flags,
        ),
    ]

rust_toolchain = rule(
    impl = _rust_toolchain_impl,
    attrs = {
        "compiler": attrs.dep(providers = [RunInfo]),
        "rustc_flags": attrs.list(attrs.arg(), default = []),
    },
    is_toolchain_rule = True,  # Mark this as a toolchain rule
)
```

**3. Create a toolchain target in BUCK:**

```starlark
# In //toolchains/BUCK
rust_toolchain(
    name = "rust",
    compiler = ":rustc_wrapper",
    rustc_flags = ["-C", "opt-level=2"],
)

# Helper target that provides RunInfo for rustc
command_alias(
    name = "rustc_wrapper",
    exe = "/usr/bin/rustc",  # System rustc
)
```

**4. Use the toolchain in your rule:**

```starlark
def rust_binary_impl(ctx: AnalysisContext):
    # Access toolchain
    toolchain = ctx.attrs._toolchain[RustToolchainInfo]

    output = ctx.actions.declare_output(ctx.label.name)

    # Build command using toolchain
    cmd = cmd_args()
    cmd.add(toolchain.compiler)        # Add rustc from toolchain
    cmd.add(toolchain.rustc_flags)     # Add flags from toolchain
    cmd.add("--crate-type=bin")
    cmd.add(ctx.attrs.src)
    cmd.add("-o", output.as_output())

    ctx.actions.run(cmd, category = "rustc")

    return [DefaultInfo(default_output = output)]

rust_binary = rule(
    impl = rust_binary_impl,
    attrs = {
        "src": attrs.source(),
        "_toolchain": attrs.toolchain_dep(
            default = "//toolchains:rust",  # Default toolchain target
        ),
    },
)
```

**Key points:**

- Toolchain rules must set `is_toolchain_rule = True`
- Toolchain rules return a custom provider (e.g., `RustToolchainInfo`) with tool
  information
- Consumer rules access toolchains via `attrs.toolchain_dep()` (usually as a
  private `_toolchain` attribute)
- This pattern allows different toolchains (e.g., stable vs nightly Rust)
  without changing rule implementations

---

## Multiple Outputs

### Pattern: Output Directory

When a tool produces multiple files, use an output directory:

```starlark
def my_rule_impl(ctx: AnalysisContext):
    # Declare output directory
    output_dir = ctx.actions.declare_output("outputs", dir = True)

    # Command writes multiple files to directory
    cmd = cmd_args([
        "my_tool",
        "--output-dir", output_dir.as_output(),
    ])

    ctx.actions.run(cmd)

    return [DefaultInfo(default_output = output_dir)]
```

### Pattern: Main Output + Sub-Outputs

```starlark
def compiler_impl(ctx: AnalysisContext):
    # Main output: executable
    exe = ctx.actions.declare_output(ctx.label.name)

    # Debug symbols as sub-output
    debug_symbols = ctx.actions.declare_output(ctx.label.name + ".debug")

    # Compilation database as sub-output
    compile_commands = ctx.actions.declare_output("compile_commands.json")

    ctx.actions.run(cmd_args([
        "my_compiler",
        ctx.attrs.src,
        "-o", exe.as_output(),
        "--debug-output", debug_symbols.as_output(),
        "--compilation-database", compile_commands.as_output(),
    ]))

    return [
        DefaultInfo(
            default_output = exe,
            sub_targets = {
                "debug": [DefaultInfo(default_output = debug_symbols)],
                "compdb": [DefaultInfo(default_output = compile_commands)],
            },
        ),
    ]

# Build different outputs:
# buck2 build //:app              # Main executable
# buck2 build //:app[debug]       # Debug symbols
# buck2 build //:app[compdb]      # Compilation database
```

---

## Command Line Building

### Pattern: Complex Command Lines

```starlark
def my_rule_impl(ctx: AnalysisContext):
    cmd = cmd_args()

    # Add tool
    cmd.add(ctx.attrs.toolchain[MyToolInfo].tool)

    # Add flags
    cmd.add("-Wall", "-O2")

    # Add user flags
    cmd.add(ctx.attrs.flags)

    # Add source files
    cmd.add(ctx.attrs.srcs)

    # Add include directories (prepend -I to each)
    for include in ctx.attrs.includes:
        cmd.add("-I")
        cmd.add(include)

    # Or more concisely:
    cmd.add(cmd_args(ctx.attrs.includes, format = "-I{}"))

    # Add output
    cmd.add("-o", output.as_output())

    # Hidden inputs (for dependencies but not in command)
    cmd.add(hidden = [dep_artifact1, dep_artifact2])

    ctx.actions.run(cmd)
```

### Pattern: Conditional Command Line Arguments

```starlark
def my_rule_impl(ctx: AnalysisContext):
    cmd = cmd_args(["my_tool"])

    # Add flags conditionally
    if ctx.attrs.debug:
        cmd.add("-g")

    if ctx.attrs.optimize:
        cmd.add("-O3")
    else:
        cmd.add("-O0")

    # Platform-specific flags
    if ctx.attrs._target_os_type[OsLookup].platform == "windows":
        cmd.add("-DWINDOWS")

    ctx.actions.run(cmd)
```

---

## Configuration-Dependent Rules

### Pattern: Using select() in Rules

```starlark
# In BUCK file, users can use select():
my_rule(
    name = "app",
    srcs = ["main.cpp"],
    flags = select({
        "ovr_config//os:linux": ["-DLINUX"],
        "ovr_config//os:macos": ["-DMACOS"],
        "DEFAULT": [],
    }),
)

# In rule implementation, just use the value:
def my_rule_impl(ctx: AnalysisContext):
    # ctx.attrs.flags is already resolved to the correct value
    cmd = cmd_args(["compiler"] + ctx.attrs.flags + [ctx.attrs.src])
    # ...
```

---

## Testing Rules

### Pattern: Test Rule with Runner

```starlark
def my_test_impl(ctx: AnalysisContext):
    # Build the test binary (same as binary rule)
    test_exe = ctx.actions.declare_output(ctx.label.name)
    ctx.actions.run(cmd_args(["gcc", ctx.attrs.src, "-o", test_exe.as_output()]))

    # Create test runner script
    runner = ctx.actions.write(
        "run_test.sh",
        [
            "#!/bin/bash",
            "set -e",
            "exec " + cmd_args(test_exe).relative_to(ctx.label.path),
        ],
    )

    return [
        DefaultInfo(default_output = test_exe),
        RunInfo(args = cmd_args([runner])),
        ExternalRunnerTestInfo(
            type = "custom",
            command = [runner],
        ),
    ]

my_test = rule(
    impl = my_test_impl,
    attrs = {
        "src": attrs.source(),
    },
)
```

**Run the test:**

```bash
buck2 test //:my_test
```

### Pattern: Test with Test Data

```starlark
def my_test_impl(ctx: AnalysisContext):
    test_exe = ...  # Build test executable

    # Test needs access to data files
    test_data = ctx.attrs.data

    # Create a test runner that sets up the environment
    runner = ctx.actions.write_json(
        "test_runner.json",
        {
            "exe": test_exe,
            "data": test_data,
        },
    )

    return [
        DefaultInfo(default_output = test_exe),
        RunInfo(
            args = cmd_args([test_exe], hidden = test_data)
        ),
        ExternalRunnerTestInfo(
            type = "custom",
            command = [test_exe],
            env = {
                "TEST_DATA": cmd_args(test_data, delimiter = ","),
            },
        ),
    ]

my_test = rule(
    impl = my_test_impl,
    attrs = {
        "src": attrs.source(),
        "data": attrs.list(attrs.source(), default = []),
    },
)
```

---

## Common Patterns Summary

| Pattern                 | Use Case                                                       |
| ----------------------- | -------------------------------------------------------------- |
| Custom Providers        | Share information between rules                                |
| Transitive Dependencies | Collect headers, libraries, etc. from all deps                 |
| **Transitive Sets**     | **Efficient transitive propagation (use this in production!)** |
| Toolchains              | Abstract compiler/tool locations                               |
| Multiple Outputs        | Output directories, sub-outputs, debug info                    |
| Command Building        | Construct complex command lines                                |
| Configuration-Dependent | Platform-specific behavior                                     |
| Test Rules              | Executable tests with data                                     |

These patterns form the building blocks of production Buck2 rules. Combine them
as needed for your specific use case.

**Note:** For production code, prefer transitive sets over manual dependency
collection for better performance and correctness.

```