bazel: build and package man pages as runfiles by alokkumardalei-wq · Pull Request #9766 · The-OpenROAD-Project/OpenROAD

alokkumardalei-wq · 2026-03-14T20:20:28Z

What does this PR do?

Fixes #7117 — Bazel build now generates and packages man pages

The Bazel build was missing man pages for both the man command and the GUI help browser.

Added a man_pages Bazel rule (
man_pages.bzl
) that runs the existing docs Makefile to generate cat/ and html/ pages from the module READMEs. The output is packaged as runfiles alongside the openroad binary.

Updated getDocsPath() to check for the Bazel runfiles layout (.runfiles/openroad/docs/) before falling back to the installed path.

Verification/Testing

bazel build //docs:man_pages

Expected output:

INFO: Invocation ID: e5407d31-853c-4d14-ba5d-f6352d3f1eb0
INFO: Analyzed target //docs:man_pages (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
Target //docs:man_pages up-to-date:
  bazel-bin/docs/cat
  bazel-bin/docs/html
INFO: Elapsed time: 147.810s, Critical Path: 0.24s
INFO: 1 process: 1 internal.
INFO: Build completed successfully, 1 total action

gemini-code-assist

Code Review

This pull request introduces a new Bazel rule to build and package man pages, making them available to the openroad binary as runfiles. This is a valuable addition that improves the build process. My review focuses on enhancing the robustness and maintainability of the new Bazel rule and improving the portability of the C++ code that locates the generated documentation at runtime.

github-actions · 2026-03-14T20:27:19Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-03-14T20:35:30Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-03-14T20:42:00Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-03-14T20:48:33Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-03-14T21:03:02Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-03-14T21:29:30Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-03-14T21:39:06Z

clang-tidy review says "All clean, LGTM! 👍"

gadfort · 2026-03-15T19:24:04Z

When I try this I get:

make: mkdir: No such file or directory
make: *** [Makefile:76: man/man1] Error 127
make: mkdir: No such file or directory
make: *** [Makefile:78: man/man2] Error 127
make: mkdir: No such file or directory
make: *** [Makefile:82: html/html1] Error 127
make: mkdir: No such file or directory
make: *** [Makefile:84: html/html2] Error 127
make: mkdir: No such file or directory
make: *** [Makefile:88: cat/cat1] Error 127
make: mkdir: No such file or directory
make: *** [Makefile:90: cat/cat2] Error 127
make: Target 'all' not remade because of errors.

and no files are created in the runfiles.

github-actions · 2026-03-16T16:58:36Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-03-16T17:15:17Z

clang-tidy review says "All clean, LGTM! 👍"

alokkumardalei-wq · 2026-03-16T17:48:33Z

Hello @gadfort I think this is due to PATH environment problem in Bazel's sandboxed execution on macOS. I have fixed that I want you to have look into this when you have time and happy to address further feedback.

Thank you!

alokkumardalei-wq · 2026-03-17T13:53:32Z

Hello @gadfort all checks are passing now ,please have a look onto this when you have time .
Thank you!

gadfort · 2026-03-17T15:50:40Z

It builds, but ord::get_docs_path is pointing to a directory that doesn't exist.

github-actions · 2026-03-17T18:29:42Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-03-17T18:38:49Z

clang-tidy review says "All clean, LGTM! 👍"

alokkumardalei-wq · 2026-03-17T18:40:20Z

Hello @gadfort,
You're absolutely right - I had the wrong repository name in the runfiles path. Fixed in commit d00e7866aa.
The code was looking for runfiles->Rlocation("openroad/docs") but the actual path is _main/docs because that's the Bazel repository name.

Please have a look onto this and happy to address any further feedback.

Thank you!

github-actions · 2026-03-17T18:43:22Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-04-12T09:55:51Z

clang-tidy review says "All clean, LGTM! 👍"

alokkumardalei-wq · 2026-04-12T10:37:45Z

Hello @maliberty and @gadfort thanks for your feedback and time, all checks are passing and I have addressed all your
feedback , please have a look when you have time . I would be happy to address any feedback further .

Thank you !

maliberty · 2026-04-13T16:00:22Z

% bazel build //docs:man_pages
INFO: Invocation ID: aab259c6-219e-4d34-9239-d4c74732a020
WARNING: Target pattern parsing failed.
ERROR: Skipping '//docs:man_pages': no such package 'docs': BUILD file not found in any of the following directories. Add a BUILD file to a directory to mark it as a package.
 - docs
ERROR: no such package 'docs': BUILD file not found in any of the following directories. Add a BUILD file to a directory to mark it as a package.
 - docs
INFO: Elapsed time: 0.196s
INFO: 0 processes.
ERROR: Build did NOT complete successfully

github-actions · 2026-04-14T04:14:22Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-04-14T04:36:00Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-04-14T04:48:14Z

