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 terkait menjalankan proses debug di Android Studio.

Persyaratan

Agar proses debug native command line dapat difungsikan, persyaratan berikut harus dipenuhi:

  • Buat aplikasi menggunakan skrip ndk-build. Skrip ndk-gdb tidak mendukung penggunaan metode make APP=<name> lama untuk membuat aplikasi.
  • Aktifkan proses debug aplikasi pada file AndroidManifest.xml dengan memasukkan elemen <application> yang menetapkan atribut android:debuggable ke true.
  • Buat aplikasi Anda untuk berjalan pada 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 keperluan proses debug, level API target yang Anda nyatakan dalam file AndroidManifest.xml tidak berpengaruh.
  • Kembangkan aplikasi Anda di shell Unix. Pada Windows, gunakan Cygwin atau implementasi Python ndk-gdb-py eksperimental.
  • Gunakan GNU Make 3.81 atau yang lebih tinggi.

Penggunaan

Untuk memanggil ndk-gdb, beralihlah 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 menunjuk ke jalur penginstalan NDK.

Saat Anda memanggil ndk-gdb, kode ini akan mengonfigurasi sesi untuk mencari file sumber dan versi simbol/debug library native yang telah Anda hasilkan. Setelah berhasil menambahkannya 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 menampilkan prompt GDB normal.

Anda berinteraksi dengan ndk-gdb dengan cara yang sama seperti yang Anda lakukan dengan GNU GDB. Sebagai contoh, Anda dapat menggunakan b <location> untuk menetapkan titik henti sementara, dan c (untuk "continue") untuk melanjutkan eksekusi. Untuk daftar lengkap perintah, lihat Panduan GDB.

Harap perhatikan bahwa saat Anda keluar dari prompt GDB, proses aplikasi yang sedang Anda debug akan berhenti. Perilaku ini merupakan kelemahan GDB.

ndk-gdb menangani banyak kondisi error, dan menampilkan pesan error informatif jika menemukan masalah. Pemeriksaan ini termasuk memastikan bahwa kondisi berikut terpenuhi:

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

Secara default, ndk-gdb 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 lebih lanjut, lihat Opsi.

Opsi

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

Tabel 1. Opsi ndk-gdb umum dan deskripsinya.

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

Opsi Deskripsi
--verbose

Opsi ini memerintahkan sistem build untuk mencetak informasi verbose 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 digugurkan jika ternyata sesi proses debug native lain sudah berjalan di perangkat yang sama. Opsi ini akan mematikan sesi lain tersebut, dan menggantinya dengan sesi baru. Perhatikan bahwa opsi ini tidak mematikan aplikasi sebenarnya yang sedang di-debug, yang harus Anda matikan secara terpisah.
--start

Saat Anda memulai ndk-gdb, secara default kode ini mencoba terhubung ke instance aplikasi yang sedang berjalan pada perangkat target. Anda dapat mengganti perilaku default ini menggunakan --start untuk secara eksplisit meluncurkan aplikasi pada perangkat target sebelum sesi proses debug.

--launch=<name>

Opsi ini mirip dengan - --start, kecuali bahwa opsi ini memungkinkan Anda memulai aktivitas tertentu dari aplikasi. Fitur ini hanya berguna jika manifes Anda menetapkan beberapa aktivitas launchable.

--launch-list

Opsi kenyamanan ini mencetak daftar semua nama aktivitas launchable yang ditemukan dalam manifes aplikasi. --start menggunakan nama aktivitas pertama.

--project=<path> Opsi ini menentukan direktori project aplikasi. Berguna jika Anda ingin meluncurkan skrip tanpa perlu berganti 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 untuk men-debug secara native program yang berjalan pada perangkat atau emulator lain yang terhubung ke mesin host yang sama.

--adb=<file>

Opsi ini menentukan executable fitur adb. Hanya diperlukan jika Anda belum menetapkan jalur untuk menyertakan file executable tersebut.

  • -d
  • -e
  • -s <serial>
  • Tanda ini serupa dengan perintah adb dengan nama yang sama. Tetapkan tanda ini jika Anda memiliki beberapa perangkat atau emulator yang terhubung ke mesin host. Arti tanda 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 membuat daftar perangkat tertentu, tanpa perlu menggunakan opsi tertentu.

  • --exec=<file>
  • -x <file>
  • Opsi ini memerintahkan 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 adalah tanda tambahan untuk diteruskan ke sistem ndk-build saat membuat kueri untuk meminta informasi project. Anda dapat menggunakan banyak instance opsi ini dalam perintah yang sama.

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

    Dukungan Thread

    Jika aplikasi Anda berjalan pada 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 sebuah fungsi yang dijalankan bukan pada thread utama, program akan ditutup, dan GDB akan menampilkan pesan berikut:

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