Skip to content

Fix PlantUML and Graphviz execution in Zuul CI documentation builds - #433

Closed
vishwajitdandage wants to merge 2 commits into
eclipse-score:mainfrom
vishwajitdandage:add-more-packages
Closed

Fix PlantUML and Graphviz execution in Zuul CI documentation builds#433
vishwajitdandage wants to merge 2 commits into
eclipse-score:mainfrom
vishwajitdandage:add-more-packages

Conversation

@vishwajitdandage

@vishwajitdandage vishwajitdandage commented Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Issue: #324

Why

PlantUML and Graphviz diagrams fail during documentation builds executed in Zuul Bazel sandbox environments, especially when runfiles are not materialized as symlinks.

The tools cannot reliably locate their Java runtime, classpath dependencies, or Graphviz executable when only the runfiles manifest is available. This results in errors such as missing runfiles directories, unresolved PlantUML classes, and unavailable Graphviz binaries. Consequently, documentation builds either fail or produce missing diagrams.

How

Updated the tooling to support sandboxed execution by:

  • Exporting JAVA_RUNFILES for PlantUML invocations.
  • Resolving the JDK and PlantUML dependencies from the Bazel runfiles manifest.
  • Materializing a synthetic runfiles tree when Bazel does not provide one.
  • Caching the generated runfiles tree to avoid repeated setup for multiple diagrams.
  • Resolving the Graphviz executable through the same sandbox-compatible runfiles mechanism.
  • Preserving compatibility with regular Bazel runfiles trees.

Graphviz error -

image

Plantuml error -

/output_base/sandbox/processwrapper-sandbox/770/execroot/_main/bazel-out/k8-fastbuild/bin/deployment/ecu_instances/ipb2/doc/ipb2_sphinx_doc/systems/routing_system.rst:41: WARNING: error while running plantuml


b'Picked up JAVA_TOOL_OPTIONS: -Djava.awt.headless=true -Dsun.java2d.fontpath=bazel-out/k8-opt-exec/bin/external/score_tooling+/third_party/plantuml/plantuml.runfiles/score_tooling+/third_party/plantuml/plantuml_sysroot_sysroot/usr/share/fonts/truetype/dejavu -Djava.awt.headless=true -Dsun.java2d.fontpath=/output_base/execroot/_main/bazel-out/k8-opt-exec/bin/external/score_tooling+/third_party/plantuml/plantuml_sysroot_sysroot/usr/share/fonts/truetype/dejavu -Dsun.awt.fontconfig=/tmp/plantuml-fontconfigW96eAs\nError: Could not find or load main class net.sourceforge.plantuml.Run\nCaused by: java.lang.ClassNotFoundException: net.sourceforge.plantuml.Run\n' [plantuml]
/output_base/sandbox/processwrapper-sandbox/783/execroot/_main/bazel-out/k8-fastbuild/bin/deployment/ecu_instances/ipb2/doc/ipb2_sphinx_doc/systems/can_system.rst:61: WARNING: error while running plantuml```

@vishwajitdandage
fix(plantuml): export JAVA_RUNFILES for sandbox execution
196cdf1 
When the PlantUML wrapper invokes plantuml_java, explicitly set the
JAVA_RUNFILES environment variable so that the Java launcher can locate
its runfiles directory. This is critical in Bazel sandbox contexts where
the Java process cannot rely on default runfiles discovery mechanisms.

Tries two locations:
1. First, plantuml_java.runfiles adjacent to the Java binary
2. Fallback to the sh_binary's RUNFILES_DIR if available

Fixes 'Cannot locate runfiles directory' errors when PlantUML is invoked
from Sphinx actions in Bazel sandboxes.

fix(plantuml): resolve JDK via runfiles manifest when no runfiles tree exists

The empty-placeholder JAVA_RUNFILES fallback satisfied the launcher's
directory-exists check but the generated Java launcher itself resolves
its own JDK as $JAVA_RUNFILES/<jdk repo>/bin/java, so an empty directory
still failed with 'No such file or directory'. Resolve the real JDK
location from the runfiles manifest and symlink it into a synthetic
runfiles directory instead.

fix(plantuml): materialize full runfiles tree when no directory exists

The JDK-only symlink fixed 'Cannot locate runfiles directory' but the Java
launcher also resolves PlantUML's own classpath jars purely as paths under
$JAVA_RUNFILES, causing ClassNotFoundException. Build a full synthetic
runfiles tree from the manifest instead (one symlink per entry), cached by
manifest checksum so repeated diagram renders within the same action reuse
it instead of rebuilding it each time.
@vishwajitdandage
feat(dependable_element): add Graphviz support for lobster RST report…
552bd39 
… generation
@vishwajitdandage vishwajitdandage changed the title Fix PlantUML and Graphviz execution in sandboxed documentation builds Fix PlantUML and Graphviz execution in zuul CI documentation builds Aug 20, 2026
@vishwajitdandage vishwajitdandage changed the title Fix PlantUML and Graphviz execution in zuul CI documentation builds Fix PlantUML and Graphviz execution in Zuul CI documentation builds Aug 20, 2026
@simon-d-bmw

simon-d-bmw commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Thanks for tracking down the sandbox/runfiles-materialization root cause — we hit the
same class of failure downstream and can confirm GRAPHVIZ_DOT reaching the LOBSTER
RST report action fixes a real gap (that action previously had no graphviz binary at
all).

One simplification idea for plantuml.sh: the hand-rolled rlocation() plus its
several repo-name-spelling fallbacks (score_tooling/..., score_tooling+/...,
_main/..., external/score_tooling+/...) and the subsequent find-based search
loops largely reimplement what Bazel's own runfiles library already provides. Sourcing
@bazel_tools//tools/bash/runfiles:runfiles.bash and using its rlocation would likely
let most of that manual path-search logic be dropped, since that library already
handles both manifest- and directory-based runfiles and bzlmod repo mapping correctly
across the different execution modes (including --nobuild_runfile_links). The
synthetic JAVA_RUNFILES tree materialization for the Java stub launcher's own
manifest-blindness would still be needed on top, but could build directly on the
resolved manifest path from that library instead of re-deriving it independently.

Happy to help prototype this simplification if useful.

@vishwajitdandage
vishwajitdandage force-pushed the add-more-packages branch 2 times, most recently from f9e1066 to 552bd39 Compare August 27, 2026 10:41
@vishwajitdandage
vishwajitdandage marked this pull request as draft August 27, 2026 11:34
@vishwajitdandage

vishwajitdandage commented Aug 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

PlantUML fix is delivered by #431. A separate PR for GraphViz is created.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@castler castler Awaiting requested review from castler castler is a code owner
@hoe-jo hoe-jo Awaiting requested review from hoe-jo hoe-jo is a code owner
@LittleHuba LittleHuba Awaiting requested review from LittleHuba LittleHuba is a code owner
@limdor limdor Awaiting requested review from limdor limdor is a code owner
@ramceb ramceb Awaiting requested review from ramceb ramceb is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@vishwajitdandage @simon-d-bmw