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 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 — 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 why the build errored — that declare_output() only promises an artifact while nothing yet produces it (declaration vs production). Advance only once they show they understand.

---

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([
            "/bin/bash",
            "-c",
            script,
            "--",
            src,  # Input artifact
            output.as_output(),  # Output artifact
        ]),
        category = "uppercase",  # Shows in buck2 output
    )

    return [DefaultInfo(default_output = output)]

Testing:

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 — 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 what as_output() and ctx.actions.run() do, and when the action actually runs (lazy execution) — i.e. why adding the action fixed the error. Advance only once they show they understand.

---

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:

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

# 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 — 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 difference between unconfigured and configured targets — what the (cfg:...) suffix means, or the parts of a target name. Advance only once they show they understand.

---

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

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():

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:

# 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 — 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 when and how select() resolves (the configuration phase), and what differs between the uquery and cquery output for output_name. Advance only once they show they understand.

---

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

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

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

# 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 — 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 how Buck2 knows to build :hello before :goodbye, and how the rule reaches a dependency's output via dep[DefaultInfo]. Advance only once they show they understand.

---

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

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

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

Testing:

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

Before wrapping up — 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 rule-vs-macro distinction — which phase each runs in, and why the macro itself doesn't appear in buck2 cquery/uquery. Wrap up only once they show they understand.

Final wrap-up:

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]

Now, before we move on, let me check one thing..."

[Asks an open-ended Socratic comprehension question as plain text, generated from what Step 1 taught — e.g. why the build succeeded with no output — then waits for the user to answer in their own words. If the answer is right, affirm and go to Step 2; if not, re-explain and ask again.]

