From 03fd955d9e55f5f7ce7cc883e8eb35261c7f6a95 Mon Sep 17 00:00:00 2001 From: Henrique Velloso Date: Thu, 15 Jan 2026 15:53:00 -0300 Subject: [PATCH] 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. --- REPRODUCIBLE_BUILD.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/REPRODUCIBLE_BUILD.md b/REPRODUCIBLE_BUILD.md index 7832595..bc82a32 100644 --- a/REPRODUCIBLE_BUILD.md +++ b/REPRODUCIBLE_BUILD.md @@ -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.