اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتبُّع Winscope هو جزء من إطار عمل Android. توضّح هذه الصفحة الخطوات المطلوبة لتنزيل أداة عرض عمليات التتبُّع في Winscope وإنشائها وتشغيلها على الجهاز.
إنشاء Winscope محليًا
اتّبِع الخطوات التالية لإعداد جهاز الكمبيوتر لتشغيل أداة Winscope Tracer:
للاطّلاع على قائمة بالأوامر المتاحة، شغِّل الأمر: npm run
إنشاء جميع أهداف الإنتاج والاختبار باستخدام:
npm run build:prod
شغِّل Winscope باستخدام:
npm run start
إنشاء أجزاء منفصلة
يمكنك إنشاء أجزاء فردية من Winscope بشكل منفصل باستخدام الأوامر التالية:
الأمر
الوصف
build:trace_processor
يتم استخراج أحدث إصدار من trace_processor وإعادة إنشائه.
build:protos
يعيد تجميع تعريفات proto.
إجراء الاختبارات
يحتوي Winscope على اختبارات الوحدات والاختبارات الشاملة. لتشغيلها، استخدِم npm run
<command>:
الأمر
الوصف
test:unit:ci
يُجري اختبارات الوحدة بتنسيق أقل تفصيلاً لعمليات الدمج المتواصل
أو خطافات ما قبل الإرسال.
test:unit:dev
يُجري اختبارات الوحدات بتنسيق أكثر تفصيلاً
للتطوير المحلي. يراقب هذا الوضع التغييرات
ويعيد تشغيل الاختبارات الصحيحة تلقائيًا.
test:e2e
لتشغيل الاختبارات الشاملة، مثل اختبارات
بروتوكول الأدوات المتعددة
test:presubmit:quiet
تنشئ جميع اختبارات الوحدات قبل الإرسال، وأدوات التدقيق، وتحليل
الرسومات البيانية بتنسيق أقل تفصيلاً لعمليات الدمج المتواصل أو خطاف
قبل الإرسال.
test:presubmit
تنشئ هذه السمة جميع وحدات الاختبار قبل الإرسال، وأدوات التدقيق، وتحليل الرسومات
بتنسيق أكثر تفصيلاً للتطوير
المحلي.
test:all
تنفيذ جميع الاختبارات (الوحدات والاختبارات الشاملة) وأدوات التدقيق والتحليل البياني
بتنسيق أكثر تفصيلاً للتطوير
المحلي
اختبارات شاملة
قبل تشغيل اختبارات شاملة، عليك بدء تشغيل الأداة عن بُعد وتثبيت الإصدار الصحيح من برنامج تشغيل Chrome. في مقتطف الرمز التالي، يثبّت الأمر
run test:e2e برنامج تشغيل Chrome تلقائيًا.
يسرد الجدول التالي الأوامر الضرورية وأوصافها. لتشغيلها، استخدِم npm run command:
الأمر
الوصف
start:remote_tool_mock
يبدأ عملية محاكاة الأداة عن بُعد لاختبار بروتوكول الأدوات المتعددة.
install:chromedriver
تثبِّت هذه الخطوة برنامج تشغيل Chrome اللازم لتنفيذ اختبارات شاملة.
تعديل عملية الربط @IntDef
@IntDef هي تعليق توضيحي يُستخدم في Android لحصر القيم المحتملة لعدد صحيح. يستخدم Winscope عملية ربط بين هذه التعليقات التوضيحية لعرض اسم القيمة بدلاً من العدد الصحيح.
لتعديل عملية ربط @IntDef، اتّبِع الخطوات التالية:
أنشئ :framework-minus-apex-intdefs لكي يتم تشغيل المعالجة المُسبَقة للتعليقات التوضيحية:
mp:framework-minus-apex-intdefs
انسخ ملف intDefMapping.json الذي تم إنشاؤه إلى مستودع الحِزم المُنشأة مسبقًا:
بالإضافة إلى عمليات الإنشاء والاختبار، تحتوي نصوص Winscope البرمجية على إمكانات أخرى، كما هو موضّح في الجدول. لتشغيلها، استخدِم npm run command:
الأمر
الوصف
format:check
للتحقّق من مشاكل تنسيق الرموز البرمجية باستخدام prettier
format:fix
يتحقّق من مشاكل تنسيق الرموز ويحلّها تلقائيًا باستخدام prettier.
eslint:check
للتحقّق من مشاكل تنسيق الرموز البرمجية باستخدام eslint
eslint:fix
يتحقّق من مشاكل تنسيق الرموز ويحلّها تلقائيًا باستخدام eslint.
tslint:check
للتحقّق من مشاكل تنسيق الرموز البرمجية باستخدام tslint
tslint:fix
يتحقّق من مشاكل تنسيق الرموز ويحلّها تلقائيًا باستخدام tslint.
deps_graph:check_cycles
تحلّل هذه السمة الرمز البرمجي بحثًا عن الاعتمادات الدورية.
تحديد المشاكل وحلّها
اتّبِع النصائح التالية لتحديد المشاكل وحلّها:
الخطأ ProtocolError: missing required '<FIELD>' أو TypeError: Cannot
read property '<PROP>' of null
يحدث ذلك عندما يتم إنشاء ملف التتبُّع باستخدام تعريف بروتوكول جديد،
يتضمّن حقولاً جديدة مطلوبة.
تأكَّد من فتح التتبُّع على إصدار Winscope الصحيح (الإصدار الرئيسي أو الإصدار S أو الإصدار R).
إذا أنشأت الحقل الجديد في ملف proto، عليك إعادة تجميع ملفات proto في Winscope باستخدام npm run build:protos.
بعض إصدارات التبعيات المثبَّتة غير صحيحة (يتعذّر إنشاء التطبيق)
إلغاء التغييرات التي أجريتها على package.json وpackage-lock.json إزالة
node_modules نفِّذ الأمر npm install مرة أخرى.
أضفتُ حقلًا جديدًا إلى أحد ملفات proto. كيف يمكنني عرضها؟
يستخدم Winscope تعريفات proto من وقت تجميعه، لذا لن تظهر الحقول الجديدة تلقائيًا. لعرض الحقول الجديدة، أعِد إنشاء ملفات protos باستخدام npm run build:protos.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-09-03 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-03 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["Winscope tracing is part of the Android framework. This page outlines the\nsteps required to download, build, and run the Winscope trace viewer locally.\n\nBuild Winscope locally\n\nFollow these steps to set up your PC to run the Winscope tracer:\n\n1. [Download the Android source](/docs/setup/build/building).\n2. Navigate to the Winscope folder:\n\n cd development/tools/winscope\n\n3. Install dependencies using:\n\n npm install\n\n To see a list of available commands, run: `npm run`\n4. Build all prod and test targets using:\n\n npm run build:prod\n\n5. Run Winscope using:\n\n npm run start\n\n| **Note:** You can also download and build Winscope to host on a standard web server to get a shareable link to the tool.\n\nBuild separate parts\n\nYou can build individual parts of Winscope separately using the following\ncommands:\n\n| Command | Description |\n|-------------------------|-----------------------------------------------------------------------------|\n| `build:trace_processor` | Checks out and rebuilds the latest version of Perfetto's `trace_processor`. |\n| `build:protos` | Recompiles the proto definitions. |\n\nRun tests **Tip:** Winscope doesn't build on Soong and can't be built by Tradefed, so it's recommended to have a local Git hook to the tests in your local environment.\n\nWinscope contains unit and end-to-end tests. To run them use `npm run\n\u003ccommand\u003e`:\n\n| Command | Description |\n|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|\n| `test:unit:ci` | Runs the unit tests in a less verbose format for CI or presubmit hook. |\n| `test:unit:dev` | Runs the unit tests in a more verbose format for local development. This mode watches for changes and automatically reruns the correct tests. |\n| `test:e2e` | Runs the end-to-end tests, such as those for the cross-tool protocol. |\n| `test:presubmit:quiet` | Builds all presubmit unit tests, linters, and graph analysis in a less verbose format for CI or presubmit hook. |\n| `test:presubmit` | Builds all presubmit unit tests, linters, and graph analysis in a more verbose format for local development. |\n| `test:all` | Runs all tests (unit and end-to-end), linters, and graph analysis in a more verbose format for local development. |\n\nEnd-to-end tests\n\nBefore running end-to-end tests, you must start the remote tool and install the\ncorrect version of the Chrome driver. In the following code snippet, the\n`run test:e2e` command automatically installs the Chrome driver. \n\n $ npm run start\n $ npm run start:remote_tool_mock\n $ npm run test:e2e\n\nThe following table lists the necessary commands and their descriptions. To run\nthem use `npm run `\u003cvar translate=\"no\"\u003ecommand\u003c/var\u003e:\n\n| Command | Description |\n|--------------------------|---------------------------------------------------------------|\n| `start:remote_tool_mock` | Starts the remote tool mock for testing cross tool protocol. |\n| `install:chromedriver` | Installs the Chrome driver necessary to run end-to-end tests. |\n\nUpdate @IntDef mapping\n\n`@IntDef` is an annotation used in Android to restrict the possible values of an\ninteger. Winscope uses a mapping of these annotations to display the name of the\nvalue instead of the integer.\n\nTo update the `@IntDef` mapping, do the following:\n\n1. Build `:framework-minus-apex-intdefs` for the annotation preprocessor to run:\n\n mp :framework-minus-apex-intdefs\n\n2. Copy the generated `intDefMapping.json` file to the prebuilts repository:\n\n $ 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) \u003e ./development/tools/winscope/src/common/intDefMapping.json\n\n3. Upload the changes in Winscope using `repo upload`.\n\nOther commands\n\nIn addition to build and tests, Winscope scripts contain other capabilities, as\nshown in the table. To run them use `npm run `\u003cvar translate=\"no\"\u003ecommand\u003c/var\u003e:\n\n| Command | Description |\n|---------------------------|----------------------------------------------------------------|\n| `format:check` | Checks for code formatting issues using `prettier`. |\n| `format:fix` | Checks and auto fixes code formatting issues using `prettier`. |\n| `eslint:check` | Checks for code formatting issues using `eslint`. |\n| `eslint:fix` | Checks and auto fixes code formatting issues using `eslint`. |\n| `tslint:check` | Checks for code formatting issues using `tslint`. |\n| `tslint:fix` | Checks and auto fixes code formatting issues using `tslint`. |\n| `deps_graph:check_cycles` | Analyzes the code for cyclical dependencies. |\n\nTroubleshoot\n\nUse the following tips for troubleshooting:\n\n- **Error `ProtocolError: missing required '\u003cFIELD\u003e'` or `TypeError: Cannot\n read property '\u003cPROP\u003e' of null`**\n\n - This occurs when the trace file was created with a new proto definition,\n containing new *required* fields.\n\n 1. Make sure you're opening the trace on the correct Winscope version (master, S, or R).\n 2. If you create the new field on the proto, recompile the protos in\n Winscope using `npm run build:protos`.\n\n | **Note:** You shouldn't need a new required field, because the protos should be backward compatible.\n- **Some installed dependency versions are wrong (build fails)**\n\n - Revert changes to `package.json` and `package-lock.json`. Remove `node_modules`. Run `npm install` again.\n- **I added a new field to one of the proto files. How do I display it?**\n\n - Winscope uses the proto definitions from when it was compiled, so new fields won't appear by default. To show new fields, rebuild the protos using `npm run build:protos`."]]
