ndk-gdb

NDK menyertakan skrip shell bernama ndk-gdb untuk memulai sesi proses debug native command line. Pengguna yang lebih suka menggunakan GUI sebaiknya membaca dokumentasi untuk melakukan proses debug di Android Studio.

Persyaratan

Agar proses debug native command line dapat berjalan, persyaratan berikut harus terpenuhi:

  • Build aplikasi Anda menggunakan skrip ndk-build. Skrip ndk-gdb tidak mendukung penggunaan metode make APP=<name> lama untuk proses build.
  • Aktifkan proses debug aplikasi dalam file AndroidManifest.xml dengan menyertakan elemen <application> yang menetapkan atribut android:debuggable ke true.
  • Build aplikasi Anda agar berjalan di Android 2.2 (Android API level 8) atau yang lebih tinggi.
  • Debug pada perangkat atau emulator yang menjalankan Android 2.2 atau yang lebih tinggi. Untuk tujuan proses debug, API level target yang dideklarasikan dalam file AndroidManifest.xml tidak penting.
  • Kembangkan aplikasi di shell Unix. Di Windows, gunakan Cygwin atau implementasi Python ndk-gdb-py eksperimental.
  • Gunakan GNU Make 3.81 atau yang lebih tinggi.

Penggunaan

Untuk memanggil skrip ndk-gdb, ubah ke direktori aplikasi atau direktori apa pun di bawahnya. Contoh:

cd $PROJECT
$NDK/ndk-gdb

Di sini, $PROJECT mengarah ke direktori utama project, dan $NDK mengarah ke jalur penginstalan NDK.

Saat Anda memanggil ndk-gdb, kode tersebut akan mengonfigurasi sesi untuk mencari file sumber dan versi simbol/debug library native yang telah Anda hasilkan. Setelah berhasil melampirkannya ke proses aplikasi Anda, ndk-gdb akan mengeluarkan rangkaian panjang pesan error, yang menyampaikan bahwa kode tidak dapat menemukan berbagai library sistem. Hal ini normal, karena mesin host Anda tidak memuat versi simbol/debug library ini pada perangkat target. Anda dapat mengabaikan pesan ini dengan aman.

Selanjutnya, ndk-gdb akan menampilkan perintah GDB normal.

Tangani ndk-gdb dengan cara yang sama seperti saat menangani GDB GNU. Misalnya, Anda dapat menggunakan b <location> untuk menetapkan titik henti sementara, dan c (untuk "melanjutkan") untuk melanjutkan eksekusi. Untuk daftar lengkap perintah yang tersedia, lihat Panduan GDB. Jika Anda lebih memilih menggunakan Debugger LLDB, gunakan opsi --lldb saat memanggil skrip ndk-gdb.

Perlu diketahui bahwa saat keluar dari perintah GDB, proses aplikasi yang sedang Anda debug akan berhenti. Perilaku ini merupakan kelemahan GDB.

ndk-gdb menangani banyak kondisi error, dan akan menampilkan pesan error informatif saat menemukan masalah. Pemeriksaan ini mencakup proses untuk memastikan kondisi berikut terpenuhi:

  • Memeriksa apakah ADB berada di jalur Anda.
  • Memeriksa apakah aplikasi Anda dinyatakan dapat di-debug dalam manifesnya.
  • Memeriksa bahwa, aplikasi yang diinstal di perangkat dengan nama paket yang sama juga dapat di-debug.

Secara default, ndk-gdb akan menelusuri proses aplikasi yang sudah berjalan, dan menampilkan error jika tidak menemukannya. Namun, Anda dapat menggunakan opsi --start atau --launch=<name> untuk memulai aktivitas secara otomatis sebelum sesi proses debug. Untuk informasi selengkapnya, lihat Opsi.

Opsi

Untuk melihat daftar lengkap opsi yang tersedia, ketik ndk-gdb --help pada command line. Tabel 1 menunjukkan sejumlah opsi yang lebih umum digunakan, beserta deskripsi singkat.

Tabel 1. Opsi ndk-gdb umum dan deskripsinya.

Memulai ndk-gdb dengan opsi yang ditentukan ini akan meluncurkan aktivitas pertama yang dapat diluncurkan, yang tercantum dalam manifes aplikasi Anda. Gunakan --launch=<name> untuk memulai aktivitas berikutnya yang dapat diluncurkan. Untuk menghapus daftar aktivitas yang dapat diluncurkan, jalankan --launch-list dari command line.

Opsi Deskripsi
--lldb

Jika ditetapkan, skrip akan menggunakan Debugger LLDB untuk sesi, bukan gdb.

--verbose

