Skip to content

Commit 1cf4ffa

Browse files
malibertymaliberty
authored
Merge pull request #9766 from alokkumardalei-wq/feature/bazel-manpage
bazel: build and package man pages as runfiles
2 parents af39e7f + 6a55ac1 commit 1cf4ffa

33 files changed

Lines changed: 255 additions & 27 deletions

File tree

‎bazel/Dockerfile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,16 @@ RUN install -m 0755 -d /etc/apt/keyrings \
1919

2020
RUN apt-get -y update \
2121
&& apt-get -y install --no-install-recommends \
22+
bsdextrautils \
2223
build-essential \
2324
clang \
2425
containerd.io \
2526
docker-buildx-plugin \
2627
docker-ce \
2728
docker-ce-cli \
29+
groff \
2830
openjdk-21-jre-headless \
31+
pandoc \
2932
python3 \
3033
python3-yaml \
3134
time

‎bazel/man_pages.bzl‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# SPDX-License-Identifier: BSD-3-Clause
2+
# Copyright (c) 2026, The OpenROAD Authors
3+
4+
"""Bazel rule that invokes docs/Makefile to produce cat/ and html/ man pages.
5+
6+
The output filenames aren't known at analysis time (they depend on which
7+
modules exist under src/*/), so outputs are declared as TreeArtifacts and
8+
the real work is delegated to the `bazel-manpages` Makefile target.
9+
10+
Host requirements: pandoc, nroff (groff), col (bsdextrautils), python3>=3.10.
11+
"""
12+
13+
def _man_pages_impl(ctx):
14+
cat_dir = ctx.actions.declare_directory("cat")
15+
html_dir = ctx.actions.declare_directory("html")
16+
17+
command = """
18+
set -euo pipefail
19+
CAT_OUT="$PWD/{cat_out}"
20+
HTML_OUT="$PWD/{html_out}"
21+
make --no-print-directory -C docs -f Makefile bazel-manpages \\
22+
CAT_ROOT_DIR="$CAT_OUT" HTML_ROOT_DIR="$HTML_OUT"
23+
""".format(
24+
cat_out = cat_dir.path,
25+
html_out = html_dir.path,
26+
)
27+
28+
ctx.actions.run_shell(
29+
outputs = [cat_dir, html_dir],
30+
inputs = ctx.files.docs_srcs + ctx.files.scripts + ctx.files.readmes + ctx.files.messages,
31+
command = command,
32+
mnemonic = "ManPages",
33+
progress_message = "Generating man pages (cat + html)",
34+
use_default_shell_env = True,
35+
execution_requirements = {"no-sandbox": "1"},
36+
)
37+
38+
return [DefaultInfo(
39+
files = depset([cat_dir, html_dir]),
40+
runfiles = ctx.runfiles(files = [cat_dir, html_dir]),
41+
)]
42+
43+
man_pages = rule(
44+
implementation = _man_pages_impl,
45+
attrs = {
46+
"docs_srcs": attr.label_list(
47+
doc = "All source files under docs/ needed by the Makefile.",
48+
allow_files = True,
49+
),
50+
"messages": attr.label_list(
51+
doc = "Module messages.txt files needed for man3 page generation.",
52+
allow_files = [".txt"],
53+
),
54+
"readmes": attr.label_list(
55+
doc = "Module README.md files (src/*/README.md).",
56+
allow_files = [".md"],
57+
),
58+
"scripts": attr.label_list(
59+
doc = "Python/shell scripts for man page generation.",
60+
allow_files = True,
61+
),
62+
},
63+
)

