amethyst/tools/zxing-cpp-build/README.md

zxing-cpp Android Build Tools

Custom-built zxing-cpp native library for Amethyst's QR scanner. This replaces the prebuilt io.github.zxing-cpp:android AAR with the same library built from source, the way tools/arti-build replaces the Guardian Project AAR.

Why custom build?

Not for size — the published AAR's libraries are already stripped, and ours come out only slightly smaller. For verifiability.

The AAR ships four .so files built by a third party on toolchains we cannot see, and nothing in this repository could check them. A QR scanner is a thing you point at a stranger's phone, and the binary that parses whatever comes back was one we took on trust. Amethyst already holds libarti_android.so to a reproducible standard; there was no principled reason for the barcode decoder to be exempt.

Building it ourselves also means F-Droid, Zapstore or any auditor can rebuild from this tag and confirm the committed bytes, instead of being asked to trust a Maven artifact.

Quick start

Pre-built .so files are committed to amethyst/src/main/jniLibs/. You only need to rebuild to verify the binaries, bump the zxing-cpp version, or change the build flags.

./build-zxingcpp.sh                  # every ABI
./build-zxingcpp.sh --abi arm64-v8a  # one ABI, much faster
./verify-reproducible.sh             # build twice, compare bytes, compare against the commit

Prerequisites: git, cmake, ninja, and the exact NDK revision in tools/arti-build/ANDROID_NDK_VERSION. That is the repo's single NDK pin, not a copy: build-zxingcpp.sh, build-arti.sh and :amethyst's ndkVersion all read that one file, so one NDK install serves every native build and the three can never drift apart.

Reproducible builds

Five things have to be fixed, and each is:

Source of non-determinism	Pinned by
compiler + linker version	tools/arti-build/ANDROID_NDK_VERSION; build-zxingcpp.sh refuses any other revision
upstream source	ZXING_CPP_VERSION, cloned at that tag and nothing else
absolute paths baked into __FILE__, assertions, debug records	-ffile-prefix-map / -fdebug-prefix-map in repro-env.sh
timestamps	SOURCE_DATE_EPOCH, derived from the pinned tag's commit rather than from build time; __DATE__/__TIME__ redacted
codegen/link ordering keyed on the real build path	canonical build path (/tmp/amethyst-zxingcpp-build)

Why the NDK is pinned. clang compiles the C++ and lld links the .so, and both stamp their versions into the binary's .comment section. Swapping the NDK changes the bytes exactly as swapping compilers would. build-zxingcpp.sh reads each candidate directory's source.properties and keeps looking until it finds the pinned revision — no wildcards. Picking "some NDK" is precisely how arti's committed binaries ended up built by r25b while its README told everyone to install r27; that lesson is borrowed here rather than re-learned.

Why the output is re-checked. After each build the script decodes the library's own .note.android.ident, which records the min SDK and the NDK release and build number, and fails if they are not what was asked for. The revision gate checks the input; this checks the output, which is what catches a stale CMake cache or an overriding environment variable that slipped a different toolchain past the gate.

Verified on this machine: two clean builds of arm64-v8a produced identical bytes (dec4397c…39dbf), and verify-reproducible.sh confirmed they match the committed library.

What is built

wrappers/android/zxingcpp/src/main/cpp/CMakeLists.txt from the pinned tag, which pulls in zxing-cpp's core/ and compiles one JNI file. Readers only (ZXING_WRITERS=OFF) — Amethyst encodes its QR codes with ZXing core on the JVM, and never writes one natively.

All four ABIs, unlike arti's two. Tor is an optional feature that can be absent; a QR scanner that fails to load is a broken core feature, and the decoder this replaced was pure Java and worked everywhere. Dropping an ABI would mean a silent regression on those devices unless the ZXing-Java fallback behind BarcodeDecoder were wired up too.

The Kotlin half

The AAR shipped the zxingcpp.BarcodeReader class alongside the .so, so dropping the AAR means carrying that too: it is vendored verbatim at amethyst/src/main/java/zxingcpp/BarcodeReader.kt.

Two things there are load-bearing and easy to break:

• The package and class name. The native library exports Java_zxingcpp_BarcodeReader_readYBuffer, so moving or renaming the class breaks the JNI lookup at runtime with no build error.
• -keep class zxingcpp.** { *; } in amethyst/proguard-rules.pro. This used to arrive as the AAR's consumer rule. Without it R8 renames the class in release builds and the scanner fails to start — in release only, which is the worst place to find out.

The vendored file keeps its upstream Apache-2.0 header and is excluded from spotless in the root build.gradle.kts, so our MIT header is never stamped onto it.

Updating zxing-cpp

1. Change ZXING_CPP_VERSION to the new tag.
2. Run ./build-zxingcpp.sh.
3. Re-copy BarcodeReader.kt from the pinned clone (/tmp/amethyst-zxingcpp-build/.zxing-cpp-source/wrappers/android/zxingcpp/src/main/java/zxingcpp/) so the two halves cannot drift — a Kotlin wrapper from one version against a .so from another fails at the JNI boundary, not at compile time.
4. Run ./verify-reproducible.sh and commit the .so files with the hash it reports.

Licensing

zxing-cpp is Apache-2.0 — permissive, so linking it into Amethyst's MIT-licensed artifacts is fine, and no linking-exception question arises. The vendored Kotlin file carries its upstream SPDX-License-Identifier: Apache-2.0 and copyright line unchanged.