4.12.4 Dormant Dependency Materialization

Dormant dependency materialization is an experimental rule-author API for dependency edges that are possible, but not immediately resolved. Instead of making every dependency in an attribute become an analyzed configured target up front, a rule can route selected edges through a materializer target, and Bazel substitutes the materialized dependencies for that placeholder when another target consumes it.¹ The motivation is large builds where some expensive targets should be analyzed only on demand, such as dependency-injection-style graphs with dynamically determined dependencies.²

What Changes In The Graph

The normal rule-authoring model from 2.2.3 Static Action Graph is deliberately static: dependency attributes are known during analysis, configured targets are analyzed, and actions are registered before execution starts. select() and transitions are the mainstream ways to make that graph configuration-aware. select() chooses attribute values from configuration conditions in 3.3.1 Configurable Attributes (select()), and 4.7.2 Starlark Transitions rewrites configurations along edges.

Dormant dependency materialization is narrower. It does not let a tool discover arbitrary new labels during execution, and it does not make the action graph fully dynamic like the tree-artifact action-template case in 4.12.1 Dynamic Actions with ctx.actions.map_directory(). It changes how selected dependency edges are resolved: a target may depend on a materializer target, but see the materialized dependencies instead of the materializer target itself.¹

That distinction matters for naming. This is target dependency materialization, not repository materialization from 4.9.1 Repository Rule Fundamentals. Repository rules create external repository directories before ordinary target analysis. Materializer rules operate inside the target analysis dependency graph.

The Materializer Rule

materializer_rule() creates a target kind that can be called from a BUILD file or macro to create materializer targets.¹ Its implementation function has the same broad shape rule authors already know: it receives one ctx parameter and runs during analysis for each materializer target instance.¹ The special contract is the return value: the implementation must return exactly one MaterializedDepsInfo provider.¹

MaterializedDepsInfo is intentionally small. Its deps field is the list of dependencies to materialize, and the documented element types are ConfiguredTarget or DormantDependency objects.³ In other words, the materializer target is not the semantic dependency that consumers should reason about. It is a resolver target whose provider tells Bazel which real dependency objects stand in its place.

The API reference also exposes an allow_real_deps parameter on materializer_rule(), defaulting to False, for allowing materializer instances to have real, non-dormant dependencies. The docs mark this as allowlist-controlled.¹ Treat that as a warning about maturity, not a convenience switch to design around. A materializer API should make its dependency-resolution boundary obvious to downstream rule authors.

Attribute Hooks And Resolution Rules

The other half of the feature is on attributes. attr.label() and attr.label_list() have an experimental materializer parameter, enabled by --experimental_dormant_deps.⁴ The documented behavior is that the materializer function can access the rule's non-dependency attributes, plus dependency attributes explicitly marked as available for dependency resolution, and returns either a dormant dependency or a list of dormant dependencies depending on the attribute type.⁴

That "available for dependency resolution" part is explicit too. Label-shaped attributes document for_dependency_resolution, which makes the attribute available for materializers. Only rules marked with the corresponding rule-level flag may be referenced through those attributes.⁵ On the rule declaration side, rule(dependency_resolution_rule = True) marks a rule as one that can be used through attributes available in materializers, and the docs require every attribute of such rules to be marked available in materializers so those rules do not depend on ordinary rules outside that boundary.⁶

Those constraints are the core design signal. The feature is not "any rule can peek at any dependency later." A rule author has to declare which attributes participate in dependency resolution, which rule kinds may appear there, and which materializer target produces the replacement dependency list.

How To Design Around It

Start from the same public-surface discipline as 4.2.7 Custom Provider Declaration and 4.2.8 Provider-as-Interface Pattern. If a consumer rule expects materialized dependencies to provide a provider, keep that provider contract documented and tested. The materializer may be experimental, but provider shape, attribute names, and failure modes are still the API your users will copy into BUILD files.

Good materializer candidates model a real choice in the dependency graph: optional implementation modules, generated dependency-injection edges, or other large sets where most possible edges are not needed in a given build. The operational question of when that complexity pays for itself belongs in 6.6.9 Bottleneck-Driven Optimization. At Level 4, the rule-author question is smaller: can you express the resolver target, its attrs, its provider output, and the consuming attrs without making the rule surface surprising?

Test at analysis time where possible. The important contract is not "did a compiler run". It is "did this target expose the expected provider data after dependency materialization." That makes 4.5.1 Analysis-Phase Testing a better first fit than an execution-heavy fixture. Add integration tests only when the materialized dependency affects real downstream rule behavior.

Current Status

Every public surface here says "experimental." The attribute hook is documented as experimental, may change at any time, and is gated by --experimental_dormant_deps.⁴ The API pages are also sparse: MaterializedDepsInfo documents only the provider purpose and its deps field.³ Use this as a design-study topic or a controlled ruleset experiment, not a default abstraction for published rules.

There is deliberately no runnable workspace linked from this page yet. Against the repository's pinned Bazel 9.1.0, even a materializer target that returns an empty MaterializedDepsInfo stops before useful analysis because the bundled @bazel_tools lacks the required materializer_rule_allowlist target. The flag alone is therefore not enough to provide a command that works with this project's Bazel distribution. The code still shows the documented API, but it is not runnable here. Before adopting it, verify the Bazel distribution, flag, allowlist policy, and the attribute that will use the materializer.