### Alat

#### Membandingkan file APK (*Diffing the APK*)

Disarankan menggunakan [`diffoscope`](https://diffoscope.org/) untuk
menemukan perbedaan antara APK referensi dari pengembang dan APK yang
dihasilkan oleh `fdroidserver`.

Anda dapat menemukan APK yang dihasilkan oleh `fdroidserver` di folder
seperti:
`fdroiddata/build/com.example.app/app/build/outputs/apk/prod/release/example-1.0.0-prod-release-unsigned.apk`
(saat dijalankan secara lokal),
atau di artefak *pipeline* (jika menggunakan GitLab CI).
Sesuaikan jalur sesuai kebutuhan, misalnya untuk *flavour* selain `prod`.

#### Prioritas dan Perbaikan Perbedaan (*Prioritising & fixing differences*)

Panduan [HOWTO: diff & fix APKs for Reproducible
Builds](https://gitlab.com/fdroid/wiki/-/wikis/HOWTO:-diff-&-fix-APKs-for-Reproducible-Builds)
di wiki F-Droid menjelaskan secara mendalam jenis perbedaan yang umum
terjadi, perbedaan mana yang harus lebih diprioritaskan saat debugging,
serta cara mengatasi permasalahan umum tersebut.

Panduan tersebut juga menjelaskan penggunaan berbagai alat khusus yang dapat
memberikan hasil lebih baik ketika `diffoscope` tidak cukup memadai.

#### Alat Reproducible APK (*Reproducible APK tools*)

Skrip dari proyek
[reproducible-apk-tools](https://github.com/obfusk/reproducible-apk-tools)
(tersedia di *fdroiddata* sebagai `srclib`) dapat membantu membuat build
menjadi lebih konsisten — misalnya dengan memperbaiki format akhir baris
(*newline*: CRLF vs LF) atau membuat urutan dalam file ZIP menjadi
deterministik.
Jika penyebab perbedaannya tidak realistis untuk dihilangkan, skrip ini bisa
dijalankan oleh pengembang hulu sebelum menandatangani APK, oleh resep
*fdroiddata*, atau keduanya.

Alat [disorderfs](https://salsa.debian.org/reproducible-builds/disorderfs),
yang awalnya dibuat untuk menambahkan ketidakpastian ke proses build, juga
dapat digunakan sebaliknya — untuk membuat pembacaan sistem file menjadi
deterministik.
Dalam beberapa kasus, ini dapat membantu membuat file seperti
`resources.arsc` menjadi lebih konsisten.
Berikut contoh penggunaannya:

```console
```bash
$ mv my.app my.app_underlying
$ disorderfs --sort-dirents=yes --reverse-dirents=no my.app_underlying my.app

### Sumber Potensial dari Build yang Tidak Dapat Direproduksi (*Potential sources of unreproducible builds*)

Terdapat berbagai faktor yang dapat menyebabkan build tidak dapat
direproduksi.
Beberapa di antaranya mudah dihindari, tetapi sebagian lainnya cukup sulit
diperbaiki.
Berikut adalah beberapa penyebab umum yang ditemui:

Lihat juga [masalah GitLab
ini](https://gitlab.com/fdroid/fdroiddata/-/issues/2816).


#### Bug: Android Studio menghasilkan urutan ZIP yang tidak deterministik

[Lihat laporan bug: Non-deterministic order of ZIP entries in APK makes
builds not reproducible](https://issuetracker.google.com/issues/265653160)
(memerlukan akun Google untuk diakses).

Catatan: masalah ini telah diperbaiki pada *Android Gradle Plugin*
(`com.android.tools.build:gradle` / `com.android.application`) versi `7.1.X`
dan yang lebih baru.

Saat membangun APK menggunakan Android Studio, urutan *entry* dalam struktur
ZIP dapat berbeda dibandingkan dengan APK yang dibangun langsung menggunakan
`gradle`. Hal ini memengaruhi reproducibility karena urutan file bisa
benar-benar acak, bahkan antar build dari sumber kode yang sama.

Solusi untuk versi lama adalah menjalankan `gradle` langsung (seperti pada
build F-Droid atau CI), sehingga melewati Android Studio sepenuhnya:

```console
```bash
$ ./gradlew assembleRelease

Catatan: tergantung pada konfigurasi penandatanganan Anda, mungkin perlu
menandatangani APK menggunakan `apksigner` setelah proses build selesai,
karena Android Studio tidak melakukan penandatanganan otomatis dalam metode
ini.


#### Bug: `apksigner` dari build-tools ≥ 35.0.0-rc1 menghasilkan APK yang tidak dapat diverifikasi

Menggunakan `apksigner` dari *build-tools* versi 34 menghasilkan APK yang
dapat diverifikasi oleh `apksigcopier`, tetapi versi yang lebih baru akan
gagal.
Masalah ini sedang dilacak di
[#3299](https://gitlab.com/fdroid/fdroiddata/-/issues/3299), dengan detail
tambahan di [apksigcopier issue
#105](https://github.com/obfusk/apksigcopier/issues/105).
Karena *Ubuntu images* GitHub Actions sejak Juli 2024 sudah menggunakan
versi 35, solusinya adalah memilih versi `apksigner` dari *build-tools* 34
secara manual daripada menggunakan versi terbaru bawaan.


#### Bug: `baseline.prof` tidak deterministik

Kadang berkas `baseline.prof` tidak dapat direproduksi dengan hasil yang
sama. Beberapa solusi yang dapat dicoba:

1. Jalankan build ulang beberapa kali hingga file `baseline.prof` cocok.
1. Gunakan jumlah inti CPU (*cores*) yang sama dengan yang digunakan
   pengembang hulu.
1. Nonaktifkan profil dasar (*baseline profile*).  
Tambahkan potongan berikut ke dalam `build.gradle`:

  ```groovy
  tasks.whenTaskAdded { task ->
      if (task.name.contains("ArtProfile")) {
          task.enabled = false
      }
  }

Catatan: solusi ini memengaruhi seluruh sistem, jadi sebaiknya digunakan
pada mesin virtual atau kontainer sementara untuk menghindari gangguan
permanen.

Untuk kode Rust, Anda dapat mengatur [`codegen-units =
1`](https://doc.rust-lang.org/rustc/codegen-options/index.html#codegen-units).

Lihat juga [masalah GitLab
ini](https://gitlab.com/fdroid/rfp/-/issues/1519#note_1226216164).


#### Jalur build yang tertanam (*Embedded build paths*)

[Jalur build](https://reproducible-builds.org/docs/build-path/) yang
tertanam sering menjadi penyebab masalah reproducibility, terutama pada
aplikasi yang dibangun menggunakan Flutter, *python-for-android*, atau
bahasa native seperti Rust dan C/C++ (contohnya berkas `libfoo.so`).
Aplikasi yang ditulis sepenuhnya dengan Java atau Kotlin biasanya tidak
terpengaruh.

Cara termudah untuk menghindarinya adalah dengan selalu menggunakan
direktori kerja yang sama saat melakukan build — misalnya:
`/builds/fdroid/fdroiddata/build/your.app.id` (F-Droid CI),
`/home/vagrant/build/your.app.id` (server build F-Droid), atau `/tmp/build`,
atau buat direktori yang menyerupai jalur build di sistem pengembang hulu,
misalnya di macOS: `/Users/runner`.

Catatan: menggunakan subdirektori di dalam `/tmp` yang dapat ditulis oleh
semua pengguna memiliki potensi risiko keamanan pada sistem multi-pengguna.

Jika jalur SDK tertanam ke dalam build Flutter, Anda dapat memindahkan SDK ke jalur tersebut di resep build, lalu konfigurasikan dengan: 
`flutter config --android-sdk <path>` 
karena pengaturan `ANDROID_SDK_ROOT` saja terkadang tidak cukup.

Jika pustaka (`lib`) tidak di-*strip* dengan benar, informasi debug dapat
tetap tersimpan, yang biasanya berisi banyak jalur direktori. Mengaktifkan
*strip* dapat menghapus data tersebut. Hal ini dapat dilakukan dengan
menentukan versi NDK yang tepat atau menambahkan opsi `-s` ke perintah
*linker*. Proses ini juga bisa dilakukan secara manual menggunakan alat
seperti `llvm-strip`.

#### Cap waktu tertanam (*Embedded timestamps*)

[*Timestamps*](https://reproducible-builds.org/docs/timestamps/) yang
tertanam merupakan salah satu penyebab paling umum dari masalah
reproducibility dan sebaiknya dihindari sebisa mungkin.


#### *Stripping* pustaka native (*Native library stripping*)

Proses *stripping* pada pustaka native (misalnya `libfoo.so`) kadang dapat
menyebabkan hasil build tidak sepenuhnya identik.
Karena itu, penting untuk menggunakan versi NDK yang sama saat melakukan
*rebuild*, misalnya `r21e`.
Menonaktifkan *stripping* kadang dapat membantu.
Secara default, Gradle akan melakukan *strip* pustaka secara otomatis,
bahkan jika pustaka tersebut berasal dari dependensi AAR.
Berikut cara menonaktifkannya di Gradle:

```gradle
android {
    packagingOptions {
        doNotStrip '**/*.so'
    }
}

```bash
objcopy --remove-section .comment <file>

#### Revisi *Platform*

Pada tahun 2014, *Android SDK tools*
[diubah](https://issuetracker.google.com/issues/37132313) untuk menambahkan
dua elemen data, yaitu
[`platformBuildVersionName`](https://android.googlesource.com/platform/frameworks/base/+/ad2d07d%5E!/)
dan
[`platformBuildVersionCode`](https://android.googlesource.com/platform/frameworks/base/+/5283fab%5E!/),
ke dalam `AndroidManifest.xml` sebagai bagian dari proses build.
`platformBuildVersionName` berisi *revision* dari paket *platform* yang
digunakan (mis. `android-23`).
Namun, versi revisi yang berbeda dari paket *platform* yang sama tidak dapat
diinstal secara bersamaan, dan SDK tools juga tidak menyediakan cara untuk
menentukan revisi yang diperlukan saat build.
Akibatnya, dua build yang seharusnya identik dapat berbeda hanya karena
atribut `platformBuildVersionName`.

Komponen _platform_ adalah bagian dari *Android SDK* yang mewakili pustaka
standar yang terpasang pada perangkat.
Mereka memiliki dua jenis versi:
1. *Version code* — bilangan bulat yang mewakili rilis SDK.
2. *Revision* — versi perbaikan bug untuk tiap *platform*.

Versi-versi ini dapat ditemukan dalam berkas `build.prop`, di mana setiap
revisi memiliki nilai berbeda untuk `ro.build.version.incremental`.
Gradle tidak menyediakan cara untuk menentukan revisi melalui properti
`compileSdkVersion` atau `targetSdkVersion`.
Hanya satu *platform-23* yang dapat dipasang dalam satu waktu, berbeda
dengan *build-tools* yang bisa diinstal beberapa versi sekaligus.

Berikut dua contoh di mana perbedaan hasil diduga berasal dari revisi
*platform* yang berbeda:

* <https://verification.f-droid.org/de.nico.ha_manager_25.apk.diffoscope.html>
* <https://verification.f-droid.org/de.nico.asura_12.apk.diffoscope.html>


#### PNG Crush/Crunch

Tahap standar dalam proses build Android mencakup optimisasi gambar PNG
menggunakan alat seperti `aapt singleCrunch`, `pngcrush`, `zopflipng`, atau
`optipng`.
Sayangnya, hasilnya tidak deterministik dan penyebab pastinya masih belum
diketahui.

Karena berkas PNG biasanya sudah dikomit di repositori sumber (misalnya
lewat *git*), solusi praktis adalah menjalankan alat optimisasi pilihan Anda
terhadap berkas-berkas PNG lalu mengomitas perubahan tersebut ke
repositori.
Setelah itu, nonaktifkan proses optimisasi PNG bawaan dengan menambahkan
kode berikut ke `build.gradle`:

```gradle
android {
    aaptOptions {
        cruncherEnabled = false
    }
}

-keep class kotlinx.coroutines.CoroutineExceptionHandler
-keep class kotlinx.coroutines.internal.MainDispatcherFactory

```proto
repositories {
  system: GIT
  local_root_path: "$PROJECT_DIR"
  revision: "3a443877cd53e37d85cbc52adc8cfd558919d373"
}

Kami memahami bahwa pengembang perlu membangun dan menguji aplikasi selama
proses kerja. Namun, pastikan untuk mengunggah APK *release* yang dibangun
setelah *tagging*, menggunakan *tree* bersih pada *commit* bertanda tersebut
(tanpa perubahan lokal atau artefak build sebelumnya). Hanya dalam kasus
luar biasa, ketika tidak memungkinkan, `vcsInfo` boleh dinonaktifkan (karena
dapat menimbulkan masalah jika salah konfigurasi). Hal ini dapat dilakukan
sebagai berikut:

```gradle
    buildTypes {
        release {
           vcsInfo.include false
        }
    }

#### Perbedaan *Toolchain* (*Mismatched Toolchains*)

Berbagai *toolchain* dapat menghasilkan biner yang berbeda. Kasus umum
terjadi ketika lebih dari satu versi atau distribusi JDK digunakan untuk
membangun APK. Bahkan Gradle terkadang mencampur beberapa versi JDK dalam
satu proses build. Untuk menghindari masalah ini, pastikan hanya satu versi
JDK yang digunakan dan hapus JDK yang tidak relevan.

Perbedaan file `classes.dex` akibat versi Java yang berbeda dapat terlihat
seperti:

```diff
-    .annotation system Ldalvik/annotation/Signature;
-        ```
         value = {
         ```
-            ```
             "()V"
             ```
-        ```
         }
         ```
-    ```
     .end annotation
     ```

```cmake
add_link_options("LINKER:--build-id=none")

Perintah ini hanya berlaku untuk pustaka yang ditambahkan setelah perintah ini dipanggil, jadi sebaiknya diletakkan di awal berkas CMake.
Untuk versi CMake sebelum 3.13, gunakan `target_compile_options(<target> PRIVATE mpiler args>)` dan `target_link_libraries(<target> LINKER:<linker args>)` untuk setiap target.
Alternatifnya, konfigurasi ini juga dapat ditetapkan langsung di berkas Gradle:

```gradle
android {
    defaultConfig {
        externalNativeBuild.cmake {
          cFlags "<compiler args> -Wl,<linker args>" // or
          arguments "-DCMAKE_C_FLAGS=<compiler args> -DCMAKE_SHARED_LINKER_FLAGS=-Wl,<linker args>"
        }
    }
}

Atau di dalam `build.gradle`:

```gradle
```groovy
externalNativeBuild {
    cmake {
        cFlags "-ffile-prefix-map=${rootDir}=."
        cppFlags "-ffile-prefix-map=${rootDir}=."
    }
}

##### Golang

Argumen *linker* dapat ditambahkan ke `CGO_LDFLAGS`. Beberapa argumen
berguna yang dapat diteruskan saat menjalankan `go build` adalah
`-ldflags="-buildid="`, `-trimpath` (untuk menghindari jalur build tertanam)
dan`-buildvcs=false`.

##### Rust

Argumen *compiler* dan *linker* dapat ditetapkan melalui [Cargo `build.rustflags`](https://doc.rust-lang.org/cargo/reference/config.html#buildrustflags) dan [Opsi Kodegen `rustc`](https://doc.rust-lang.org/rustc/codegen-options/index.html).
Argumen *linker* dapat ditambahkan dengan `-C link-args=-Wl,<linker args>`, sementara `--remap-path-prefix=<old>=<new>` digunakan untuk menghapus jalur build dari hasil akhir.

Versi *toolchain Rust* harus disamakan dengan versi yang digunakan oleh pengembang hulu. Hal ini dapat dilakukan saat instalasi menggunakan perintah: `rustup-init.sh -y --default-toolchain <version>`.

Ketika *crate openssl* menggunakan metode *vendored build*, pustaka OpenSSL
perlu dikonfigurasi secara khusus agar hasilnya dapat direproduksi. Variabel
`SOURCE_DATE_EPOCH` dapat diatur untuk menghapus cap waktu (*timestamp*),
dan `CARGO_TARGET_DIR` sebaiknya diarahkan ke jalur absolut seperti
`/tmp/build`, agar jalur tertanam tetap konsisten di berbagai mesin. Jalur
instalasi NDK juga mencerminkan hal yang sama agar konsisten antara satu
sistem dengan yang lain.

Jalur `CARGO_HOME` juga berpengaruh besar karena direkam di pustaka hasil
build. Sebaiknya disamakan antar build dengan cara mengekspornya sebelum
menjalankan `rustup` atau perintah build lainnya. Setelah itu, pastikan Anda
memuat (*source*) berkas `env` dari direktori tersebut.

#### Instruksi Khusus Pustaka (*Library-specific instructions*)

Beberapa pustaka menghasilkan kode yang tidak deterministik karena
keberadaan cap waktu, iterasi yang tidak terurut, dan faktor
lainnya. Beberapa solusi umum dijelaskan di bawah:

##### Plugin Gradle AboutLibraries (*AboutLibraries Gradle plugin*)

Untuk mencegah plugin `com.mikepenz.aboutlibraries.plugin` menambahkan cap
waktu (*timestamp*) ke dalam berkas JSON yang dihasilkannya, tambahkan
konfigurasi berikut ke dalam `build.gradle`:

```gradle
```groovy
aboutLibraries {
    // Hapus cap waktu "generated" agar build dapat direproduksi
    excludeFields = ["generated"]
}

Untuk `build.gradle.kts`, gunakan konfigurasi berikut:

```gradle
```kotlin
aboutLibraries {
    // Hapus cap waktu "generated" agar build dapat direproduksi
    excludeFields = arrayOf("generated")
}