Panduan CLI hiddenjar

hiddenjar adalah CLI yang membangun android.jar kustom berisi hidden API dari emulator atau device yang sedang berjalan. Repository menyediakan dua implementasi dengan permukaan perintah yang sama: skrip bash cli/hiddenjar untuk macOS/Linux, dan port PowerShell cli/hiddenjar.ps1 yang berjalan native di Windows tanpa Git Bash atau WSL. README.md:26-31¹ cli/hiddenjar.ps1:1-13²

Keduanya menerima empat subcommand, yaitu build, restore, doctor, dan help, yang didokumentasikan langsung di blok usage cli/hiddenjar:70-107. Pada skrip bash, fungsi main mengambil argumen pertama sebagai nama subcommand dan meneruskan sisanya ke parse_args cli/hiddenjar:518-527.

Empat subcommand

Subcommand yang tidak dikenal mencetak usage lalu keluar dengan pesan unknown command: $sub cli/hiddenjar:518-527.

Siklus satu hiddenjar build

sequenceDiagram
  autonumber
  actor U as Developer
  participant C as hiddenjar main
  participant A as adb
  participant D as d2j-dex2jar
  participant J as BuildJar
  participant V as ClosureVerify
  participant S as SDK platform dir
  U->>C: build --api 37 --install
  C->>C: parse_args lalu resolve_adb dan ensure_dex_tools
  C->>A: getprop ro.build.version.sdk
  A-->>C: level API device
  C->>S: resolve_platform_dir untuk android.jar dasar
  S-->>C: path platform
  C->>A: shell echo $BOOTCLASSPATH
  A-->>C: daftar jar boot classpath
  loop setiap jar
    C->>A: pull dev_path
    C->>D: --force -o classes/local_name-classes.jar
    D-->>C: kelas hasil konversi DEX
  end
  C->>J: BuildJar --base android.jar --out output
  J-->>C: custom android.jar
  C->>V: ClosureVerify jar
  V-->>C: status supertype closure
  alt --install diberikan
    C->>S: install_jar dan backup android.jar.orig
  end
  C-->>U: Done

%% fig: Siklus satu invokasi hiddenjar build %% desc: Perintah build menyentuh adb untuk daftar jar dan level API, menyerahkan konversi ke dex2jar, perakitan ke BuildJar, lalu verifikasi sebelum pemasangan opsional ke SDK.

cmd_build lebih dahulu memanggil resolve_adb dan ensure_dex_tools, lalu memastikan javac, jar, serta unzip tersedia; kegagalan berhenti lewat die dengan pesan seperti unzip is required cli/hiddenjar:241-254. Level API diambil dari getprop ro.build.version.sdk bila --api tidak diberikan, dan resolve_platform_dir mencari android.jar dasar di SDK cli/hiddenjar:241-254.

Opsi --avd memicu boot_avd_if_needed, yang menjalankan emulator dengan -no-window lalu menunggu sys.boot_completed bernilai 1 sampai 90 percobaan berjarak 2 detik cli/hiddenjar:169-191. Tanpa --serial, pick_serial memilih device emulator-* pertama, lalu device apa pun, dan berhenti dengan pesan no adb device online — start an emulator or pass --avd NAME bila tidak ada satu pun cli/hiddenjar:193-203.

Daftar jar ditentukan pada tahap ini: --only-framework menarik satu entri /system/framework/framework.jar, sedangkan default membaca seluruh $BOOTCLASSPATH cli/hiddenjar:275-283. Setiap jar harus melewati dua syarat sebelum dikonversi, yaitu ukuran minimal MIN_JAR_BYTES = 1024 dan keberadaan entri classes*.dex cli/hiddenjar:275-283 cli/hiddenjar:15-19.

Hasil konversi dirakit di memori oleh BuildJar lewat pembungkus assemble_jar, dengan path keluaran default $(pwd)/android-<api>-custom.jar cli/hiddenjar:324-335. Sesudah perakitan, verify_compile menjadi gate kelulusan, dan install_jar hanya dipanggil bila --install diberikan cli/hiddenjar:337-345.

Daftar flag

parse_args memetakan setiap flag ke satu variabel OPT_*; flag tak dikenal langsung berhenti lewat die "unknown option: $1", sedangkan -h dan --help mencetak usage lalu exit 0 cli/hiddenjar:496-516.

⚠️ --install menimpa android.jar di dalam SDK. Backup android.jar.orig hanya dibuat sekali; bila file backup sudah ada, install_jar mempertahankannya, sehingga versi asli yang tersimpan adalah versi dari pemasangan pertama, bukan versi terbaru sebelum penimpaan cli/hiddenjar:444-457.

⚠️ --keep-bodies sengaja mempertahankan method body asli dari dex2jar. Skrip mencetak peringatan bahwa Gradle lint dan unit test (MockableJarTransform) akan gagal pada jar tersebut, jadi pakai hanya untuk membaca hasil decompile cli/hiddenjar:324-335.