‎docs/BUILD.bazel‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# SPDX-License-Identifier: BSD-3-Clause
2+
# Copyright (c) 2026, The OpenROAD Authors
3+
4+
load("//bazel:man_pages.bzl", "man_pages")
5+
6+
man_pages(
7+
name = "man_pages",
8+
docs_srcs = [
9+
"Makefile",
10+
] + glob(["md/**/*.md"]),
11+
messages = [
12+
"//src/ant:messages_txt",
13+
"//src/cts:messages_txt",
14+
"//src/dbSta:messages_txt",
15+
"//src/dft:messages_txt",
16+
"//src/dpl:messages_txt",
17+
"//src/drt:messages_txt",
18+
"//src/dst:messages_txt",
19+
"//src/fin:messages_txt",
20+
"//src/gpl:messages_txt",
21+
"//src/grt:messages_txt",
22+
"//src/ifp:messages_txt",
23+
"//src/mpl:messages_txt",
24+
"//src/odb:messages_txt",
25+
"//src/pad:messages_txt",
26+
"//src/par:messages_txt",
27+
"//src/pdn:messages_txt",
28+
"//src/ppl:messages_txt",
29+
"//src/psm:messages_txt",
30+
"//src/rcx:messages_txt",
31+
"//src/rmp:messages_txt",
32+
"//src/rsz:messages_txt",
33+
"//src/stt:messages_txt",
34+
"//src/tap:messages_txt",
35+
"//src/upf:messages_txt",
36+
"//src/utl:messages_txt",
37+
],
38+
readmes = [
39+
"//src/ant:README.md",
40+
"//src/cts:README.md",
41+
"//src/dft:README.md",
42+
"//src/dpl:README.md",
43+
"//src/drt:README.md",
44+
"//src/fin:README.md",
45+
"//src/gpl:README.md",
46+
"//src/grt:README.md",
47+
"//src/gui:README.md",
48+
"//src/ifp:README.md",
49+
"//src/mpl:README.md",
50+
"//src/odb:README.md",
51+
"//src/pad:README.md",
52+
"//src/par:README.md",
53+
"//src/pdn:README.md",
54+
"//src/ppl:README.md",
55+
"//src/psm:README.md",
56+
"//src/rcx:README.md",
57+
"//src/rmp:README.md",
58+
"//src/rsz:README.md",
59+
"//src/stt:README.md",
60+
"//src/tap:README.md",
61+
"//src/upf:README.md",
62+
"//src/utl:README.md",
63+
],
64+
scripts = [
65+
"//docs/src/scripts:link_readmes.sh",
66+
"//docs/src/scripts:md_roff_compat.py",
67+
"//docs/src/scripts:manpage.py",
68+
"//docs/src/scripts:extract_utils.py",
69+
],
70+
visibility = ["//visibility:public"],
71+
)

‎docs/Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,8 +124,13 @@ $(CAT2_DIR)/%.2: $(CAT2_DIR)/%.md
124124
$(CAT3_DIR)/%.3: $(CAT3_DIR)/%.md
125125
mv $< $@
126126

127+
# Single-invocation target used by //docs:man_pages (Bazel). Chains the
128+
# preprocessing step (README symlinks + roff-compat conversion) with the
129+
# cat and web outputs that the Bazel rule copies into its declared outputs.
130+
bazel-manpages: preprocess cat web
131+
127132
# Phony targets
128-
.PHONY: all
133+
.PHONY: all bazel-manpages preprocess
129134

130135
# _____ _____ _ _ _____ _ ___ __
131136
# / ____| __ \| | | |_ _| \ | \ \ / /

‎docs/src/scripts/BUILD‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,10 @@ py_test(
1515
srcs = ["test_extract_utils.py"],
1616
deps = [":extract_utils"],
1717
)
18+
19+
exports_files([
20+
"md_roff_compat.py",
21+
"manpage.py",
22+
"link_readmes.sh",
23+
"extract_utils.py",
24+
])

‎src/ant/BUILD‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,5 +114,8 @@ filegroup(
114114
)
115115

116116
messages_txt(
117-
visibility = ["//src/ant/test:__pkg__"],
117+
visibility = [
118+
"//docs:__pkg__",
119+
"//src/ant/test:__pkg__",
120+
],
118121
)

‎src/cts/BUILD‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,5 +151,8 @@ filegroup(
151151
)
152152

153153
messages_txt(
154-
visibility = ["//src/cts/test:__pkg__"],
154+
visibility = [
155+
"//docs:__pkg__",
156+
"//src/cts/test:__pkg__",
157+
],
155158
)

‎src/dbSta/BUILD‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
load("@rules_cc//cc:cc_library.bzl", "cc_library")
55
load("//bazel:tcl_encode_or.bzl", "tcl_encode")
66
load("//bazel:tcl_wrap_cc.bzl", "tcl_wrap_cc")
7+
load("//test:regression.bzl", "messages_txt")
78

89
package(
910
default_visibility = ["//:__subpackages__"],
@@ -193,3 +194,7 @@ tcl_wrap_cc(
193194
"//src/odb:swig",
194195
],
195196
)
197+
198+
messages_txt(
199+
visibility = ["//docs:__pkg__"],
200+
)

‎src/dft/BUILD‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,5 +101,8 @@ filegroup(
101101
)
102102

103103
messages_txt(
104-
visibility = ["//src/dft/test:__pkg__"],
104+
visibility = [
105+
"//docs:__pkg__",
106+
"//src/dft/test:__pkg__",
107+
],
105108
)

‎src/dft/test/BUILD‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
load("@rules_python//python:defs.bzl", "py_test")
21
# SPDX-License-Identifier: BSD-3-Clause
32
# Copyright (c) 2022-2025, The OpenROAD Authors
43

54
# Test Parity Note: All tests from CMakeLists.txt are included in this BUILD file.
65
# No tests are intentionally excluded. See .kiro/specs/bazel-cmake-test-parity/intentional_exclusions.md
76

87
load("@rules_cc//cc:cc_test.bzl", "cc_test")
8+
load("@rules_python//python:defs.bzl", "py_test")
99
load("//test:regression.bzl", "doc_check_test", "regression_test")
1010

1111
package(features = ["layering_check"])

0 commit comments

Comments
 (0)