[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 with Socratic questions: Gate each step on a comprehension check, not a yes/no "ready?" — see "Use the Socratic Method Between Major Steps" 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

Buck2 Rule Basics - Interactive Tutorial Skill

Overview

This skill provides an interactive, step-by-step tutorial for learning Buck2 fundamentals by writing a simple text processing rule. It guides users through 8 progressive steps, teaching core concepts like rules, actions, artifacts, targets, configurations, and more.

What Makes This Skill Interactive?

Unlike traditional tutorials that dump all content at once, this skill:

• Assesses current state before starting
• Presents one step at a time with testing after each
• Waits for user confirmation before proceeding
• Tracks progress with a visual todo list
• Adapts to the user's pace and understanding
• Encourages experimentation and questions

How to Use

For Users

Simply invoke the skill:

use buck2-rule-basics

Claude will:

1. Check if you have any existing tutorial files 2. Offer to start fresh or continue from where you left off 3. Guide you through each step interactively 4. Wait for your confirmation before moving to the next step

You can:

• Ask questions at any time
• Request more explanation on any concept
• Experiment with variations
• Take breaks and resume later

For Claude (Skill Execution)

When this skill is activated, follow these critical rules:

1. Always start by assessing state

• Check for existing uppercase.bzl, BUCK, input.txt
• Read files to determine current progress
• Ask user if starting fresh or continuing

2. Present one step at a time

• Introduce the concept
• Implement the code
• Test it together
• Explain what happened
• Show file changes: Summarize what files were created/modified
• Remind about editor: Tell users they can view changes in their editor
• STOP and wait for confirmation

3. Use AskUserQuestion between steps

• "Ready to move to the next step?"
• "Do you want to explore this more?"
• "Any questions about this concept?"

4. Track progress with TodoWrite

• Show all 8 steps
• Mark completed steps
• Show current step as in_progress
• Keep upcoming steps visible

5. Be adaptive

• If user is confused → provide more examples
• If user is advanced → offer to skip explanations
• If user wants to experiment → encourage and help debug

Tutorial Structure

The tutorial has 8 steps:

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

Each step follows the pattern:

Goal → What to do → Code to write → Test → Key concepts → Confirm before next

Files in This Skill

• SKILL.md - Main skill definition with step-by-step instructions
• README.md - This file, explaining the skill
• CHANGELOG.md - History of changes and fixes
• assets/ - Reference files for the tutorial
• rule_template.bzl - Generic rule template for reference
• BUCK.example - Example BUCK file showing various patterns
• test_input.txt - Sample input for testing
• references/ - Additional documentation
• advanced_patterns.md - Advanced Buck2 patterns
• concepts.md - Core concepts reference

Teaching Philosophy

Show, Don't Tell

• Build and run first
• Then explain what happened
• Concepts are taught in context, not upfront

Normalize Errors

• Step 3 intentionally causes an error
• Use it as a teaching moment
• "This error is expected and good!"

Celebrate Wins

• "Great!", "Perfect!", "It worked!"
• Positive reinforcement keeps users engaged

User-Paced Learning

• Never rush through steps
• Always wait for confirmation
• Encourage questions and exploration

Common Usage Patterns

Starting Fresh

User: "I want to learn Buck2"
Claude: [Checks for existing files]
Claude: "Starting fresh! Here's the plan..."
Claude: [Creates todo list with 8 steps]
Claude: "Ready for Step 1?"

Resuming

User: "Continue the Buck2 tutorial"
Claude: [Reads existing files]
Claude: "You're on Step 5! Let's pick up from there."
Claude: [Resumes with appropriate step]

Exploring

User: "I want to try something different"
Claude: "Great! What would you like to experiment with?"
Claude: [Helps user explore variations]

Tips for Teaching

1. Be conversational - "Let's try...", "Great job!", "Interesting question!" 2. Ask questions - "What do you think will happen?", "Does this make sense?" 3. Connect concepts - "Remember in Step 2 when we learned about X? Here's where it matters..." 4. Offer choices - "Would you like to continue or explore more?" 5. Provide context - Explain WHY something works, not just HOW

Troubleshooting

If user seems lost

• Go back to previous concept
• Provide simpler examples
• Slow down the pace

If user is advanced

• Offer to skip basic explanations
• Jump to more interesting topics
• Suggest variations to try

If errors occur

• Help debug together
• Explain what Buck2 is telling us
• Turn it into a learning opportunity

Next Steps After Completion

Suggest these resources:

1. Explore Buck2's prelude for real production rules 2. Try more complex rules (multiple outputs, custom providers) 3. Learn BXL for build introspection 4. Read internal docs for advanced patterns 5. Apply learnings to their actual project

Maintenance

When updating this skill:

1. Update SKILL.md with the changes 2. Document changes in CHANGELOG.md 3. Test the interactive flow end-to-end 4. Ensure all code examples work 5. Update README.md if teaching approach changes

Known Issues:

• None currently (see CHANGELOG.md for historical fixes)

Version History

See CHANGELOG.md for detailed version history.

Feedback

If you find issues or have suggestions for improving this skill, please provide feedback through the appropriate channels.

Advanced Buck2 Rule Patterns

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

Table of Contents

1. Custom Providers 2. Transitive Dependencies 3. Toolchain Dependencies 4. Dynamic Output Names 5. Multiple Outputs 6. Command Line Building 7. Configuration-Dependent Rules 8. Testing Rules

---

Custom Providers

Pattern: Library with Transitive Headers

Libraries need to expose headers to dependents:

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

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:

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:

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:

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

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

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

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

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:

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

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

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

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

# 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

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:

buck2 test //:my_test

Pattern: Test with Test Data

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

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.

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 2. Targets in Depth 3. Artifacts 4. Actions 5. Providers 6. Configurations 7. Analysis Phase 8. 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:

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

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

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:

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!)

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

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:

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:

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

Action Inputs and Outputs

Buck2 tracks dependencies automatically:

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:

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

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:

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

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:

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

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

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

# 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

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:

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:

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

Example:

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

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

cquery - Configured target graph

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

aquery - Action graph

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.