4.4.5 Legacy Runfiles Split

New rules should treat runtime files as one contract: build a ctx.runfiles(...) object and return it with DefaultInfo(runfiles = ...). The legacy split into data_runfiles and default_runfiles still matters when you maintain older rulesets, because a target can appear to work in one runtime position and then lose files when used through another attribute.¹ The modern model is covered in 4.2.5 DefaultInfo & Runfiles. This article is the debugging note for the old shape.

The Three Slots

DefaultInfo still exposes three runfiles-related constructor parameters.²

Parameter	What it means now
runfiles	The unified runtime file descriptor for new rule implementations.
data_runfiles	Legacy descriptor used when the target is reached through a data attribute.
default_runfiles	Legacy descriptor used when the target is run normally or used through attributes other than data.

The important point is not that new rules should carefully choose between data_runfiles and default_runfiles. New rules should avoid both legacy constructor parameters and use DefaultInfo(runfiles = ...) instead.³ The DefaultInfo API carries the same warning on both legacy parameters.⁴

Why The Split Is Confusing

The split tried to distinguish "files needed when this is runtime data" from "files needed when this is a normal dependency or tool." In practice, that makes the consuming position affect which runtime files appear. The distinction is legacy and carries a real compatibility trap: some rules put their default outputs in data_runfiles but not in default_runfiles.⁵

That is why a migration should not be a mechanical rename from data_runfiles to runfiles. First decide the runtime contract the target should have. Then include the rule's own runtime files, include default outputs when the executable needs them, and merge the dependency runfiles that should propagate.⁶

def _impl(ctx):
    runfiles = ctx.runfiles(files = ctx.files.data)

    transitive = []
    for dep in ctx.attr.data + ctx.attr.deps:
        transitive.append(dep[DefaultInfo].default_runfiles)

    return [DefaultInfo(runfiles = runfiles.merge_all(transitive))]

This uses the old default_runfiles field only as a read-side compatibility surface: dependencies expose their already-computed runtime files there. The returned provider still uses the unified runfiles parameter.⁷

Avoid The Other Legacy Shortcut

The same cleanup applies to ctx.runfiles(collect_data = True) and ctx.runfiles(collect_default = True). Those switches implicitly collect runfiles across hardcoded srcs, data, and deps edges, and both are not recommended.⁸ Add direct files with files or transitive_files, or explicitly merge dependency runfiles instead.⁹

A common runfiles helper shows the useful shape: it collects direct data files and pulls transitive runtime files from dependency DefaultInfo.default_runfiles, then the rule returns that object through DefaultInfo(runfiles = ...).¹⁰ The exact helper can vary, but the public surface should stay boring: one runfiles object returned from one place.

Debugging Missing Runtime Files

When a legacy rule loses files at runtime, ask two questions before changing code:

1. Which attribute path is the target taking: data, deps, tools, or direct bazel run?
2. Which DefaultInfo field did the producer populate: unified runfiles, legacy data_runfiles, or legacy default_runfiles?

If the file appears only when the target is listed in data, suspect a producer that populated data_runfiles but not the normal runtime path. If a tool works when run directly but fails when another action uses it, check whether the consuming rule passed the executable as a tool with its files-to-run metadata rather than just passing a raw executable path. That tool-runfiles bundle is part of the DefaultInfo runtime contract from 4.2.5 DefaultInfo & Runfiles.¹¹

Migration is safest when it is covered by an integration test from 4.5.2 Ruleset Integration Tests: build a tiny fixture where a binary depends on a library with data, then run it through the same attribute path that used to fail. A provider-only unit test can prove fields are populated, but a bazel run or bazel test fixture proves the files actually reach the runtime environment.