bazelbuild / bazelbuild/bazel

Documentation issue: When do binary runfiles get invalidated by `bazel build`, etc?

Open
#13,225 0 comments 0 reactions 0 assignees View on GitHub
help wanted P3 team-Documentation team-Rules-Server type: documentation (cleanup)
Dominant language
Java
Stars
25.8k
Forks
4.6k
Avg merge
2d 18h
Merged PRs (30d)
75

Description

### Description of the problem / feature request:

With help from colleagues, I've built an internal model of when to expect my runfiles to become stale (e.g. should be rebuilt) and/or invalidated (rebuilt due to an update / action env change / etc.).

As I look through the Bazel docs for 4.0.0, I can't seem to find a brief summary of this setup.

(It could be I was looking for the wrong thing / didn't look in enough places?)

Closest I got was stumbling around w/ search and clicking on the wesbite and coming across stuff like this:
https://docs.bazel.build/versions/4.0.0/skylark/rules.html#runfiles

### Feature requests: what underlying problem are you trying to solve with this feature?

Better docs!

### Bugs: what's the simplest, easiest way to reproduce this bug? Please provide a minimal example if possible.

Docs! Couldn't easily find a place where this is. (Maybe I didn't search correctly?)

### What operating system are you running Bazel on?

Ubuntu 18.04.5

### What's the output of `bazel info release`?

`release 4.0.0`

### If `bazel info release` returns "development version" or "(@non-git)", tell us how you built Bazel.

N/A

### What's the output of `git remote get-url origin ; git rev-parse master ; git rev-parse HEAD` ?

https://github.com/RobotLocomotion/drake
693c8497ff4d8bb7869ccbf0a9d8fbe90aa8c92d
693c8497ff4d8bb7869ccbf0a9d8fbe90aa8c92d

### Have you found anything relevant by searching the web?

Searched for `runfiles invalidation`, but didn't see much aside from the above doc link, and stuff like this:

- https://docs.bazel.build/versions/4.0.0/glossary.html#runfiles
- https://docs.bazel.build/versions/4.0.0/glossary.html#action-key
- https://docs.bazel.build/versions/4.0.0/output_directories.html
- https://docs.bazel.build/versions/4.0.0/user-manual.html#flag--workspace_status_command

### Any other information, logs, or outputs that you want to share?

Nah. But thanks for asking!

Contributor guide

Open the contributing guide

Research direction

Start by reading the linked runfiles, glossary, output_directories, and user-manual documentation for Bazel 4.0.0, focusing on action keys and runfile invalidation. Document a brief, findable explanation of when binary runfiles become stale or are rebuilt, with the relevant existing references linked.

Written by the indexing model from the issue text.

Assessment

Domain
build-system, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.