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:

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:

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:

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:

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:

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:

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:

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:

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([
            "

---

*Content truncated.*