تشغيل Winscope

تتبُّع Winscope هو جزء من إطار عمل Android. توضّح هذه الصفحة الخطوات المطلوبة لتنزيل أداة عرض عمليات التتبُّع في Winscope وإنشائها وتشغيلها على جهازك.

إنشاء Winscope محليًا

اتّبِع الخطوات التالية لإعداد جهاز الكمبيوتر لتشغيل أداة Winscope لتتبُّع الأخطاء:

1. تنزيل مصدر Android

2. انتقِل إلى مجلد Winscope:

   cd development/tools/winscope
   

3. ثبِّت الحِزم التابعة باستخدام:

   npm install
   

   للاطّلاع على قائمة بالأوامر المتاحة، شغِّل الأمر: npm run

4. إنشاء جميع أهداف الإنتاج والاختبار باستخدام:

   npm run build:prod
   

5. شغِّل Winscope باستخدام:

   npm run start
   

إنشاء أجزاء منفصلة

يمكنك إنشاء أجزاء فردية من Winscope بشكل منفصل باستخدام الأوامر التالية:

إجراء الاختبارات

يحتوي Winscope على اختبارات الوحدة والاختبارات الشاملة. لتشغيلها، استخدِم npm run <command>:

اختبارات شاملة

قبل تشغيل اختبارات شاملة، عليك بدء تشغيل الأداة البعيدة وتثبيت الإصدار الصحيح من برنامج تشغيل Chrome. في مقتطف الرمز البرمجي التالي، يثبّت الأمر run test:e2e برنامج تشغيل Chrome تلقائيًا.

$ npm run start
$ npm run start:remote_tool_mock
$ npm run test:e2e

يسرد الجدول التالي الأوامر الضرورية وأوصافها. لتشغيلها، استخدِم npm run command:

تعديل عملية الربط بين @IntDef

‫@IntDef هي تعليق توضيحي يُستخدم في Android لحصر القيم المحتملة لعدد صحيح. يستخدم Winscope عملية ربط بين هذه التعليقات التوضيحية لعرض اسم القيمة بدلاً من العدد الصحيح.

إذا تمت إضافة قيم @IntDef جديدة إلى إطار عمل Android ولكن لم يتم تعديلها في Winscope، سيتم عرضها كقيم عددية أولية بدلاً من السلاسل الوصفية. لحلّ هذه المشكلة، عدِّل ملف ربط IntDef (development/tools/winscope/src/common/intDefMapping.json).

لتعديل عملية الربط @IntDef تلقائيًا، اتّبِع الخطوات التالية:

1. نفِّذ النص البرمجي update_intdef_mappings.sh من الدليل development/tools/winscope/scripts/ في بنية Android المحلية. يؤدي هذا النص البرمجي إلى تشغيل عملية إضافة التعليقات التوضيحية التي تستخرج أحدث قيم @IntDef من الرمز وتعدّل intDefMapping.json:

   cd development/tools/winscope
   ./scripts/update_intdef_mappings.sh
   

2. نفِّذ التغييرات على src/common/intDefMapping.json باستخدام الأمر git commit وحمِّلها باستخدام الأمر repo upload.

إذا لم يكن النص البرمجي متاحًا، اتّبِع الخطوات التالية لتعديل @IntDef عملية الربط يدويًا من دليل الجذر في Android ($ANDROID_BUILD_TOP):

1. أنشئ framework-minus-apex-intdefs لكي يتم تشغيل المعالجة المُسبَقة للتعليقات التوضيحية:

   m framework-minus-apex-intdefs
   

2. انسخ ملف intDefMapping.json الذي تم إنشاؤه إلى مستودع الحِزم المُنشأة مسبقًا:

   $ python3 -c 'import sys,json,collections; print(json.dumps(collections.OrderedDict(sorted(collections.ChainMap(*map(lambda x:json.load(open(x)), sys.argv[1:])).items())), indent=2))' $(find out/soong/.intermediates/frameworks/base -iname intDefMapping.json) > ./development/tools/winscope/src/common/intDefMapping.json
   

3. حمِّل التغييرات في Winscope باستخدام repo upload.

طلبات أخرى

بالإضافة إلى عمليات الإنشاء والاختبار، تحتوي نصوص Winscope البرمجية على إمكانات أخرى، كما هو موضّح في الجدول. لتشغيلها، استخدِم npm run command:

تحديد المشاكل وحلّها

اتّبِع النصائح التالية لتحديد المشاكل وحلّها:

• الخطأ ProtocolError: missing required '<FIELD>' أو TypeError: Cannot read property '<PROP>' of null

  • يحدث ذلك عندما يتم إنشاء ملف التتبُّع باستخدام تعريف proto جديد، يحتوي على حقول مطلوبة جديدة.

    1. تأكَّد من فتح التتبُّع على إصدار Winscope الصحيح (الإصدار الرئيسي أو الإصدار S أو الإصدار R).

    2. إذا أنشأت الحقل الجديد في ملف proto، عليك إعادة تجميع ملفات proto في Winscope باستخدام npm run build:protos.

• بعض إصدارات الاعتماديات المثبَّتة غير صحيحة (يتعذّر إنشاء الإصدار)

  • إلغاء التغييرات التي أجريتها على package.json وpackage-lock.json إزالة node_modules نفِّذ الأمر npm install مرة أخرى.

• أضفتُ حقلًا جديدًا إلى أحد ملفات proto. كيف يمكنني عرضها؟

  • يستخدم Winscope تعريفات proto من وقت تجميعه، لذا لن تظهر الحقول الجديدة تلقائيًا. لعرض الحقول الجديدة، أعِد إنشاء ملفات protos باستخدام npm run build:protos.