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.

gemini-code-assist · 2026-03-14T20:23:14Z

bazel/man_pages.bzl

+    html_dir = ctx.actions.declare_directory("html")
+
+    # Build a map of script basename -> path for easy lookup
+    scripts_by_name = {f.basename: f.path for f in ctx.files.scripts}


The use of .get(script_name, "") on lines 77-80 can lead to cryptic cp errors if a required script is not provided in the scripts attribute. A more robust approach would be to explicitly check for the required scripts and fail with a clear error message if any are missing. After this check, you can directly access the script paths without .get().

For example, you could add this check after building scripts_by_name:

required_scripts = [ "link_readmes.sh", "md_roff_compat.py", "manpage.py", "extract_utils.py", ] for script in required_scripts: if script not in scripts_by_name: fail("Script '{}' is missing from the 'scripts' attribute".format(script))

And then in the .format() call, use direct access like scripts_by_name["link_readmes.sh"].

gemini-code-assist · 2026-03-14T20:23:14Z

bazel/man_pages.bzl

+        command = """
+set -euo pipefail
+
+# Ensure system tools like pandoc and nroff are available
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+WORK_DIR=$(mktemp -d)
+trap "rm -rf $WORK_DIR" EXIT
+EXECROOT=$(pwd)
+
+# Set up docs directory structure
+mkdir -p "$WORK_DIR/md/man1"
+mkdir -p "$WORK_DIR/md/man2"
+mkdir -p "$WORK_DIR/md/man3"
+mkdir -p "$WORK_DIR/src/scripts"
+
+# Copy scripts and Makefile
+cp {link_readmes} "$WORK_DIR/src/scripts/link_readmes.sh"
+cp {md_roff_compat} "$WORK_DIR/src/scripts/md_roff_compat.py"
+cp {manpage} "$WORK_DIR/src/scripts/manpage.py"
+cp {extract_utils} "$WORK_DIR/src/scripts/extract_utils.py"
+cp {makefile} "$WORK_DIR/Makefile"
+
+# Copy man1 sources
+for f in {man1_srcs}; do
+    cp "$f" "$WORK_DIR/md/man1/"
+done
+
+# Copy man2 README sources (named by module directory)
+for f in {man2_srcs}; do
+    module=$(basename $(dirname $f))
+    cp "$f" "$WORK_DIR/md/man2/${{module}}.md"
+done
+
+# Run the Python preprocessor to generate per-function man2/man3 pages
+cd "$WORK_DIR"
+python3 src/scripts/md_roff_compat.py
+
+# Remove any malformed output files (e.g. '#.md' from READMEs with bad function names)
+find "$WORK_DIR/md" -name '#*.md' -delete 2>/dev/null || true
+
+# Build all man page formats; use -k to continue past nroff warnings
+make all -k -j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 2) || true
+
+# Ensure output subdirs exist even if some pages failed to build
+mkdir -p "$WORK_DIR/cat/cat1" "$WORK_DIR/cat/cat2" "$WORK_DIR/cat/cat3"
+mkdir -p "$WORK_DIR/html/html1" "$WORK_DIR/html/html2" "$WORK_DIR/html/html3"
+
+# Copy outputs into the Bazel-declared output directories (paths are execroot-relative)
+mkdir -p "$EXECROOT/{cat_out}" "$EXECROOT/{html_out}"
+cp -r "$WORK_DIR/cat/." "$EXECROOT/{cat_out}/"
+cp -r "$WORK_DIR/html/." "$EXECROOT/{html_out}/"
+""".format(
+            link_readmes = scripts_by_name.get("link_readmes.sh", ""),
+            md_roff_compat = scripts_by_name.get("md_roff_compat.py", ""),
+            manpage = scripts_by_name.get("manpage.py", ""),
+            extract_utils = scripts_by_name.get("extract_utils.py", ""),
+            makefile = ctx.file.makefile.path,
+            man1_srcs = " ".join([f.path for f in ctx.files.man1_srcs]),
+            man2_srcs = " ".join([f.path for f in ctx.files.man2_srcs]),
+            cat_out = cat_dir.path,
+            html_out = html_dir.path,
+        ),


The shell script embedded in the command attribute is quite long and complex. For better maintainability, readability, and testability, consider moving this script to a separate file (e.g., man_pages.sh.tpl) and using ctx.actions.expand_template to substitute the values.

gemini-code-assist · 2026-03-14T20:23:14Z

bazel/man_pages.bzl

+set -euo pipefail
+
+# Ensure system tools like pandoc and nroff are available
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"


Hardcoding paths like /opt/homebrew/bin can make the build less portable, as tool locations can vary between operating systems, distributions, and user configurations. While this might work for the current primary development environments, a more robust solution would be to rely on the tools being in the system PATH.

gemini-code-assist · 2026-03-14T20:23:14Z

src/OpenRoad.cc

+  const std::filesystem::path runfiles_docs
+      = std::filesystem::path(exe + ".runfiles") / "openroad" / "docs";
+  if (std::filesystem::exists(runfiles_docs)) {
+    return runfiles_docs;
+  }


Manually constructing the runfiles path with exe + ".runfiles" is not fully portable (e.g., it differs on Windows) and can be brittle. Since this target already depends on the Bazel runfiles library, it would be more robust to use it to locate the docs directory. This would abstract away the platform-specific details of the runfiles layout.

Example using the runfiles library:

#include "tools/cpp/runfiles/runfiles.h" // ... in a function that has access to argv[0] or exe path std::string error; std::unique_ptr<bazel::tools::cpp::runfiles::Runfiles> runfiles( bazel::tools::cpp::runfiles::Runfiles::Create(getExePath(), &error)); // ... error handling ... std::string docs_path = runfiles->Rlocation("openroad/docs"); if (!docs_path.empty() && std::filesystem::exists(docs_path)) { return docs_path; }

This change would make your code more portable and less dependent on the specifics of Bazel's runfiles implementation.

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 d00e786.
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-01T21:10:48Z

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

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

github-actions · 2026-04-01T21:37:18Z

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

github-actions · 2026-04-01T21:38:55Z

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

gemini-code-assist bot reviewed Mar 14, 2026

View reviewed changes

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

Open

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from 693980d to 8fa8bfe Compare April 1, 2026 21:01

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from e1fa556 to bc10b91 Compare April 1, 2026 21:34

chore: fix package boundary violation and buildifier warnings

3eb3e7a

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

alokkumardalei-wq force-pushed the feature/bazel-manpage branch from bc10b91 to 3eb3e7a Compare April 1, 2026 21:36

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!

gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

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 1, 2026

Uh oh!

github-actions bot commented Apr 1, 2026

Uh oh!

github-actions bot commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alokkumardalei-wq commented Mar 14, 2026 •

edited

Loading