Documentation issue: When do binary runfiles get invalidated by `bazel build`, etc?
- 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
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