Opsi ini memberi tahu sistem build untuk mencetak informasi panjang tentang penyiapan sesi proses debug native. Opsi ini hanya diperlukan untuk masalah proses debug ketika debugger tidak dapat terhubung ke aplikasi, dan pesan error yang ditampilkan ndk-gdb tidak memadai.

--force Secara default, ndk-gdb akan dibatalkan jika ada sesi proses debug native lain yang sudah berjalan di perangkat yang sama. Opsi ini akan menghentikan sesi lain tersebut, dan menggantinya dengan sesi baru. Perhatikan bahwa opsi ini tidak menghentikan aplikasi sebenarnya yang sedang di-debug, yang harus Anda hentikan secara terpisah.
--start

Ketika dimulai, ndk-gdb akan secara default mencoba mengaitkan ke instance aplikasi yang sedang berjalan di perangkat target. Anda dapat mengganti perilaku default ini menggunakan --start untuk meluncurkan aplikasi secara eksplisit di perangkat target sebelum sesi proses debug.

--launch=<name>

Opsi ini mirip dengan --start, tetapi memungkinkan Anda memulai aktivitas tertentu dari aplikasi Anda. Fitur ini hanya berguna jika manifes Anda menetapkan beberapa aktivitas yang dapat diluncurkan.

--launch-list

Opsi yang memudahkan ini menampilkan daftar semua nama aktivitas yang dapat diluncurkan yang ada dalam manifes aplikasi. --start menggunakan nama aktivitas pertama.

--project=<path> Opsi ini menetapkan direktori project aplikasi. Opsi ini dapat membantu jika Anda ingin meluncurkan skrip tanpa perlu berganti ke direktori project terlebih dahulu.
--port=<port>

Secara default, ndk-gdb menggunakan port TCP lokal 5039 untuk berkomunikasi dengan aplikasi yang sedang di-debug pada perangkat target. Penggunaan port berbeda memungkinkan Anda men-debug secara native program yang berjalan di berbagai perangkat atau emulator yang terhubung ke mesin host yang sama.

--adb=<file>

Opsi ini menentukan file alat adb yang dapat dieksekusi. Hanya diperlukan jika Anda belum menetapkan jalur untuk menyertakan file yang dapat dieksekusi tersebut.

  • -d
  • -e
  • -s <serial>
  • Flag ini serupa dengan perintah adb dengan nama yang sama. Tetapkan flag ini jika Anda memiliki beberapa perangkat atau emulator yang terhubung ke mesin host. Arti flag ini adalah seperti berikut:

    -d
    Menghubungkan ke satu perangkat fisik.
    -e
    Menghubungkan ke satu perangkat emulator.
    -s <serial>
    Menghubungkan ke perangkat atau emulator tertentu. Di sini, <serial> adalah nama perangkat seperti yang dicantumkan oleh perintah adb devices.

    Atau, Anda dapat menentukan variabel lingkungan ADB_SERIAL untuk mencantumkan daftar perangkat tertentu tanpa perlu menggunakan opsi khusus.

  • --exec=<file>
  • -x <file>
  • Opsi ini memberi tahu ndk-gdb untuk menjalankan perintah inisialisasi GDB yang ditemukan dalam <file> setelah terhubung ke proses yang sedang di-debug. Fitur ini berguna jika Anda ingin melakukan sesuatu secara berulang, seperti mengatur daftar titik henti sementara, lalu melanjutkan eksekusi secara otomatis.

    --nowait

    Menonaktifkan jeda kode Java hingga GDB terhubung. Melewatkan opsi ini dapat menyebabkan debugger kehilangan titik henti sementara terlalu dini.

    --tui -t

    Mengaktifkan Antarmuka Pengguna Teks jika tersedia.

    --gnumake-flag=<flag>

    Opsi ini merupakan flag (atau beberapa flag) tambahan untuk diteruskan ke sistem ndk-build saat membuat kueri untuk meminta informasi project. Anda dapat menggunakan beberapa instance opsi ini dalam perintah yang sama.

    Catatan: Ketiga opsi terakhir dalam tabel ini hanya untuk ndk-gdb versi Python.

    Dukungan thread

    Jika aplikasi berjalan di platform yang lebih lama dari Android 2.3 (API level 9), ndk-gdb tidak dapat men-debug thread native dengan benar. Debugger hanya dapat men-debug thread utama, dan sepenuhnya mengabaikan eksekusi thread lainnya.

    Jika Anda menempatkan titik henti sementara pada fungsi yang tidak dijalankan di thread utama, program akan ditutup, dan GDB akan menampilkan pesan berikut:

    Program terminated with signal SIGTRAP, Trace/breakpoint trap.
          The program no longer exists.