clang-tidy review says "All clean, LGTM! 👍"

alokkumardalei-wq · 2026-04-14T04:56:12Z

% bazel build //docs:man_pages
INFO: Invocation ID: aab259c6-219e-4d34-9239-d4c74732a020
WARNING: Target pattern parsing failed.
ERROR: Skipping '//docs:man_pages': no such package 'docs': BUILD file not found in any of the following directories. Add a BUILD file to a directory to mark it as a package.
 - docs
ERROR: no such package 'docs': BUILD file not found in any of the following directories. Add a BUILD file to a directory to mark it as a package.
 - docs
INFO: Elapsed time: 0.196s
INFO: 0 processes.
ERROR: Build did NOT complete successfully

Hello , @maliberty now you can check the same , it is fixed docs/BUILD.bazel and bazel/man_pages.bzl are now included. It should build successfully now .

alokkumardalei-wq · 2026-04-18T13:10:53Z

Hello @maliberty @gadfort , all checks are passing ,please have a look onto this when you get time.

Thank you !

maliberty · 2026-04-18T14:42:35Z

/gemini review

maliberty · 2026-04-18T14:42:42Z

@codex review

gemini-code-assist

Code Review

This pull request introduces a new Bazel rule, man_pages, to automate the generation of man pages and HTML documentation from module READMEs, integrating with the existing documentation Makefile. It also updates the OpenRoad class to locate these documents within the Bazel runfiles directory and refactors runfiles management in regression tests. Review feedback focuses on improving the robustness of the shell commands within the Bazel rule—specifically by avoiding silent failures and handling empty output directories—and notes the fragility of hardcoding the workspace name in the runfiles path lookup.

gemini-code-assist · 2026-04-18T14:44:26Z

+cd docs
+
+# Symlink module READMEs into md/man2/
+bash src/scripts/link_readmes.sh 2>/dev/null || true


Masking errors with || true and redirecting stderr to /dev/null can lead to silent failures during the documentation generation process. If the script fails, the resulting man pages might be incomplete or incorrect. It is better to allow the script to fail the build so that issues can be identified and fixed.

Suggested change

bash src/scripts/link_readmes.sh 2>/dev/null || true

bash src/scripts/link_readmes.sh

gemini-code-assist · 2026-04-18T14:44:26Z

+cp -r docs/cat/* {cat_out}/
+cp -r docs/html/* {html_out}/


Using the * glob in the cp command will cause the shell to fail if the source directory is empty (which might happen if the make command fails to produce output but doesn't return a non-zero exit code). Using . is a more robust way to copy the contents of the directory.

Suggested change

cp -r docs/cat/* {cat_out}/

cp -r docs/html/* {html_out}/

cp -r docs/cat/. {cat_out}/

cp -r docs/html/. {html_out}/

gemini-code-assist · 2026-04-18T14:44:26Z


+  // Check Bazel runfiles layout first
+  const std::filesystem::path runfiles_docs
+      = std::filesystem::path(exe + ".runfiles") / "_main" / "docs";


Hardcoding _main as the workspace name is fragile. While _main is the default in modern Bazel versions, it can be overridden in the MODULE.bazel or WORKSPACE file. This logic will break if the workspace is renamed.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d073a29ad8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-18T14:52:43Z

+man_pages(
+    name = "man_pages",


Add //docs:man_pages to the openroad data deps

This target is defined but never consumed by the //:openroad binary, so the new getDocsPath() probe for <exe>.runfiles/_main/docs will not find generated docs during bazel run //:openroad. I checked for //docs:man_pages references and it only appears in this file, which means the man pages are built in isolation but not packaged with the executable’s runfiles; man/GUI help remains unavailable in Bazel-run binaries.

Useful? React with 👍 / 👎.

This matches my experience, man in the application doesn't find anything

chatgpt-codex-connector · 2026-04-18T14:52:43Z

+
+    ctx.actions.run_shell(
+        outputs = [cat_dir, html_dir],
+        inputs = ctx.files.docs_srcs + ctx.files.scripts + ctx.files.readmes,


Declare man3 messages files as Bazel action inputs

md_roff_compat.py generates man3 pages from ../src/*/messages.txt and ../messages.txt, but this action only declares docs_srcs, scripts, and readmes as inputs. In Bazel sandboxing those message files are missing, so man3() skips them and cat3/html3 outputs are incomplete, which breaks lookups for message-ID documentation. Add the messages files as explicit attrs and include them in inputs.

Useful? React with 👍 / 👎.

alokkumardalei-wq · 2026-04-19T02:55:53Z

Hello @maliberty , Fixed- the man pages target was being built but never added to the binary's runfiles, so getDocsPath() had nothing to find. Added //docs:man_pages as a data dependency of //:openroad. Also declared messages.txt files as explicit inputs so man3 pages generate correctly in sandboxed builds.

