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 run the comprehension check (see below) before continuing

3. Use the Socratic Method Between Major Steps

After completing each major step (1-8), do NOT simply ask "ready to continue?". Verify the user actually understood the step before advancing by posing a comprehension check and having them answer in their own words.

Ask the question as plain text, then stop and wait for the user's typed reply. Do NOT use AskUserQuestion or offer answer choices — the user should compose a free-response answer, not pick from a list. Having to articulate the idea themselves, with no options to recognize, is what reveals whether they actually understood it.

Generate the question yourself — do not hardcode it. Look at the concepts you just explained and the code you just wrote together, then craft a question that probes the "why," not just the "what." A good question asks the user to predict, explain, or apply ("what would happen if...", "why did X occur", "which line is responsible for Y") rather than recite a definition.

Act on the answer:

• Correct: affirm briefly, say why it's right (filling in any nuance they missed), then move to the next step.
• Partially right or vague: acknowledge what they got, then ask a follow-up that targets the gap.
• Incorrect: do NOT just reveal the answer. Re-explain from a different angle, point at the relevant code or build output, then ask a fresh open-ended question to confirm. Only advance once they get it.

Keep it to one or two questions per step — a comprehension check, not an exam. The user can always ask their own question instead, or say they want to skip ahead; honor that.

Illustrative only — the shape to aim for, not a script to copy:

We built :hello and it built successfully but wrote no output file. Why do you think that happened?

Then wait for their answer. What you're listening for here: the impl ran during analysis and returned an empty DefaultInfo, so no action was ever registered to produce a file.

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:

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)

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

TodoWrite with 8 items (all pending initially)

Check existing state:

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

Ask user:

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:

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

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

uppercase(name = "hello")

Testing:

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 — Socratic check:

Run a comprehension check (see "Use the Socratic Method Between Major Steps"), generating the question from what this step covered. Aim it at whether they grasp that the impl runs during the analysis phase, and why the build succeeded despite producing no output. Advance only once they show they understand.

---

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:

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:

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

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

Create input.txt:

hello world

Testing:

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 — Socratic check:

Run a comprehension check (see "Use the Socratic Method Between Major Steps"), generating the question from what this step covered. Aim it at the gap between declaring an attribute and producing output — why adding src still yields no output, and what attrs.source() actually does. Advance only once they show they understand.

---

Step 3: Declare Output Artifact

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

What to do:

1. Update implementation

---

Content truncated.