bazel-stardoc for Debian
======================

This document explains key architectural decisions in the Debian packaging
of bazel-stardoc.

1. Prebuilt Renderer vs. Source Compilation
-------------------------------------------
Upstream Stardoc compiles the Java renderer ("//stardoc:renderer") from
Java source files ("RendererMain.java") every time a project invokes the
"stardoc" rule. Compiling the renderer from source requires several
build-time dependencies:

 - "protobuf" (for compiling ".proto" definitions and runtime protobuf classes)
 - "rules_jvm_external" and Maven artifacts (Guava, JCommander, Truth, JUnit)

In Debian, we patch "stardoc/BUILD"
("debian/patches/use-installed-renderer.patch") so that
"//stardoc:renderer" does NOT compile from source when used by end users.
Instead, we compile "renderer_prebuilt.jar" once during "dpkg-buildpackage"
(in "debian/rules") using offline build-time scaffolding ("debian/mock_repos/"
and "debian/mock_modules/"). We install this prebuilt jar to
"/usr/share/bazel/tools/stardoc/stardoc/renderer_prebuilt.jar".

When Debian developers or autopkgtests invoke "stardoc", "//stardoc:renderer"
simply executes this prebuilt jar using the system JVM. Therefore, at runtime,
Stardoc never needs "protobuf", "rules_jvm_external", or Maven.

2. Why Upstream MODULE.bazel Cannot Be Installed
------------------------------------------------
If we installed upstream's "MODULE.bazel" to
"/usr/share/bazel/tools/stardoc/MODULE.bazel", runtime Bzlmod in user
projects would read declarations for "protobuf" and "rules_jvm_external".
While Debian's "bazel-bootstrap" provides system-wide Bzlmod overrides in
"/etc/bazel/bazelrc" for rules like "rules_java", "bazel_skylib", and
"rules_cc", it does not provide system overrides for "rules_jvm_external" or
"protobuf".
Consequently, Bzlmod would attempt to connect to the Bazel Central Registry
(BCR) at "https://bcr.bazel.build/" over the internet to fetch them. In
offline developer environments, sbuild chroots, or autopkgtests, this would
immediately crash with "Unknown host: bcr.bazel.build".

3. Why a Quilt Patch on MODULE.bazel is Not Feasible
----------------------------------------------------
We cannot use a quilt patch to remove "protobuf" and "rules_jvm_external"
from "MODULE.bazel" directly in the source package.
Those module dependencies are strictly required at build time during
"dpkg-buildpackage" when "debian/rules" compiles "renderer_deploy.jar"
from source. If they were stripped via a quilt patch before the build started,
Bazel would fail to resolve "@com_google_protobuf" and "@stardoc_maven",
breaking the Debian package build.

4. The Static debian/MODULE.bazel Solution
------------------------------------------
To reconcile build-time requirements with runtime offline simplicity, we
maintain a clean, static runtime configuration in "debian/MODULE.bazel"
that only declares dependencies on system-installed modules:

 - "bazel_skylib"
 - "rules_java"
 - "rules_license"

We install this static file over the upstream version using
"debian/bazel-stardoc.install":

    debian/MODULE.bazel ${env:INSTALL_PATH}/stardoc/

This approach separates build-time compilation from runtime execution,
ensuring "bazel-stardoc" works completely offline out-of-the-box for Debian
developers without requiring internet access or manual command-line overrides.
