Update reproducibility documentation to explain differences in APK hashes between host builds and Docker environments. This addition clarifies that while both can be reproducible within their own contexts, discrepancies may arise due to variations in OS, Java runtime, and toolchain, emphasizing the importance of aligning environments for matching hashes.

2026-10-05 20:48:24 +00:00 · 2026-01-20 01:12:37 -03:00
parent 840aebb782
commit 03fd955d9e
1 changed files with 10 additions and 0 deletions
@@ -162,3 +162,13 @@ Notes:

 - F-Droid will build from source and **re-sign** the APK.
 - For reproducibility checks, compare the **unsigned** APK generated by the build step above (same source revision + same pinned toolchain).
+
+## Why host hashes can differ from Docker
+
+It is normal for a **host build** (e.g. macOS) to produce a different APK hash than the **Docker proof** (Linux), even when both are reproducible **within their own environments**. Reproducibility here means:
+
+- **Same inputs + same toolchain + same environment** → identical output.
+
+The host and Docker proofs use **different environments** (OS, Java runtime, Android toolchain, filesystem behavior), so their outputs can legitimately differ while still being deterministic.
+
+If you need host and Docker hashes to match, you must align the environment as closely as possible (e.g. use **JDK 17** locally and build on the same OS/toolchain). Even then, cross‑OS builds can still differ, which is why the Docker proof is the preferred reference.