استخدام برامج تصحيح الأخطاء

توضِّح هذه الصفحة تفاصيل استخدام LLDB لتطوير نظام التشغيل. بالنسبة إلى تطوير التطبيقات، يمكنك الاطّلاع على مقالة تصحيح أخطاء تطبيقك بدلاً من ذلك، والتي توضّح كيفية استخدام واجهة مستخدم "استوديو Android" (استنادًا إلى LLDB).

لم تعُد أداة GDB متاحة أو متوافقة. إذا كنت بصدد التبديل من GDB إلى LLDB، عليك ربما البدء بقراءة الدليل التعليمي حول LLDB. إذا كنت من خبراء استخدام GDB، سيكون جدول تعيين أوامر GDB إلى LLDB مفيدًا جدًا أثناء عملية النقل.

المتطلّبات الأساسية

لاستخدام أداة تصحيح الأخطاء:

  • يمكنك إعداد بيئة التصميم باستخدام الأمر envsetup.sh المعتاد.
  • نفِّذ الأمر lunch نفسه الذي استخدمته عند الإنشاء. يُرجى العِلم أنّ عنصر الإطلاق يجب أن يتطابق تمامًا مع الجهاز الذي تصحّح أخطاءه. إذا لم يتطابق جهاز الغداء مع الجهاز المرفق، ستظهر لك رسالة خطأ على النحو التالي: You used the wrong lunch: TARGET_PRODUCT (aosp_arm64) does not match attached device (xyzabc)
  • وصِّل جهازك بالماكينة.

للحصول على مزيد من المساعدة في إعداد بيئتك، يُرجى الاطّلاع على مقالة إعداد البيئة.

تصحيح أخطاء ملف ثنائي

لتصحيح أخطاء ملف ثنائي أنشأته على جهازك، عليك أولاً نسخ الملف الثنائي إلى الجهاز ثم تشغيل أداة تصحيح الأخطاء. مثلاً: 

adb push test.exe /data/local/tmp/test.exe
lldbclient.py --port 5038 -r /data/local/tmp/test.exe

تصحيح أخطاء التطبيقات أو العمليات الجارية

للاتصال بتطبيق قيد التشغيل أو برنامج تابع لنظام التشغيل، استخدِم lldbclient.py مع رقم تعريف العملية. على سبيل المثال، لتصحيح أخطاء العملية التي تحمل رقم تعريف العملية 1234، يمكنك تنفيذ ما يلي على المضيف:

lldbclient.py -p 1234

يُعدّ النص البرمجي عملية إعادة توجيه المنفذ، ويشغّل مقتطف تصحيح الأخطاء عن بُعد المناسب على الجهاز، ويشغّل مصحِّح الأخطاء على المضيف، ويضبطه للعثور على الرموز، ويربطه مقتطف تصحيح الأخطاء عن بُعد.

تصحيح أخطاء بدء العملية الأصلية

لتصحيح أخطاء عملية أثناء بدء تشغيلها، استخدِم lldbclient.py مع الخيار -r. على سبيل المثال، لتصحيح أخطاء ls /bin، يمكنك تنفيذ ما يلي على المضيف:

lldbclient.py -r /system/bin/ls /bin

بعد ذلك، أدخِل continue عند ظهور طلب من مصحِّح الأخطاء.

تصحيح أخطاء بدء تشغيل التطبيق

في بعض الأحيان، تريد تصحيح أخطاء تطبيق عند بدء تشغيله، مثلاً عند حدوث عطل وتريد مراجعة الرمز البرمجي لمعرفة ما حدث قبل العُطل. يمكن إرفاق الملفات في بعض الحالات، ولكن في حالات أخرى، يكون ذلك مستحيلاً لأنّ التطبيق يتعطّل قبل أن تتمكّن من إرفاق الملفات. لا يعمل أسلوب logwrapper (المستخدَم في strace) دائمًا لأنّ التطبيق قد لا يملك أذونات لفتح منفذ، ويرث lldbserver هذا القيود.

لتصحيح أخطاء بدء تشغيل التطبيق، استخدِم خيارات المطوّرين في "الإعدادات" لتوجيه التطبيق إلى الانتظار إلى أن يتم إرفاق برنامج تصحيح أخطاء Java:

  1. انتقِل إلى الإعدادات > خيارات المطوّرين > اختيار تطبيق لتصحيح الأخطاء واختَر تطبيقك من القائمة، ثم انقر على الانتظار إلى أن ينتهي تصحيح الأخطاء.
  2. ابدأ التطبيق، إما من مشغّل التطبيقات أو باستخدام سطر الأوامر لتشغيل: 
    adb shell am start -a android.intent.action.MAIN -n APP_NAME/.APP_ACTIVITY
  3. انتظِر تحميل التطبيق إلى أن يظهر لك مربّع حوار يُعلمك بأنّ التطبيق في انتظار برنامج تصحيح أخطاء.
  4. اربط lldbserver/lldbclient بشكلٍ طبيعي، واضبط نقاط التوقف، ثم واصِل العملية.

للسماح بتشغيل التطبيق، يجب إرفاق أداة تصحيح أخطاء Java Debug Wire Protocol (JDWP) مثل Java Debugger (jdb):

adb forward tcp:12345 jdwp:XXX  # (Where XXX is the PID
of the debugged process.)
jdb -attach localhost:12345

تصحيح أخطاء التطبيقات أو العمليات التي تتعطل

إذا كنت تريد أن يعلّق debuggerd العمليات التي تعطّلت حتى تتمكّن من إرفاق أداة تصحيح أخطاء، اضبط السمة المناسبة:

  • بعد Android 11 
    adb shell setprop debug.debuggerd.wait_for_debugger true
  • الإصدار 11 من نظام التشغيل Android والإصدارات الأقدم 
    adb shell setprop debug.debuggerd.wait_for_gdb true
  • Android 6.0 Marshmallow والإصدارات الأقدم 
    adb shell setprop debug.db.uid 999999

في نهاية مخرجات الأعطال المعتادة، يوفّر debuggerd تعليمات نسخ ولصق في logcat توضّح كيفية ربط أداة تصحيح الأخطاء بالعملية التي حدث بها العُطل.

تصحيح الأخطاء باستخدام VS Code

يتيح LLDB تصحيح أخطاء رمز النظام الأساسي على IDE Visual Studio Code. يمكنك استخدام واجهة مستخدم برنامج تصحيح أخطاء VS Code بدلاً من واجهة سطر أوامر LLDB للتحكّم في الرمز البرمجي الأصلي الذي يتم تشغيله على الأجهزة و تصحيح أخطاءه.

قبل استخدام VS Code لتصحيح الأخطاء، ثبِّت إضافة CodeLLDB.

لتصحيح أخطاء الرمز باستخدام VS Code:

  1. تأكَّد من توفُّر جميع عناصر التصميم (مثل الرموز) المطلوبة لتشغيل lldbclient.py أو lldbclient.py.
  2. في VS Code، اضغط على Ctrl+Shift+P لتشغيل أمر، وابحث عن Debug: Add Configuration... (تصحيح الأخطاء: إضافة إعدادات...)، ثم اختَر LLDB. يؤدي ذلك إلى فتح ملف launch.json وإضافة عنصر JSON جديد إلى قائمة.
  3. استبدِل إعدادات مصحِّح الأخطاء التي تمت إضافتها حديثًا بسطرَي تعليقات، // #lldbclient-generated-begin و// #lldbclient-generated-end، ليصبح شكل قائمة الإعدادات على النحو التالي: 
    "configurations": [
    // #lldbclient-generated-begin
    // #lldbclient-generated-end
]

    يستخدم تطبيق lldbclient.py هذه التعليقات لرصد مكان كتابة الإعدادات. إذا كان هناك عناصر أخرى في القائمة، أضِف أسطر التعليقات إلى النهاية بعد الإعدادات الأخرى.

  4. نفِّذ الأمر التالي في الوحدة الطرفية التي نفّذت فيها envsetup.sh و lunch: 
    lldbclient.py --setup-forwarding vscode-lldb \
      --vscode-launch-file LAUNCH_JSON_PATH \
      ANY_OTHER_FLAGS -p pid | -n proc-name | -r ...

    يكتب lldbclient.py الإعدادات التي تم إنشاؤها في launch.json ويكمل عملية التشغيل. هذا أمر متوقّع، ولا تُغلِق برنامج lldbclient.py. إذا حذفت--vscode-launch-file، سيطبع النص البرمجي مقتطف JSON الذي عليك نسخه ولصقه فيlaunch.json يدويًا.

    يجب أن تكون العلامة -r هي العلامة الأخيرة إذا كانت متوفّرة بسبب طريقة تحليل العلامات بواسطة الأداة.

  5. افتح الشريط الجانبي التشغيل وتصحيح الأخطاء، ومن المفترض أن تظهر الإعدادات الجديدة في قائمة مصحِّح الأخطاء. اضغط على بدء تصحيح الأخطاء (F5). من المفترض أن يتم ربط أداة تصحيح الأخطاء بعد 10 إلى 30 ثانية.

    إذا لم تظهر الإعدادات الجديدة في عرض "التشغيل وتصحيح الأخطاء"، أعِد تحميل النافذة لمحاولة تحديث قائمة مصحِّح الأخطاء: اضغط على Ctrl+Shift+P واكتب reload window.

  6. عند الانتهاء من تصحيح الأخطاء، انتقِل إلى المحطة الطرفية التي تعمل على تنفيذ lldbclient.py واضغط على Enter لإنهاء برنامج lldbclient.py. ستؤدي عمليات التشغيل اللاحقة للنص البرمجي إلى إنشاء ملف الإعدادات بين التعليقات #lldbclient-generated واستبدال المحتوى القديم، ولن تحتاج إلى إزالته يدويًا.

لإضافة خصائص مخصّصة إلى إعدادات الإطلاق التي تم إنشاؤها، يمكنك استخدام العلامة --vscode-launch-props. مثلاً: 

lldbclient.py --setup-forwarding vscode-lldb \
    --vscode-launch-props \
    '{"initCommands" : ["script print(\"Hello\")"], "preLaunchTask" : "Build"}' \
    ...
 سيؤدي مثال السمات إلى تشغيل VS Code لمهمّة باسم Build قبل تصحيح الأخطاء، ويُلحق خطوة جديدة لبدء تصحيح الأخطاء بالخطوات التي أنشأها النص البرمجي. يمكنك العثور على نظرة عامة على السمات المتاحة في مستندات VS Code وفي دليل المستخدم الخاص بملف إضافة CodeLLDB.