docs: make //docs:man_pages hermetic by managing pandoc via Bazel#10764
Open
luarss wants to merge 4 commits into
Open
docs: make //docs:man_pages hermetic by managing pandoc via Bazel#10764luarss wants to merge 4 commits into
luarss wants to merge 4 commits into
Conversation
The previous rule called make, pandoc, nroff, and col via the host PATH with use_default_shell_env=True and no-sandbox=1, breaking hermetic and remote-execution builds (issue The-OpenROAD-Project#10692). Changes: - MODULE.bazel: add http_archive downloads of pandoc 3.10 pre-built binaries for Linux amd64/arm64 and macOS x86_64/arm64 (pandoc is not on BCR yet). - bazel/BUILD: add config_setting per platform, a filegroup that selects the right pandoc binary, and a py_binary driver. - bazel/manpages_impl.py: new Python driver that replaces make + link_readmes.sh + nroff/col. All inputs arrive as explicit CLI args; pandoc --to=plain replaces nroff -man | col -b. - bazel/man_pages.bzl: rewrite to use ctx.actions.run with declared tool inputs; removes use_default_shell_env and no-sandbox. - docs/BUILD.bazel: drop Makefile and link_readmes.sh from inputs. Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
Add //docs:man_pages_build_test to catch regressions in the hermetic man page build. Remove the now-dead bazel-manpages Makefile target which was previously called by Bazel but is no longer needed since manpages_impl.py drives the build directly. Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request replaces the host-dependent make and nroff workflow for generating man pages with a hermetic Bazel rule. It downloads pre-built platform-specific pandoc binaries and orchestrates the generation using a new Python driver script (manpages_impl.py). The review feedback highlights two important issues in the new Python script: first, pandoc needs an explicit -f man format specification when reading generated roff files to prevent them from being parsed as markdown; second, the script should preserve and append to the existing PYTHONPATH instead of overwriting it entirely, which could break Bazel's Python runtime environment.
- Add docstrings to _run_pandoc, _process_section, and main() - Document skip_stems parameter in _process_section - Clarify messages.txt copy comment - Fix capitalization in man_pages.bzl module docstring (html → HTML) Signed-off-by: Jack Luar <39641663+luarss@users.noreply.github.com>
Contributor
Author
|
Comments fixed in 0fe6274 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The previous rule called make, pandoc, nroff, and col via the host PATH with use_default_shell_env=True and no-sandbox=1, breaking hermetic and remote-execution builds (issue #10692).
Summary
MODULE.bazel: download pandoc 3.10 pre-built binaries for Linux amd64/arm64 and macOS x86_64/arm64 viahttp_archive(pandoc is not on BCR).bazel/BUILD: addconfig_settingper platform, afilegroupthat selects the correct pandoc binary at build time, and apy_binarydrivertarget.
bazel/manpages_impl.py: new Python driver replacingmake+link_readmes.sh+nroff/col. All inputs (pandoc binary, README files, messages,scripts) arrive as explicit CLI arguments;
pandoc --to=plainreplacesnroff -man | col -bfor cat pages.bazel/man_pages.bzl: rewritten to usectx.actions.runwith declared tool inputs; removesuse_default_shell_envandno-sandbox.docs/BUILD.bazel: dropMakefileandlink_readmes.shfrom inputs; add//docs:man_pages_build_testto catch regressions.docs/Makefile: remove deadbazel-manpagestarget (no longer called by Bazel).Type of Change
Impact
[How does this change the tool's behavior?]
Verification
./etc/Build.sh).Related Issues
fixes #10692