[rules score] make sphinx build fully hermetic

- include graphviz
- rework plantuml integration
- include graphbiz system deps as rootfs

Author: hoe-jo

MODULE.bazel

@@ -260,10 +260,16 @@ deb(
 )
 
 ###############################################################################
-# Graphviz deb package (cmake release; bundles all graphviz .so files so
-# dot_builtins runs without system graphviz installation)
-# Uses download_deb from @download_utils at a commit that includes
-# data.tar.gz support in download/deb/repository.bzl.
+# Graphviz (relocatable cmake-release deb)
+#
+# A relocatable graphviz build (RUNPATH $ORIGIN/../lib, ships a basename-based
+# config6 plugin manifest), so its dynamic `dot` runs from the Bazel execroot
+# without a system install. We use this build (not apt's `graphviz`) because
+# apt's is built for a fixed `/` install and relies on a postinst `dot -c` that
+# rules_distroless never runs, so it fails to load plugins when relocated.
+# The cmake deb bundles graphviz's own libs + plugins + config6; the external
+# system libs it needs (libexpat/libltdl/libz) come from the docs_runtime sysroot
+# below. See //third_party/docs_runtime/README.md.
 ###############################################################################
 deb(
     name = "graphviz_deb",
@@ -272,6 +278,33 @@ deb(
     urls = ["https://gitlab.com/api/v4/projects/4207231/packages/generic/graphviz-releases/12.2.1/ubuntu_24.04_graphviz-12.2.1-cmake.deb"],
 )
 
+###############################################################################
+# Hermetic doc-tool sysroot (docs_runtime)
+#
+# A small distroless rootfs supplying ONLY the external system shared libraries
+# the relocatable graphviz `dot` links against but does not bundle
+# (libexpat.so.1, libltdl.so.7, libz.so.1). Together with @graphviz_deb this
+# makes the doc build's dot fully hermetic (no host graphviz/system-lib needed).
+# glibc (libc/libm/ld-linux) deliberately stays on the host loader.
+#
+# rules_distroless `apt.install` resolves the closure from a committed lock; the
+# flattened rootfs is extracted to a directory by //third_party/docs_runtime and
+# merged into LD_LIBRARY_PATH alongside the graphviz_deb libs.
+###############################################################################
+bazel_dep(name = "rules_distroless", version = "0.6.2")
+
+# bsdtar (used by //third_party/docs_runtime to extract the flattened rootfs tar).
+bazel_dep(name = "tar.bzl", version = "0.6.0")
+
+apt = use_extension("@rules_distroless//apt:extensions.bzl", "apt")
+apt.install(
+    name = "docs_runtime",
+    lock = "//third_party/docs_runtime:docs_runtime.lock.json",
+    manifest = "//third_party/docs_runtime:docs_runtime.yaml",
+    mergedusr = True,
+)
+use_repo(apt, "docs_runtime")
+
 register_toolchains(
     "//bazel/rules/rules_score:sphinx_default_toolchain",
 )

bazel/rules/rules_score/BUILD

@@ -185,9 +185,6 @@ sphinx_module(
 py_binary(
     name = "raw_build",
     srcs = ["src/sphinx_wrapper.py"],
-    data = [
-        "//tools/sphinx:plantuml",
-    ],
     env = {
         "SOURCE_DIRECTORY": "",
         "DATA": "",
@@ -198,7 +195,6 @@ py_binary(
     deps = [
         ":sphinx_module_ext",
         "@lobster//sphinx_lobster:sphinx_lobster_builder",
-        "@rules_python//python/runfiles",
         "@score_tooling//plantuml/sphinx/clickable_plantuml",
         "@trlc//tools/sphinx/extensions/trlc",
         requirement("sphinx"),

bazel/rules/rules_score/docs/integration_guide.rst

@@ -175,3 +175,143 @@ Design Rationale
 6. **Build System Integration** — Bazel ensures reproducible, cacheable documentation builds
 
 Reference implementation: `examples/seooc <https://github.com/eclipse-score/score-tooling/tree/main/bazel/rules/rules_score/examples/seooc>`_ in the score-tooling repository.
+
+---
+
+.. _sphinx-hermetic-tool-setup:
+
+Hermetic Diagram Tools (Graphviz and PlantUML)
+----------------------------------------------
+
+The Sphinx HTML action shells out to two diagram tools at **runtime** (inside
+Bazel actions): ``dot`` from Graphviz and PlantUML.  Both are hermetic —
+i.e.\ no host installation required.  The two tools use different
+delivery mechanisms, described below.
+
+Graphviz / ``dot``
+~~~~~~~~~~~~~~~~~~
+
+**Source and packaging**
+
+Graphviz is pulled from the **cmake-release** ``.deb`` published on the
+Graphviz GitLab CI at
+``https://gitlab.com/graphviz/graphviz/-/packages``.  This ``dot`` binary is
+*relocatable*: ``RUNPATH=$ORIGIN/../lib:$ORIGIN/../lib/graphviz``
+and the plugin manifest (``config6``) references plugins by basename — so it
+works from any directory without a system install.  The standard Ubuntu
+``graphviz`` package would not work here.
+
+``@graphviz_deb`` is declared in ``MODULE.bazel`` via a ``download_deb`` rule.
+Three external system libraries that ``dot`` does **not** bundle (``libexpat``,
+``libltdl``, ``libz``) are provided by a small distroless sysroot declared in
+``//third_party/docs_runtime`` (see its ``README.md`` for details).
+
+**Where the files land (execroot-relative paths)**
+
+.. code-block:: text
+
+   external/+_repo_rules+graphviz_deb/usr/
+     bin/dot                            ← GRAPHVIZ_DOT env var
+     lib/
+       libgvc.so.6 / libcgraph.so.6 /… ← core libs (RUNPATH $ORIGIN/../lib)
+       graphviz/
+         config6                        ← plugin manifest (GVBINDIR)
+         libgvplugin_core.so.6          ← SVG renderer (LTDL_LIBRARY_PATH)
+         libgvplugin_dot_layout.so.6    ← dot layout engine
+
+   bazel-bin/third_party/docs_runtime/tree_root/usr/lib/x86_64-linux-gnu/
+     libexpat.so.1 / libltdl.so.7 / libz.so.1  ← LD_LIBRARY_PATH
+
+**Wiring into the Sphinx action**
+
+``dot_action_env()`` (from ``//third_party/docs_runtime:defs.bzl``) converts
+the file list into an environment dict with four execroot-relative paths:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Env var
+     - Content
+   * - ``GRAPHVIZ_DOT``
+     - Path to the ``dot`` binary
+   * - ``LD_LIBRARY_PATH``
+     - Graphviz core libs + sysroot libs (colon-separated)
+   * - ``GVBINDIR``
+     - Plugin directory (``config6`` + ``.so`` files)
+   * - ``LTDL_LIBRARY_PATH``
+     - Same as ``GVBINDIR``; searched by ``libltdl`` to ``dlopen`` plugins
+
+Both targets are added as **action inputs** and the env dict is set on the
+Sphinx HTML ``ctx.actions.run`` call.
+
+**Resolving paths in conf.py**
+
+All four env vars are set as *execroot-relative* paths (e.g.
+``external/+_repo_rules+graphviz_deb/usr/bin/dot``).  Because Sphinx changes
+the process working directory during the build, these paths would break if
+used as-is.  ``conf.template.py`` therefore:
+
+1. Captures ``_EXECROOT = Path.cwd()`` at **module import time** (cwd is still
+   the execroot at that point).
+2. Calls ``_resolve_execroot_path()`` on each value to prepend ``_EXECROOT``
+   and produce absolute paths.
+3. Mutates ``os.environ`` for ``LD_LIBRARY_PATH``, ``GVBINDIR`` and
+   ``LTDL_LIBRARY_PATH`` so that the ``dot`` *child process* (spawned by
+   ``sphinx.ext.graphviz`` and PlantUML) inherits them.
+
+PlantUML
+~~~~~~~~
+
+**Source and packaging**
+
+PlantUML is fetched from **Maven Central** via ``rules_jvm_external``
+(declared in ``MODULE.bazel``).  It is wrapped as a ``java_binary`` at
+``//tools/sphinx:plantuml`` in ``tools/sphinx/BUILD``.
+
+The PlantUML target is added to the sphinx-build binary (``raw_build``) as a
+``data`` dependency, making it a **runfile** of that binary — not an
+independent action input.
+
+**Where the file lands (runfiles-relative path)**
+
+.. code-block:: text
+
+   {sphinx_build_binary}.runfiles/
+     {repo_name}/tools/sphinx/plantuml   ← wrapper script (absolute path via Runfiles API)
+
+The ``{repo_name}`` prefix depends on the Bzlmod configuration:
+
+- ``_main`` — when score_tooling is the root module (e.g.\ building within
+  the score-tooling repo itself)
+- ``score_tooling`` / ``score_tooling+`` / ``score_tooling~`` — when
+  score_tooling is an external dependency of another project
+
+**Discovering the binary in conf.py**
+
+Because the repo name varies, ``conf.template.py`` uses two-stage discovery:
+
+1. **Manifest scan (primary):** Read ``RUNFILES_MANIFEST_FILE`` and search
+   for any entry whose runfiles path ends in ``/tools/sphinx/plantuml``.  This
+   requires no knowledge of the repo name prefix.
+2. **Runfiles API fallback:** If no manifest file is available (directory-based
+   runfiles trees on some platforms), fall back to
+   ``Runfiles.Create().Rlocation()`` with a list of known repo-name candidates
+   (``_main``, ``score_tooling``, ``score_tooling+``, …).
+
+The Runfiles API returns an **absolute path** directly, so no
+``_resolve_execroot_path()`` is required for PlantUML.
+
+**Connecting PlantUML to Graphviz**
+
+Once both paths are resolved, ``conf.template.py`` assembles the PlantUML
+command:
+
+.. code-block:: python
+
+   plantuml = f"{plantuml_path} -graphvizdot {graphviz_dot}"
+
+The ``-graphvizdot`` flag makes PlantUML use the hermetic ``dot`` binary for
+diagram layout instead of its bundled Java port (Smetana).  This ensures that
+the graphviz version is identical for both ``sphinx.ext.graphviz`` directives
+and PlantUML diagrams.

bazel/rules/rules_score/private/sphinx_module.bzl

@@ -18,6 +18,7 @@ load("@rules_python//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
 load("@rules_python//sphinxdocs/private:sphinx_docs_library_info.bzl", "SphinxDocsLibraryInfo")
 load("//bazel/rules/rules_score:providers.bzl", "FilteredExecpathInfo", "SphinxIndexFileInfo", "SphinxModuleInfo", "SphinxNeedsInfo")
 load("//bazel/rules/rules_score/private:verbosity.bzl", "VERBOSITY_ATTR", "get_log_level")
+load("//third_party/docs_runtime:defs.bzl", "DOCS_RUNTIME_TREE", "GRAPHVIZ_DEB", "dot_action_env")
 
 def _get_index_file(ctx):
     """Extract the index file from the index attribute.
@@ -69,6 +70,11 @@ sphinx_rule_attrs = dict(
         "deps": attr.label_list(
             doc = "List of other sphinx_module targets this module depends on for intersphinx.",
         ),
+        "_plantuml": attr.label(
+            default = Label("//third_party/plantuml:plantuml"),
+            executable = True,
+            cfg = "exec",
+        ),
     },
     **VERBOSITY_ATTR
 )
@@ -110,10 +116,12 @@ def _score_needs_impl(ctx):
         inputs = needs_inputs,
         outputs = [needs_output],
         arguments = needs_args,
+        env = {"PLANTUML_BIN": ctx.executable._plantuml.path},
         progress_message = "Generating needs.json for: %s" % ctx.label.name,
         executable = sphinx_toolchain.sphinx.files_to_run.executable,
         tools = [
             sphinx_toolchain.sphinx.files_to_run,
+            ctx.attr._plantuml.files_to_run,
         ],
     )
     transitive_needs = [dep[SphinxNeedsInfo].needs_json_files for dep in ctx.attr.deps if SphinxNeedsInfo in dep]
@@ -238,39 +246,26 @@ def _score_html_impl(ctx):
         get_log_level(ctx),
     ]
 
-    # Wire in the hermetic graphviz deb (dot_builtins + bundled shared libs) if provided.
-    # conf.template.py resolves all three env vars (GRAPHVIZ_DOT,
-    # LD_LIBRARY_PATH, LTDL_LIBRARY_PATH) from execroot-relative to absolute
-    # paths so dot_builtins can load its plugins without a system installation.
-    graphviz_env = {}
-    graphviz_files = ctx.files.graphviz
-    if graphviz_files:
-        _dot_suffix = "/usr/bin/dot_builtins"
-        dot_binary = None
-        for f in graphviz_files:
-            if f.path.endswith(_dot_suffix):
-                dot_binary = f
-                break
-        if not dot_binary:
-            fail("graphviz target {} must provide usr/bin/dot_builtins".format(ctx.attr.graphviz))
-
-        graphviz_prefix = dot_binary.path[:-len(_dot_suffix)]
-        graphviz_env = {
-            "GRAPHVIZ_DOT": dot_binary.path,
-            "LD_LIBRARY_PATH": graphviz_prefix + "/usr/lib",
-            "LTDL_LIBRARY_PATH": graphviz_prefix + "/usr/lib/graphviz",
-        }
-        html_inputs = html_inputs + graphviz_files
+    # Wire in the hermetic graphviz `dot` (relocatable cmake deb @graphviz_deb)
+    # plus the docs_runtime sysroot (libexpat/libltdl/libz). conf.template.py
+    # reads GRAPHVIZ_DOT for both sphinx.ext.graphviz and PlantUML, and resolves
+    # LD_LIBRARY_PATH / GVBINDIR / LTDL_LIBRARY_PATH to absolute paths so dot can
+    # load its plugins without a system graphviz installation.
+    action_env = {"PLANTUML_BIN": ctx.executable._plantuml.path}
+    if ctx.files._graphviz and ctx.file._docs_runtime:
+        action_env.update(dot_action_env(ctx.files._graphviz, ctx.file._docs_runtime))
+        html_inputs = html_inputs + ctx.files._graphviz + [ctx.file._docs_runtime]
 
     ctx.actions.run(
         inputs = html_inputs,
         outputs = [sphinx_html_output],
         arguments = html_args + [args],
-        env = graphviz_env,
+        env = action_env,
         progress_message = "Building HTML: %s" % ctx.label.name,
         executable = sphinx_toolchain.sphinx.files_to_run.executable,
         tools = [
             sphinx_toolchain.sphinx.files_to_run,
+            ctx.attr._plantuml.files_to_run,
         ],
     )
 
@@ -358,12 +353,13 @@ _score_html = rule(
                   "destination paths relative to the Sphinx source root. Exactly one " +
                   "file per label. Mirrors sphinx_docs.renamed_srcs from rules_python.",
         ),
-        graphviz = attr.label(
-            default = None,
+        _graphviz = attr.label(
+            default = GRAPHVIZ_DEB,
             allow_files = True,
-            doc = "Graphviz cmake-release deb files (dot_builtins binary + bundled libs). " +
-                  "Only available on Linux x86_64; provides a hermetic 'dot' binary without requiring a system graphviz installation. " +
-                  "Defaults to @graphviz_deb//:all on Linux x86_64.",
+        ),
+        _docs_runtime = attr.label(
+            default = DOCS_RUNTIME_TREE,
+            allow_single_file = True,
         ),
     ),
     toolchains = ["//bazel/rules/rules_score:toolchain_type"],
@@ -383,7 +379,6 @@ def sphinx_module(
         strip_prefix = "",
         extra_opts = [],
         extra_opts_targets = [],
-        graphviz = None,
         testonly = False,
         **kwargs):
     """Build a Sphinx module with transitive HTML dependencies.
@@ -408,10 +403,6 @@ def sphinx_module(
         extra_opts_targets: {type}`list[label]` Label targets that resolve to extra Sphinx
                     arguments at analysis time. Each target must provide FilteredExecpathInfo
                     (e.g. filter_execpath targets).
-        graphviz: Graphviz cmake-release deb files (dot_builtins + bundled libs). On Linux x86_64,
-                    defaults to @graphviz_deb//:all for hermetic graphviz support. On other platforms
-                    or if explicitly set to None, no graphviz support is provided (the sphinx.ext.graphviz
-                    extension will not be available).
         visibility: Bazel visibility
     """
     _score_needs(
@@ -432,7 +423,6 @@ def sphinx_module(
         needs = [d + "_needs" for d in deps],
         extra_opts = extra_opts,
         extra_opts_targets = extra_opts_targets,
-        graphviz = graphviz,
         testonly = testonly,
         **kwargs
     )