Fix outdated information in output directory layout docs.#29271
Fix outdated information in output directory layout docs.#29271philwo wants to merge 1 commit intobazelbuild:masterfrom
Conversation
- Replace nonexistent `_embedded_binaries/` with actual installBase contents (A-server.jar, linux-sandbox, process-wrapper, embedded_tools/) - Fix `bazel clean` description: it deletes the entire execroot, not just outputPath and action_cache - Remove `genfiles/` from the layout diagram (merged into bin/ by default) - Replace obsolete `host/` config with modern exec config (k8-opt-exec/) - Update config directory naming from `local_linux-fastbuild/` to the actual `k8-fastbuild/` scheme with explanation of the mnemonic format - Fix server directory description: Bazel uses TCP, not Unix sockets - Fix minor formatting issues and sync content between .md and .mdx
There was a problem hiding this comment.
Pull request overview
Updates the Bazel output directory layout documentation to reflect current on-disk structure and behavior (installBase contents, configuration directory naming, server directory details, and bazel clean semantics), and keeps the .md and .mdx versions aligned.
Changes:
- Refreshes the layout diagram (installBase contents, removes
genfiles/, replaceshost/with exec config naming, updates config mnemonics). - Updates server directory description (TCP command port + related files).
- Revises
bazel cleandescription and fixes minor formatting/wording inconsistencies.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| site/en/remote/output-directories.md | Updates the output directory layout and bazel clean docs for the site-rendered Markdown version. |
| docs/remote/output-directories.mdx | Mirrors the same documentation updates for the MDX docs pipeline. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| `bazel clean` clears the on-disk action cache and then removes the entire | ||
| `execroot` directory (which contains the symlink forest and all build | ||
| outputs). It also removes the convenience symlinks from the workspace |
There was a problem hiding this comment.
The text says bazel clean "removes the entire execroot directory", but the implementation removes the contents under outputBase/execroot (via execroot.deleteTreesBelow()) and does not delete the execroot directory itself in the default synchronous mode. Consider rewording to something like "deletes everything under execroot" / "clears execroot" (and optionally call out that --async may temporarily rename the directory before deletion). Reference: src/main/java/com/google/devtools/build/lib/runtime/commands/CleanCommand.java (around the execroot.deleteTreesBelow() call).
| `bazel clean` clears the on-disk action cache and then removes the entire | |
| `execroot` directory (which contains the symlink forest and all build | |
| outputs). It also removes the convenience symlinks from the workspace | |
| `bazel clean` clears the on-disk action cache and then deletes everything | |
| under the `execroot` directory (which contains the symlink forest and all | |
| build outputs). It also removes the convenience symlinks from the workspace |
| `bazel clean` clears the on-disk action cache and then removes the entire | ||
| `execroot` directory (which contains the symlink forest and all build | ||
| outputs). It also removes the convenience symlinks from the workspace | ||
| directory. The `--expunge` option will clean the entire outputBase. |
There was a problem hiding this comment.
The text says bazel clean "removes the entire execroot directory", but the implementation removes the contents under outputBase/execroot (via execroot.deleteTreesBelow()) and does not delete the execroot directory itself in the default synchronous mode. Consider rewording to something like "deletes everything under execroot" / "clears execroot" (and optionally call out that --async may temporarily rename the directory before deletion). Reference: src/main/java/com/google/devtools/build/lib/runtime/commands/CleanCommand.java (around the execroot.deleteTreesBelow() call).
| `bazel clean` clears the on-disk action cache and then removes the entire | |
| `execroot` directory (which contains the symlink forest and all build | |
| outputs). It also removes the convenience symlinks from the workspace | |
| directory. The `--expunge` option will clean the entire outputBase. | |
| `bazel clean` clears the on-disk action cache and then deletes everything | |
| under `execroot` (which contains the symlink forest and all build outputs). | |
| It also removes the convenience symlinks from the workspace directory. The | |
| `--expunge` option will clean the entire outputBase. |
Description
_embedded_binaries/with actual installBase contents (A-server.jar, linux-sandbox, process-wrapper, embedded_tools/)bazel cleandescription: it deletes the entire execroot, not just outputPath and action_cachegenfiles/from the layout diagram (merged into bin/ by default)host/config with modern exec config (k8-opt-exec/)local_linux-fastbuild/to the actualk8-fastbuild/scheme with explanation of the mnemonic formatMotivation
Correct docs are important. :) I just came across it while refreshing my knowledge about Bazel internals so that I can explain them to a colleague.
Build API Changes
No
Checklist
Release Notes
RELNOTES: None