Please have a look onto this when you get time.

Thank you !

github-actions · 2026-04-19T02:58:32Z

clang-tidy review says "All clean, LGTM! 👍"

github-actions · 2026-04-19T03:46:23Z

clang-tidy review says "All clean, LGTM! 👍"

alokkumardalei-wq · 2026-04-19T03:50:58Z

@maliberty what's the best way to reach you - discord/slack, email, or here on GitHub?

github-actions · 2026-04-19T05:07:05Z

clang-tidy review says "All clean, LGTM! 👍"

Signed-off-by: alokkumardalei-wq <alokkumardalei2@gmail.com>

github-actions · 2026-04-19T05:23:48Z

clang-tidy review says "All clean, LGTM! 👍"

gemini-code-assist bot reviewed Mar 14, 2026

View reviewed changes

Comment thread bazel/man_pages.bzl Outdated

Comment thread bazel/man_pages.bzl Outdated

Comment thread bazel/man_pages.bzl Outdated

Comment thread src/OpenRoad.cc Outdated

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from b02b33d to cb4284b Compare March 14, 2026 20:29

alokkumardalei-wq force-pushed the feature/bazel-manpage branch 2 times, most recently from abb37f2 to 4f974a0 Compare March 14, 2026 20:41

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from 4f974a0 to 20a70f9 Compare March 14, 2026 20:56

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from 20a70f9 to 57a1471 Compare March 14, 2026 21:21

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from 57a1471 to 693980d Compare March 14, 2026 21:32

alokkumardalei-wq mentioned this pull request Mar 14, 2026

bazel - manpage missing #7117

Open

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from 068e6ad to 0070f75 Compare March 16, 2026 17:08

alokkumardalei-wq force-pushed the feature/bazel-manpage branch 2 times, most recently from 0070f75 to 693980d Compare March 17, 2026 18:32

This was referenced Mar 18, 2026

Install should not expect an orfs install. #9775

Open

Add a bazelisk run :tidy that tidies up the code across all languages #8495

Closed

github-actions bot added the size/S label Apr 12, 2026

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from fec1f74 to 982e88e Compare April 14, 2026 04:06

github-actions bot added size/M and removed size/S labels Apr 14, 2026

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from ced4ab9 to 44a564d Compare April 14, 2026 04:29

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from 6ee2f47 to d073a29 Compare April 14, 2026 04:42

gemini-code-assist bot reviewed Apr 18, 2026

View reviewed changes

chatgpt-codex-connector bot reviewed Apr 18, 2026

View reviewed changes

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from d073a29 to 1638325 Compare April 19, 2026 02:45

alokkumardalei-wq requested a review from maliberty April 19, 2026 02:56

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from f9da33f to d96b6de Compare April 19, 2026 03:39

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from aadcb10 to a973981 Compare April 19, 2026 05:01

chore: fix package boundary violation and buildifier warnings

cdd3028

Signed-off-by: alokkumardalei-wq <alokkumardalei2@gmail.com>

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from a973981 to cdd3028 Compare April 19, 2026 05:17

	bash src/scripts/link_readmes.sh 2>/dev/null \|\| true
	bash src/scripts/link_readmes.sh

Conversation

alokkumardalei-wq commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Verification/Testing

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

gadfort commented Mar 15, 2026

Uh oh!

github-actions bot commented Mar 16, 2026

Uh oh!

github-actions bot commented Mar 16, 2026

Uh oh!

alokkumardalei-wq commented Mar 16, 2026

Uh oh!

alokkumardalei-wq commented Mar 17, 2026

Uh oh!

gadfort commented Mar 17, 2026

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

alokkumardalei-wq commented Mar 17, 2026

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

github-actions bot commented Apr 12, 2026

Uh oh!

alokkumardalei-wq commented Apr 12, 2026

Uh oh!

maliberty commented Apr 13, 2026

Uh oh!

github-actions bot commented Apr 14, 2026

Uh oh!

github-actions bot commented Apr 14, 2026

Uh oh!

github-actions bot commented Apr 14, 2026

Uh oh!

alokkumardalei-wq commented Apr 14, 2026

Uh oh!

alokkumardalei-wq commented Apr 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maliberty commented Apr 18, 2026

Uh oh!

maliberty commented Apr 18, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Apr 18, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Apr 18, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Apr 18, 2026

alokkumardalei-wq commented Mar 14, 2026 •

edited

Loading

alokkumardalei-wq commented Apr 18, 2026 •

edited

Loading

alokkumardalei-wq commented Apr 19, 2026 •

edited

Loading

alokkumardalei-wq commented Apr 19, 2026 •

edited

Loading