buck2-rule-basics

What this skill does

@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. Re