4.2.5 DefaultInfo & Runfiles

DefaultInfo is the default public face of a target. A rule may declare many actions and internal files, but DefaultInfo answers the questions most callers ask first: which files does this target build by default, which file should Bazel run if it is executable, and which runtime files must be present when that executable starts.¹ That makes it the handoff between the rule skeleton from 4.2.1 Rule Function, the action outputs from 4.2.2 Actions, and the runnable target contract expanded in 4.2.6 Executable & Test Rules.

Default Outputs

DefaultInfo.files is a depset of File objects representing the default outputs built when a target is requested on the command line.² If a rule implementation does not return DefaultInfo, or returns one without files, Bazel defaults this field to all predeclared outputs.³ For a rule with derived outputs, returning files explicitly is usually clearer because it says which generated artifacts are part of the target's normal contract.

def _manifest_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name + ".txt")
    ctx.actions.write(
        output = out,
        content = "name = %s\n" % ctx.label.name,
    )
    return [DefaultInfo(files = depset([out]))]

The depset matters for the same reason it mattered in 4.1.5 depset vs list: default outputs may be consumed through other providers and action inputs, so the rule should preserve Bazel's graph-shaped data model instead of flattening too early.⁴ Files that are not in DefaultInfo.files can still be useful, but they need another route: a custom provider, an output group, or direct use by another action. Named output groups are covered separately in 4.2.9 OutputGroupInfo & Output Groups.

Build Inputs Are Not Runtime Files

Action inputs are the files needed to produce an output. Runfiles are the files needed when an executable runs. The same physical file can be both, but the contracts are different: action inputs are visible to the build action, while runfiles are staged for bazel run, bazel test, or for tools used by later actions.⁵ This is the rule-authoring version of the lesson from 2.3.2 Sandboxing: Bazel only makes declared files visible in the context where they were declared. The lower-level mechanics of how those prepared directories are assembled come later in 5.8 Sandboxing.

Create a runfiles object with ctx.runfiles() and pass it through DefaultInfo(runfiles = ...).⁶

def _viewer_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "#!/usr/bin/env bash\necho viewer ready\n",
        is_executable = True,
    )

    runfiles = ctx.runfiles(files = ctx.files.data)

    return [DefaultInfo(
        files = depset([out]),
        executable = out,
        runfiles = runfiles,
    )]

ctx.runfiles(files = ...) adds direct runtime files. ctx.runfiles(transitive_files = ...) adds a depset of runtime files, and that depset should use the default order.⁷ The older collect_data and collect_default parameters still exist, but the API docs mark both as not recommended. Write the collection logic explicitly so the rule's runtime contract is visible in the implementation.⁸

Merging Dependency Runfiles

Runtime files usually do not stop at the current target. A binary may need its own data, the runtime files of libraries in deps, and the runtime files attached to filegroup-like targets in srcs or data. The common pattern starts with direct files, collects target[DefaultInfo].default_runfiles from dependency attributes, and merges them into one runfiles object.⁹

def _collect_runfiles(ctx):
    direct = ctx.runfiles(files = ctx.files.data)

    transitive = []
    for attr in (ctx.attr.srcs, ctx.attr.deps, ctx.attr.data):
        for target in attr:
            transitive.append(target[DefaultInfo].default_runfiles)

    return direct.merge_all(transitive)

Use merge_all() when combining many runfiles objects. The runfiles API explicitly warns that calling merge() repeatedly in a loop can construct deep depset structures and cause build failures.¹⁰ This is the same performance shape as repeated depset wrapping: collect the children, merge once, and keep the structure shallow.

The default_runfiles field appears in that collection code because dependencies expose their already-computed runfiles through DefaultInfo. New rules should still return the unified runfiles parameter, not the legacy constructor split between data_runfiles and default_runfiles.¹¹ Maintaining old rulesets that rely on the split belongs in 4.4.5 Legacy Runfiles Split.

Trace The Producer, Consumer, And Runtime

A useful way to review any runfiles design is to trace one file across three boundaries:

1. Producer: a rule declares the file as runtime data and publishes it in a DefaultInfo runfiles set.
2. Consumer: an executable or an intermediate rule depends on that target and, when it republishes a runtime contract, merges the dependency's runfiles into the set it carries forward.
3. Runtime: the launched program resolves the file's logical runfiles name through its language library instead of guessing a working-directory or output-tree path.

Each boundary has a different failure. Omitting the file at the producer loses it from the contract. Failing to merge it at an intermediate consumer breaks transitive propagation. Hard-coding a physical path at runtime makes the program depend on one materialization layout. 1.1.2 bazel run & Runfiles shows the operator-visible result of a missing or mislocated runfile. L2.1.7 Generated Sources, Data & Runfiles applies the final lookup step with the C++ library, and L11.5 Publishing, RIDs & Runfiles shows why a later publish or packaging step must preserve the same runtime set.

Executable Targets And Files-To-Run

For executable or test rules, DefaultInfo(executable = out) tells Bazel which output to invoke for bazel run or bazel test.¹² The executable is added to the rule's default outputs and to its runfiles, so you do not need to list the same file in both files and executable.¹³

DefaultInfo.files_to_run exposes a FilesToRunProvider: the executable plus the metadata Bazel needs to run it, including runfiles manifest and repository mapping manifest fields when present.¹⁴ You do not construct this provider directly. Bazel derives it from executable targets and makes it available through DefaultInfo.files_to_run.¹⁵

That distinction matters when one rule uses another target as a tool. ctx.executable._tool is the convenient File for an executable label attr, but ctx.actions.run() can also accept a FilesToRunProvider as the action executable, and its tools parameter can accept FilesToRunProvider values so tool runfiles are automatically made available to the action.¹⁶ Use the file shortcut for simple tools. Reach for the files-to-run bundle when the tool's own runfiles are part of the action contract.

Runtime Lookup Is A Program Concern

A rule author decides what belongs in runfiles. The program decides how to locate those files at runtime. Do not design a rule API that assumes every platform exposes a Unix-style symlink tree. Bazel may materialize runfiles as a symlink tree on Linux/macOS, while Windows commonly uses a manifest file, and Bzlmod adds repository mapping to the lookup problem.¹⁷

The practical rule is: put the right files in runfiles, then let runtime code use the language's Bazel runfiles library or $(rlocationpath ...)-style values when it needs stable lookup paths.¹⁸ If the executable starts subprocesses that also need runfiles, propagate the runfiles library's environment variables to those subprocesses.¹⁹

The mini-ruleset shows both shapes in one file: glyph_library returns default outputs plus transitive runfiles, while glyph_binary returns an executable with its launch-time runfiles.