Skip to content

Fix outdated information in output directory layout docs.#29271

Open
philwo wants to merge 1 commit intobazelbuild:masterfrom
philwo:outputdirs-docs
Open

Fix outdated information in output directory layout docs.#29271
philwo wants to merge 1 commit intobazelbuild:masterfrom
philwo:outputdirs-docs

Conversation

@philwo
Copy link
Copy Markdown
Member

@philwo philwo commented Apr 11, 2026

Description

  • 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

Motivation

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

  • I have added tests for the new use cases (if any).
  • I have updated the documentation (if applicable).

Release Notes

RELNOTES: None

- 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
Copilot AI review requested due to automatic review settings April 11, 2026 09:33
@github-actions github-actions bot added team-Documentation Documentation improvements that cannot be directly linked to other team labels awaiting-review PR is awaiting review from an assigned reviewer labels Apr 11, 2026
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/, replaces host/ with exec config naming, updates config mnemonics).
  • Updates server directory description (TCP command port + related files).
  • Revises bazel clean description 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.

Comment on lines +147 to +149
`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
Copy link

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Suggested change
`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

Copilot uses AI. Check for mistakes.
Comment on lines +146 to +149
`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.
Copy link

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Suggested change
`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.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting-review PR is awaiting review from an assigned reviewer team-Documentation Documentation improvements that cannot be directly linked to other team labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants