ndk-gdb

يتضمّن NDK نصًا برمجيًا في واجهة الأوامر يسمى ndk-gdb لبدء جلسة تصحيح أخطاء أصلية لسطر الأوامر. على المستخدمين الذين يفضّلون استخدام واجهة المستخدم الرسومية الاطّلاع على مستندات تصحيح الأخطاء في Android Studio بدلاً من ذلك.

الشروط

لكي يعمل تصحيح الأخطاء الأصلي لسطر الأوامر، يجب استيفاء المتطلبات التالية:

• أنشِئ تطبيقك باستخدام نص ndk-build البرمجي. لا يتيح النص البرمجي ndk-gdb استخدام طريقة make APP=<name> القديمة لإنشاء الإصدار.
• يمكنك تفعيل ميزة "تصحيح أخطاء التطبيقات" في ملف AndroidManifest.xml عن طريق تضمين العنصر <application> الذي يضبط السمة android:debuggable على true.
• أنشئ تطبيقك لتشغيله على Android 2.2 (المستوى 8 لواجهة برمجة تطبيقات Android) أو إصدارات أحدث.
• يمكنك تصحيح الأخطاء على جهاز أو محاكي يعمل بنظام التشغيل Android 2.2 أو إصدار أحدث. لأغراض تصحيح الأخطاء، لا يهم مستوى واجهة برمجة التطبيقات المستهدف الذي تعلن عنه في ملف AndroidManifest.xml.
• طوّر التطبيق في واجهة أوامر Unix. على نظام التشغيل Windows، استخدِم Cygwin أو تنفيذ ndk-gdb-py Python التجريبي.
• استخدِم GNU Make 3.81 أو أعلى.

الاستخدام

لاستدعاء النص البرمجي ndk-gdb، يمكنك التغيير إلى دليل التطبيق أو أي دليل ضمنه. مثلاً:

cd $PROJECT
$NDK/ndk-gdb

هنا، يشير $PROJECT إلى الدليل الجذر لمشروعك، ويشير $NDK إلى مسار تثبيت NDK.

عند استدعاء ndk-gdb، يتم ضبط الجلسة للبحث عن ملفات المصدر ونُسخ الرموز/تصحيح الأخطاء في مكتباتك الأصلية التي تم إنشاؤها. عند إرفاق المحتوى في عملية الطلب بنجاح، يعرض ndk-gdb سلسلة طويلة من رسائل الخطأ، مع الإشارة إلى أنّه يتعذّر عليه العثور على مكتبات نظام مختلفة. وهذا أمر طبيعي لأن الجهاز المضيف لا يحتوي على إصدارات الرموز/تصحيح الأخطاء من هذه المكتبات على جهازك المستهدف. يمكنك تجاهل هذه الرسائل بأمان.

بعد ذلك، يعرض ndk-gdb طلب GDB عاديًا.

تتفاعل مع ndk-gdb بالطريقة نفسها التي تتفاعل بها مع GNU GDB. على سبيل المثال، يمكنك استخدام b <location> لضبط نقاط الإيقاف واستخدام c (المصطلح "متابعة") لاستئناف التنفيذ. للحصول على قائمة شاملة بالأوامر، راجِع دليل GDB. إذا كنت تفضّل استخدام برنامج تصحيح الأخطاء LLDB، استخدِم الخيار --lldb عند استدعاء النص البرمجي ndk-gdb.

لاحظ أنه عند إنهاء موجه GDB، ستتوقف عملية التطبيق التي تقوم بتصحيحها. وهذا السلوك هو أحد قيود gdb.

يتعامل ndk-gdb مع العديد من حالات الخطأ، ويعرض رسالة خطأ إعلامية إذا وجد أي مشكلة. وتشمل عمليات التحقّق هذه التأكّد من استيفاء الشروط التالية:

• يتحقّق من أنّ ADB في مسارك.
• يتحقّق هذا الإعداد من أنّه تم تعريف تطبيقك بأنّه قابل للتصحيح في ملف البيان.
• للتحقق من أنّ التطبيق المثبّت الذي يحمل اسم الحزمة نفسه قابل للتصحيح أيضًا على الجهاز.

بشكل تلقائي، يبحث ndk-gdb عن عملية تطبيق قيد التشغيل، ويعرض رسالة خطأ إذا لم يعثر على أي عملية. ومع ذلك، يمكنك استخدام الخيار --start أو --launch=<name> لبدء نشاطك تلقائيًا قبل جلسة تصحيح الأخطاء. لمزيد من المعلومات، يُرجى الاطّلاع على الخيارات.

الخيارات

للاطّلاع على قائمة كاملة بالخيارات، اكتب ndk-gdb --help في سطر الأوامر. ويوضح الجدول 1 عددًا من أكثرها استخدامًا، إلى جانب أوصاف موجزة.

الجدول 1. خيارات ndk-gdb الشائعة وأوصافها.

بدءًا من ndk-gdb مع تحديد هذا الخيار، سيتم تشغيل أول نشاط قابل للتشغيل مدرج في بيان التطبيق. استخدم --launch=<name> لبدء النشاط التالي للإطلاق. ولحذف قائمة الأنشطة القابلة للتشغيل، شغِّل --launch-list من سطر الأوامر.

Option	الوصف>
--lldb	في حال التعيين، سيستخدم النص البرمجي برنامج تصحيح أخطاء LLDB للجلسة بدلاً من gdb.
--verbose	يطلب هذا الخيار من نظام الإصدار طباعة معلومات مطوَّلة بشأن إعداد جلسة تصحيح الأخطاء الأصلية. وهو أمر ضروري فقط لمعالجة المشاكل المتعلقة بتصحيح الأخطاء عندما يتعذّر على برنامج تصحيح الأخطاء الاتصال بالتطبيق، ولا تكون رسائل الخطأ التي يعرضها ndk-gdb كافية.
--force	يتم إلغاء ميزة ndk-gdb تلقائيًا إذا رصدت أنّه يتم تشغيل جلسة تصحيح أخطاء أصلية أخرى على الجهاز نفسه. يؤدي هذا الخيار إلى إنهاء الجلسة الأخرى واستبدالها بجلسة جديدة. تجدر الإشارة إلى أنّ هذا الخيار لا يؤدي إلى إنهاء التطبيق الفعلي الذي يتم تصحيح أخطائه، والذي يجب إيقافه بشكل منفصل.
--start	عند بدء تشغيل ndk-gdb، يحاول تلقائيًا إرفاق الجهاز بمثيل قيد التشغيل حاليًا لتطبيقك على الجهاز المستهدف. يمكنك إلغاء هذا السلوك التلقائي باستخدام --start لتشغيل التطبيق بشكل صريح على الجهاز المستهدف قبل جلسة تصحيح الأخطاء.
--launch=<name>	يشبه هذا الخيار --start، باستثناء أنّه يسمح لك ببدء نشاط محدّد من تطبيقك. لا تكون هذه الميزة مفيدة إلا إذا كان البيان يحدّد أنشطة متعددة قابلة للتشغيل.
--launch-list	يطبع هذا الخيار المريح قائمة بجميع أسماء الأنشطة القابلة للتشغيل الواردة في بيان التطبيق. يستخدم --start اسم النشاط الأول.
--project=<path>	يحدِّد هذا الخيار دليل مشروع التطبيق. وهو مفيد إذا كنت تريد تشغيل النص البرمجي بدون الحاجة إلى التغيير إلى دليل المشروع أولاً.
--port=<port>	يستخدم ndk-gdb تلقائيًا منفذ TCP المحلي 5039 للاتصال بالتطبيق الذي يُصحح الأخطاء على الجهاز المستهدف. ويسمح لك استخدام منفذ مختلف بتصحيح الأخطاء في البرامج التي تعمل على أجهزة مختلفة أو برامج محاكاة متصلة بالجهاز المضيف نفسه.
--adb=<file>	يحدِّد هذا الخيار أداة adb القابلة للتنفيذ. يكون ذلك ضروريًا فقط إذا لم يتم تعيين المسار لتضمين ذلك الملف التنفيذي.
-d -e -s <serial>	تشبه هذه العلامات أوامر adb التي تحمل الأسماء نفسها. عليك تعيين هذه العلامات إذا كان لديك العديد من الأجهزة أو أدوات المحاكاة المتصلة بالجهاز المضيف. وفي ما يلي معانيها: -d يُرجى الاتصال بجهاز فعلي واحد. -e اتصل بجهاز محاكي واحد. -s <serial> اتصل بجهاز أو محاكٍ محدّد. يظهر هنا <serial> اسم الجهاز كما هو وارد في الأمر adb devices. ويمكنك بدلاً من ذلك تحديد متغيّر بيئة ADB_SERIAL لإدراج جهاز محدّد، بدون الحاجة إلى خيار محدّد.
--exec=<file> -x <file>	يطلب هذا الخيار من ndk-gdb تشغيل أوامر إعداد GDB المتوفّرة في <file> بعد الاتصال بالعملية التي يتم تصحيح الأخطاء بها. هذه ميزة مفيدة إذا كنت تريد تنفيذ إجراء ما بشكل متكرر، مثل إعداد قائمة بنقاط الإيقاف، ثم استئناف التنفيذ تلقائيًا.
--nowait	إيقاف إيقاف رمز Java مؤقتًا حتى يتم اتصال GDB. قد يؤدي تمرير هذا الخيار إلى تفويت برنامج تصحيح الأخطاء لنقاط الإيقاف المبكرة.
--tui -t	تفعيل واجهة المستخدم النصية إذا كانت متاحة.
--gnumake-flag=<flag>	يمثّل هذا الخيار علامة (أو علامات) إضافية يجب تمريرها إلى نظام ndk-build عند طلب البحث عن معلومات المشروع. يمكنك استخدام عدة مثيلات من هذا الخيار باستخدام نفس الأمر.

ملاحظة: الخيارات الثلاثة الأخيرة في هذا الجدول مخصصة فقط لإصدار Python من ndk-gdb.

إتاحة سلسلة المحادثات

إذا كان تطبيقك يعمل على نظام أساسي أقدم من Android 2.3 (المستوى 9 من واجهة برمجة التطبيقات)، لن يتمكّن ndk-gdb من تصحيح أخطاء سلاسل المحادثات الأصلية على نحو سليم. يمكن لبرنامج تصحيح الأخطاء تصحيح أخطاء سلسلة التعليمات الرئيسية فقط، ويتجاهل Abd تنفيذ سلاسل التعليمات الأخرى تمامًا.

إذا وضعت نقطة إيقاف على دالة يتم تنفيذها على سلسلة تعليمات غير رئيسية، يتم الخروج من البرنامج، ويعرض GDB الرسالة التالية:

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