GO — Healthy across the board

• Last commit today
• 35+ active contributors
• Distributed ownership (top contributor 41% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Buck2 is a fast, hermetic, multi-language build system written in Rust that replaces the original Buck. It orchestrates compilation, linking, and testing across Java, Python, Kotlin, C++, and other languages, supporting local and distributed execution with a daemon architecture and Starlark-based rules (7.1M LOC Starlark, 19M LOC Rust). Key capabilities include incremental builds, remote execution via gRPC, action persistence, and fine-grained dependency tracking via its node-based DAG engine. Workspace monorepo (Cargo.toml lists 60+ members): app/buck2 is the CLI entry point, app/buck2_analysis handles build graph construction, app/buck2_interpreter houses the Starlark evaluator, app/buck2_execute_* contains execution backends (local/distributed), app/buck2_daemon manages the persistent daemon, and app/buck2_events streams structured telemetry. Rules live in external cells and prelude (Starlark); configuration in .buckconfig and .buckconfig.d/.

Software engineers at large organizations (especially Meta) who maintain monorepos with mixed language codebases and need deterministic, reproducible builds; build system maintainers extending Buck2 via custom rules; platform engineering teams integrating remote execution backends like NativeLink or Bazel's RBE.

Actively developed and production-ready: this is Meta's successor to the original Buck build system with substantial investment (66K+ stars on predecessor, ongoing CI/CD via .github/workflows/, comprehensive test suite across app/buck2_*_tests modules). However, it's still evolving—the codebase is actively refactored (Starlark interpreter, action caching, configuration system) and has not yet achieved feature parity with some Buck v1 use cases.

Moderate risk: the monorepo spans 60+ interdependent Rust crates (app/buck2_, allocative/) creating tight coupling and potential for cascading breakage; build system changes can silently invalidate users' caches if not handled carefully. Mitigation: strong internal testing at Meta, but external adoption may surface edge cases; complexity is high, making contributing non-trivial without deep context.

Ongoing work visible in the repo structure: enhanced action caching (app/buck2_action_impl), toolchain improvements (app/buck2_cfg_constructor), Starlark language features (app/buck2_interpreter_for_build), external cell bundling (app/buck2_external_cells_bundled), and distributed execution (app/buck2_cmd_query_server, app/buck2_cmd_audit_server). GitHub Actions (.github/workflows/) run bootstrap builds, debug/release builds, and multi-platform tests; example projects test Conan, NativeLink, and custom toolchains.

Clone and build (requires Rust + Cargo): git clone https://github.com/facebook/buck2.git && cd buck2 && cargo build --release. Setup: review .buckconfig and .cargo/config.toml, initialize .envrc (direnv) if needed. To test: cargo test -p app/buck2_cli_proto or run specific suites per .github/workflows/build-and-test.yml. For local development: cargo build outputs to target/debug/buck2; run ./target/debug/buck2 --help to verify.

Daily commands: Development build: cargo build (outputs to target/debug/buck2). Run daemon mode: ./target/debug/buck2 daemon status starts the daemon. Run a build: ./target/debug/buck2 build //path/to:target (requires a BUCK file with rules). Run tests: cargo test --workspace or cargo test -p app/buck2_core for unit tests; integration tests in app/buck2_*_tests. Build docs: cargo doc --workspace --open (generates Rust API docs).

• Cargo.toml — Workspace root configuration defining all member crates and dependencies; essential for understanding the multi-crate build structure.
• .buckconfig — Primary Buck2 build configuration file; sets global build policies and toolchain defaults that affect all builds.
• .buckconfig.d/common.buckconfig — Shared build configuration module that defines common build patterns and rules inherited across the project.
• CONTRIBUTING.md — Developer onboarding guide explaining contribution workflows, testing requirements, and code review expectations.
• .github/workflows/build-and-test.yml — Primary CI/CD pipeline defining test gates and build matrix; critical for understanding release validation process.
• allocative/allocative/src/allocative_trait.rs — Core memory profiling trait used throughout Buck2 for measuring heap allocations; foundational to performance introspection.

Add a new CLI command

1. Create a new command module in app/buck2_client or a specialized client crate (e.g., app/buck2_cmd_*_client) (app/buck2_client/src/lib.rs)
2. Implement the command handler struct and wire it into the CLI dispatch logic (app/buck2_client_ctx/src/command_ctx.rs)
3. Add integration tests to validate the command against the Buck2 daemon (app/buck2_client/tests/)
4. Update CHANGELOG.md and documentation if the command affects user workflows (CHANGELOG.md)

Add a new error handler for a language/platform

1. Create a new .bzl file in action_error_handler/{language}/ directory (action_error_handler/java/java_error_handler.bzl)
2. Define error parsing rules that map compiler output to structured error metadata (action_error_handler/kotlin/kotlin_error_handler.bzl)
3. Integrate handler into app/buck2_action_impl via action execution framework (app/buck2_action_impl/src/lib.rs)
4. Test error parsing with real compiler output in action tests (app/buck2_action_impl_tests/)

Add memory profiling support for a new data structure

1. Create a new implementation module in allocative/allocative/src/impls/{struct_name}.rs (allocative/allocative/src/impls/common.rs)
2. Implement the Allocative trait to measure heap size of the structure and its nested allocations (allocative/allocative/src/allocative_trait.rs)
3. Add golden test files (.src) to validate memory measurement output (allocative/allocative/src/impls/compact_str_test_heap.src)
4. Export the implementation in allocative/allocative/src/impls.rs (allocative/allocative/src/impls.rs)

Add a new build query or audit API

1. Add query logic or API handler to app/buck2_cmd_query_server or app/buck2_cmd_audit_server (app/buck2_cmd_query_server/src/lib.rs)
2. Define client-side command in corresponding _client crate if user-facing (app/buck2_cmd_audit_client/src/lib.rs)
3. Wire the new endpoint into the server dispatcher and client CLI routing (app/buck2_client_ctx/src/lib.rs)
4. Add documentation via app/buck2_cmd_docs_server to describe the query syntax and behavior (app/buck2_cmd_docs_server/src/lib.rs)

• Rust — Type safety, memory safety without GC, and performance critical for a build system that must handle large graphs; enables fearless parallelism
• Multi-crate Cargo workspace — Modular architecture allowing independent compilation and testing of client, daemon, analysis, and execution layers
• Buck configuration (BUCK files + .buckconfig) — Declarative build rules inheriting from original Buck; familiar to existing Meta infrastructure users
• BXL (Buck Extension Language) — Starlark-like language for custom build scripting without requiring full Rust plugin development
• gRPC/Protocol Buffers — Efficient daemon-client communication and action metadata serialization for remote execution
• Allocative trait system — Precise heap memory profiling without runtime overhead; critical for understanding build system performance at scale

• Daemon-based architecture (not single-process invocation like original Buck)

  • Why: Enables persistent caching of build graphs and analysis across invocations, reducing latency for incremental builds
  • Consequence: Added complexity in client-daemon communication, state synchronization, and graceful shutdown; users must manage daemon lifecycle

• Strong typing via Rust vs. dynamic scripting for rules

  • Why: Compile-time safety and performance for core build engine; BXL provides scripting layer without sacrificing core reliability
  • Consequence: Steeper learning curve for rule authors; less flexibility than pure-scripting systems like Bazel

• Build graph materialization (eager rule evaluation) rather than lazy evaluation

  • Why: Enables accurate incremental builds and better error messages early in the build process
  • Consequence: Higher upfront cost for large projects

Daemon persistence: buck2 uses a long-running daemon; buck2 daemon stop must be called to clear stale state or changes to .buckconfig won't apply. Protobuf regeneration: modifying *_proto crates requires manual cargo build to regenerate Rust bindings; incremental builds may silently use stale code. Starlark dialect: Buck2 Starlark is not 100% compatible with Bazel or Starlark standard library; custom builtins are defined in app/buck2_interpreter_for_build/src/starlark_lib/. Multi-crate interdependency: changing a low-level crate (e.g., app/buck2_core) often requires cargo clean to avoid linker errors due to deep transitive dependencies. No precompiled binaries on macOS/Windows in CI by default: .github/workflows/ build both, but may not be released for all commits—bootstrap builds may be required locally.

• Build Graph / Directed Acyclic Graph (DAG) — Buck2's entire execution model is based on constructing and traversing a DAG of targets and actions; understanding node types (TargetNode, ConfiguredTargetNode, ActionNode in app/buck2_node/) is essential to grasping how builds are planned
• Hermetic Builds — Buck2 enforces hermetic sandboxing so builds are reproducible across machines; this drives decisions around input hashing, cache keys, and action isolation in app/buck2_execute_impl/
• Content-Addressed Caching — Buck2 caches build outputs by hashing inputs (files, command, env vars); this enables shared caches across developers and CI; see app/buck2_action_impl/ for action key computation
• Starlark Language (Dialect of Python) — Buck2 rules are written in Starlark (similar to Bazel); understanding this dynamically-typed, immutable-by-default language is critical for writing custom build rules and macros
• Daemon Architecture with Socket IPC — Buck2 keeps a long-running daemon (app/buck2_daemon/) that maintains parsed caches and analysis results; clients (app/buck2_client/) communicate via Unix sockets, enabling fast incremental rebuilds without reparsing
• gRPC Service Definitions for Remote Execution — Buck2's distributed execution (app/buck2_execute/) uses gRPC to offload actions to remote workers; protobuf messages define the action protocol, enabling backends like NativeLink to slot in
• Incremental Compilation & Dependency Tracking — Buck2 uses fine-grained dependency edges to avoid rebuilding unchanged targets; this requires careful input hashing and cache validation in app/buck2_action_impl/ and app/buck2_execute_impl/

• bazelbuild/bazel — Leading multi-language build system; Buck2 borrows Starlark language and incremental build concepts but optimizes for faster local builds and daemon caching
• facebook/buck — Original Buck build system (Java-based); Buck2 is its Rust successor with improved performance, better daemon architecture, and modern gRPC backends
• nativelink/nativelink — Remote execution backend compatible with Buck2; example in .github/actions/build_example_nativelink/ shows integration for distributed builds
• facebookincubator/reindeer — Cargo.lock to BUCK converter; enables hermetic Rust dependency management in Buck2 (set up in .github/actions/setup_reindeer/)
• abseil/abseil-py — Python utility library used by Buck2's Python tooling and test runners for common task abstraction

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for .buckconfig parsing and validation

The repo has .buckconfig and .buckconfig.d/common.buckconfig files but no visible test suite for configuration parsing. Given Buck2's role as a build system, configuration validation is critical. New contributors could add tests for edge cases like malformed configs, missing sections, and inheritance chains in .buckconfig.d/

• [ ] Create app/buck2_config_parser_tests/ directory (following repo's test naming pattern)
• [ ] Add unit tests for .buckconfig parsing in app/buck2_cmd_common or relevant config parsing module
• [ ] Test .buckconfig.d/ directory precedence and merging logic
• [ ] Add regression tests for common misconfiguration scenarios
• [ ] Reference: Look at app/buck2_error_tests/ for test structure patterns

Expand .claude/skills/buck2-rule-basics with practical examples and reference implementations

The .claude/skills directory exists with buck2-rule-basics skill, but references/ only has concepts.md and advanced_patterns.md. There are no concrete end-to-end examples showing how to write a custom rule. Contributors could add practical walkthroughs that new rule developers need.

• [ ] Create .claude/skills/buck2-rule-basics/examples/ directory
• [ ] Add example_simple_cc_rule.md with a minimal C++ rule implementation
• [ ] Add example_custom_python_rule.md showing Python rule with test integration
• [ ] Add example_toolchain_rule.md referencing the build_example_toolchain GitHub action
• [ ] Include test integration patterns showing how to validate custom rules

Add GitHub Action for validating and testing custom toolchain definitions

The repo has .github/actions/build_example_toolchain but no dedicated test action to validate that new toolchains don't break existing rules. This is a gap for contributors adding new toolchain support or rules that depend on toolchains.

• [ ] Create .github/actions/test_toolchain_integration/ with action.yml
• [ ] Add shell script to validate toolchain definitions against example rules in build_example_toolchain/
• [ ] Ensure it tests both common toolchain scenarios and edge cases (missing tools, version mismatches)
• [ ] Integrate into .github/workflows/build-and-test.yml as optional workflow
• [ ] Reference: Follow pattern of .github/actions/run_test_py/action.yml

• Add documentation and tests for the buck2 query command family (app/buck2_cmd_query_server): write examples in docs/query_syntax.md and unit tests in app/buck2_cmd_query_server/tests/ covering set operations, filtering, and output formats.
• Implement missing Starlark builtins for string manipulation in app/buck2_interpreter_for_build/src/starlark_lib/string.rs (e.g., string.partition, string.splitlines) and add corresponding tests in app/buck2_interpreter_for_build_tests/; reference app/buck2_interpreter_for_build/src/starlark_lib/paths.rs for patterns.
• Extend buck2_miniperf/src/ to track and report per-action memory usage in the event stream (app/buck2_events); add a new event type ActionMemoryUsage in app/buck2_events/src/ and log it from app/buck2_execute_impl/src/ when actions complete.

The Buck2 repository shows a moderately secure posture for a large open-source build system project. Key observations: (1) No obvious hardcoded secrets detected in visible file structure. (2) Use of Rust reduces memory safety vulnerabilities compared to C/C++ build systems. (3) Cargo.toml dependencies are truncated, preventing complete vulnerability assessment - this is critical for security. (4) Multiple proto-based packages suggest gRPC/protobuf usage which should follow security best practices. (5) GitHub Actions workflows exist but security configurations are not visible. (6) Bundled external cells may complicate dependency tracking. Recommendations: Complete dependency audit using 'cargo audit', review all GitHub Actions for proper secret management, implement proto generation validation, and ensure build system sandboxing is properly configured.

• Medium · Workspace Members Not Fully Visible — Cargo.toml. The Cargo.toml workspace members list is truncated in the provided content ('app/buck2_for' is cut off). This makes it impossible to perform complete dependency analysis and identify all potential vulnerable dependencies across the entire workspace. Fix: Provide complete Cargo.toml content and run 'cargo audit' to identify known vulnerabilities in all dependencies. Implement automated dependency scanning in CI/CD pipeline.
• Medium · Multiple Bundled External Cells Package — Cargo.toml - app/buck2_external_cells_bundled. The workspace includes 'app/buck2_external_cells_bundled' which suggests bundling of external dependencies. Bundled dependencies increase attack surface and make security updates harder to track and apply consistently. Fix: Review bundled dependencies and consider using workspace dependency management. Ensure all bundled code undergoes security review. Implement mechanisms to easily update bundled dependencies.
• Low · Proto File Generation Without Visible Controls — Cargo.toml - multiple *_proto packages. Multiple proto packages exist (buck2_action_metadata_proto, buck2_cli_proto, buck2_downward_api_proto, buck2_health_check_proto, buck2_install_proto, buck2_miniperf_proto, buck2_test_proto) but no visible proto compilation security controls or validation rules in the provided file structure. Fix: Implement code generation validation for protobuf files. Use protoc with security-focused linting rules. Validate generated code before compilation.
• Low · GitHub Actions Workflow Visibility — .github/workflows/. Multiple GitHub Actions workflows exist (.github/workflows/) but their security configurations, secret management, and permission models are not visible in the provided snippet. Potential for credential exposure or privilege escalation if misconfigured. Fix: Review all workflow files to ensure: least-privilege IAM permissions, encrypted secrets usage, no hardcoded credentials, OIDC token usage where possible, and workflow approval gates for sensitive operations.
• Low · Build System Configuration Files — .buckconfig, .buckconfig.d/. Buck configuration files (.buckconfig, .buckconfig.d/) are present but their content is not visible. Build system misconfigurations can lead to insecure build artifacts. Fix: Review buckconfig files to ensure: sandboxing is enabled, no world-writable outputs, secure caching policies, and no exposure of sensitive build information.
• Low · VS Code Launch Configuration Present — .vscode/launch.json. Debug configuration exists in .vscode/launch.json which may contain sensitive debug settings or exposed ports. Fix: Ensure debug configurations use secure settings, avoid exposing sensitive information, and don't include hardcoded credentials or local-only debugging that could be accidentally committed.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/facebook/buck2 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live facebook/buck2 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/facebook/buck2.

What it runs against: a local clone of facebook/buck2 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in facebook/buck2 | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of facebook/buck2. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/facebook/buck2.git
#   cd buck2
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of facebook/buck2 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "facebook/buck2(\\.git)?\\b" \\
  && ok "origin remote is facebook/buck2" \\
  || miss "origin remote is not facebook/buck2 (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f ".buckconfig" \\
  && ok ".buckconfig" \\
  || miss "missing critical file: .buckconfig"
test -f ".buckconfig.d/common.buckconfig" \\
  && ok ".buckconfig.d/common.buckconfig" \\
  || miss "missing critical file: .buckconfig.d/common.buckconfig"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f ".github/workflows/build-and-test.yml" \\
  && ok ".github/workflows/build-and-test.yml" \\
  || miss "missing critical file: .github/workflows/build-and-test.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/facebook/buck2"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.