Pemetaan flag ke fase build

graph LR
  F1["--serial / --avd"] --> P1["pick_serial, boot_avd_if_needed"]
  F2["--api"] --> P2["getprop ro.build.version.sdk"]
  F3["--sdk-dir"] --> P3["resolve_sdk_dir, resolve_platform_dir"]
  F4["--only-framework"] --> P4["jar_list = framework.jar saja"]
  F5["--dex-tools"] --> P5["ensure_dex_tools, cache ~/.cache/hiddenjar"]
  F6["--output"] --> P6["path android-api-custom.jar"]
  F7["--keep-bodies / --keep-dangling"] --> P7["flag tambahan untuk BuildJar"]
  F8["--install"] --> P8["install_jar, tulis android.jar"]
  F9["--work-dir / --keep"] --> P9["WORK_DIR dan trap cleanup"]
  style F4 fill:#2d7d46,color:#fff
  style P4 fill:#2d7d46,color:#fff
  style F8 fill:#dc2626,color:#fff
  style P8 fill:#dc2626,color:#fff
  style F7 fill:#f59e0b,color:#000
  style P7 fill:#f59e0b,color:#000
  style F9 fill:#f59e0b,color:#000
  style P9 fill:#f59e0b,color:#000
  style F5 fill:#8b5cf6,color:#fff
  style P5 fill:#8b5cf6,color:#fff

%% fig: Setiap flag menyentuh satu fase build %% desc: Flag menentukan tahap mana yang berubah: pemilihan device, resolusi SDK, daftar jar, konversi, perakitan, atau pemasangan ke SDK.

Warna pada diagram memisahkan tiga sifat flag: hijau untuk jalur cepat --only-framework, merah untuk --install yang menulis ke SDK, dan kuning untuk flag yang mengubah direktori kerja atau bentuk stub. Flag --work-dir dan --keep bekerja bersama cleanup, yang menghapus work dir sementara hanya ketika WORK_DIR_IS_TEMP bernilai true dan OPT_KEEP bukan true cli/hiddenjar:58-65. Detail tiap fase perakitan ada di Pipeline Build hiddenjar.

doctor, install_jar, dan restore

cmd_doctor mencetak satu baris per alat: adb, javac, jar, unzip, zip (opsional), dex2jar, sdk-dir, lalu daftar device. Alat yang tidak ditemukan ditandai MISSING dan membuat exit status menjadi tidak nol, dengan penutup doctor: all required tools present atau doctor: some tools missing (see above) cli/hiddenjar:476-491.

install_jar memeriksa keberadaan android.jar.orig lebih dulu, menyalin target ke sana bila belum ada, menimpa android.jar dengan hasil build, lalu mencetak pengingat hiddenjar restore --api <level> cli/hiddenjar:444-457. Prosedur pemasangan manual yang setara dibahas di Memasang Custom android.jar ke SDK.

cmd_restore menolak berjalan tanpa --api dengan pesan restore requires --api N, menolak bila platform tidak ditemukan, dan menolak bila backup tidak ada dengan pesan no backup found at ... cli/hiddenjar:462-471.

Verifikasi yang dijalankan sebelum pemasangan terdiri atas empat pemeriksaan terpisah, yaitu compile probe, conflict guard, public-API floor, dan supertype closure cli/hiddenjar:348-354. Rincian tiap pemeriksaan dibahas di Verifikasi Jar Kustom.

Padanan PowerShell

cli/hiddenjar.ps1 meniru permukaan perintah bash, tetapi beberapa detail lingkungan berbeda.

Perbedaan urutan argumen berarti cli\hiddenjar.ps1 --api 37 build tetap sah, sedangkan bentuk yang sama pada skrip bash akan gagal karena main membaca argumen pertama sebagai subcommand cli/hiddenjar.ps1:494-530⁷. Pemetaan yang sama juga dipakai Gradle wrapper; lihat Task Gradle Pembungkus hiddenjar.

Contoh pemakaian

./cli/hiddenjar doctor
./cli/hiddenjar build --api 37
./cli/hiddenjar build --only-framework
./cli/hiddenjar build --avd Pixel_10_API_37 --install
./cli/hiddenjar restore --api 37

powershell -ExecutionPolicy Bypass -File cli\hiddenjar.ps1 doctor
powershell -ExecutionPolicy Bypass -File cli\hiddenjar.ps1 build --api 37
powershell -ExecutionPolicy Bypass -File cli\hiddenjar.ps1 restore --api 37

README mencatat bahwa flag yang sama berlaku di kedua skrip: --serial, --avd, --api, --sdk-dir, --output, --install, --only-framework, --keep-bodies, --keep-dangling, dan --dex-tools README.md:49-79¹¹.