buck2-rule-basics

@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