# facebook/buck2 architecture

> Architecture diagram of the GitHub repository facebook/buck2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebook/buck2
- Repository: https://github.com/facebook/buck2

## Overview

Buck2 is a hermetic, multi-language build system. A typical workflow starts with a user invoking the CLI, evaluates build definitions and dependencies, analyzes configured targets into actions, executes those actions, and exposes resulting artifacts. Separate branches support target queries and BXL graph introspection. The README documents remote execution, distributed compilation, filesystem watching, and user-defined language support; the supplied source excerpts do not show their full wiring, so those connections are kept conservative.

Main entry points: [`app/buck2/src/commands`](https://github.com/facebook/buck2/tree/main/app/buck2/src/commands) (Command handlers), [`app/buck2_build_api/src/actions/execute/action_executor.rs`](https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/actions/execute/action_executor.rs) (Action executor), [`app/buck2_build_api/src/configure_targets.rs`](https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/configure_targets.rs) (Target configuration), [`app/buck2_analysis/src/analysis.rs`](https://github.com/facebook/buck2/blob/main/app/buck2_analysis/src/analysis.rs) (Target analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_cli["Buck2 CLI<br/>[commands.rs]"]
  node_dispatch["Command handlers"]
end

subgraph group_planning["Build planning"]
  node_starlark["Build definitions<br/>[interpreter.rs]"]
  node_prelude["Language rules"]
  node_configure["Target configuration"]
  node_analysis["Target analysis<br/>[analysis.rs]"]
  node_incremental["Incremental engine"]
  node_watcher["Filesystem watcher"]
end

subgraph group_execution["Action execution"]
  node_actions["Action registration<br/>[registry.rs]"]
  node_action_impl["Action implementations"]
  node_executor["Action executor<br/>[action_executor.rs]"]
  node_remote["Remote execution"]
  node_artifacts["Build artifacts<br/>[artifact.rs]"]
  node_materialize["Artifact materializer<br/>[materialize.rs]"]
end

subgraph group_inspection["Inspection and extensions"]
  node_query["Build queries<br/>[query.rs]"]
  node_bxl["BXL extensions"]
end

node_user(("Developer"))
node_cas[("Remote CAS")]
node_distributed["Distributed compilation"]

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_dispatch
node_dispatch -->|"requests build"| node_configure
node_starlark -->|"loads rules"| node_prelude
node_configure -->|"evaluates definitions"| node_starlark
node_configure -->|"configures targets"| node_analysis
node_analysis -->|"calculates dependencies"| node_incremental
node_analysis -->|"registers actions"| node_actions
node_actions -->|"creates actions"| node_action_impl
node_dispatch -->|"requests execution"| node_executor
node_executor -->|"runs actions"| node_action_impl
node_executor -.->|"dispatches remotely"| node_remote
node_remote -.->|"reads and writes"| node_cas
node_executor -->|"produces outputs"| node_artifacts
node_dispatch -->|"requests materialization"| node_materialize
node_materialize -->|"materializes"| node_artifacts
node_watcher -.->|"updates inputs"| node_incremental
node_dispatch -->|"runs query"| node_query
node_dispatch -->|"runs extension"| node_bxl
node_remote -.->|"supports compilation"| node_distributed

click node_cli "https://github.com/facebook/buck2/blob/main/app/buck2/src/commands.rs"
click node_dispatch "https://github.com/facebook/buck2/tree/main/app/buck2/src/commands"
click node_starlark "https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/interpreter.rs"
click node_prelude "https://github.com/facebook/buck2/tree/main/prelude"
click node_configure "https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/configure_targets.rs"
click node_analysis "https://github.com/facebook/buck2/blob/main/app/buck2_analysis/src/analysis.rs"
click node_incremental "https://github.com/facebook/buck2/tree/main/dice/dice/src"
click node_actions "https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/actions/registry.rs"
click node_action_impl "https://github.com/facebook/buck2/tree/main/app/buck2_action_impl/src/actions"
click node_executor "https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/actions/execute/action_executor.rs"
click node_remote "https://github.com/facebook/buck2/tree/main/app/buck2_execute_impl/src"
click node_artifacts "https://github.com/facebook/buck2/blob/main/app/buck2_artifact/src/artifact.rs"
click node_materialize "https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/materialize.rs"
click node_watcher "https://github.com/facebook/buck2/tree/main/app/buck2_file_watcher"
click node_query "https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/query.rs"
click node_bxl "https://github.com/facebook/buck2/tree/main/app/buck2_bxl/src"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_dispatch toneBlue
class node_starlark,node_prelude,node_configure,node_analysis,node_incremental,node_watcher,node_cas toneAmber
class node_actions,node_action_impl,node_executor,node_remote,node_artifacts,node_materialize toneMint
class node_query,node_bxl toneRose
class node_user,node_distributed toneIndigo
```

## Components

### Command entry

- [Buck2 CLI](https://github.com/facebook/buck2/blob/main/app/buck2/src/commands.rs): `app/buck2/src/commands.rs`
- [Command handlers](https://github.com/facebook/buck2/tree/main/app/buck2/src/commands): `app/buck2/src/commands`

### Build planning

- [Build definitions](https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/interpreter.rs): `app/buck2_build_api/src/interpreter.rs`
- [Language rules](https://github.com/facebook/buck2/tree/main/prelude): `prelude`
- [Target configuration](https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/configure_targets.rs): `app/buck2_build_api/src/configure_targets.rs`
- [Target analysis](https://github.com/facebook/buck2/blob/main/app/buck2_analysis/src/analysis.rs): `app/buck2_analysis/src/analysis.rs`
- [Incremental engine](https://github.com/facebook/buck2/tree/main/dice/dice/src): `dice/dice/src`
- [Filesystem watcher](https://github.com/facebook/buck2/tree/main/app/buck2_file_watcher): `app/buck2_file_watcher`

### Action execution

- [Action registration](https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/actions/registry.rs): `app/buck2_build_api/src/actions/registry.rs`
- [Action implementations](https://github.com/facebook/buck2/tree/main/app/buck2_action_impl/src/actions): `app/buck2_action_impl/src/actions`
- [Action executor](https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/actions/execute/action_executor.rs): `app/buck2_build_api/src/actions/execute/action_executor.rs`
- [Remote execution](https://github.com/facebook/buck2/tree/main/app/buck2_execute_impl/src): `app/buck2_execute_impl/src`
- [Build artifacts](https://github.com/facebook/buck2/blob/main/app/buck2_artifact/src/artifact.rs): `app/buck2_artifact/src/artifact.rs`
- [Artifact materializer](https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/materialize.rs): `app/buck2_build_api/src/materialize.rs`

### Inspection and extensions

- [Build queries](https://github.com/facebook/buck2/blob/main/app/buck2_build_api/src/query.rs): `app/buck2_build_api/src/query.rs`
- [BXL extensions](https://github.com/facebook/buck2/tree/main/app/buck2_bxl/src): `app/buck2_bxl/src`

### Other components

- **Developer**
- **Remote CAS**
- **Distributed compilation**

## Connections

- Developer → Buck2 CLI: invokes
- Buck2 CLI → Command handlers: dispatches
- Command handlers → Target configuration: requests build
- Build definitions → Language rules: loads rules
- Target configuration → Build definitions: evaluates definitions
- Target configuration → Target analysis: configures targets
- Target analysis → Incremental engine: calculates dependencies
- Target analysis → Action registration: registers actions
- Action registration → Action implementations: creates actions
- Command handlers → Action executor: requests execution
- Action executor → Action implementations: runs actions
- Action executor → Remote execution: dispatches remotely
- Remote execution → Remote CAS: reads and writes
- Action executor → Build artifacts: produces outputs
- Command handlers → Artifact materializer: requests materialization
- Artifact materializer → Build artifacts: materializes
- Filesystem watcher → Incremental engine: updates inputs
- Command handlers → Build queries: runs query
- Command handlers → BXL extensions: runs extension
- Remote execution → Distributed compilation: supports compilation