البدء

يغطي هذا الدليل عملية خطوة بخطوة لإعداد التحكم في الإصدارات، والحصول على نسخة من الشيفرة المصدرية لأحد المنافذ وبنائها، وبناء التوثيق، وتشغيل الاختبارات، إضافة إلى وصف لبنية الأدلة في قاعدة شيفرة MicroPython.

التحكم في المصدر باستخدام git

تُستضاف MicroPython على GitHub وتستخدم Git للتحكم في المصدر. تتمثل سير العمل في سحب الشيفرة ودفعها من وإلى المستودع الرئيسي. ثبّت الإصدار المناسب من Git لنظام تشغيلك لمتابعة بقية الخطوات.

ملاحظة

للحصول على مرجع لتعليمات التثبيت، يُرجى الرجوع إلى تعليمات تثبيت Git. تعرّف على أوامر git الأساسية في دليل Git أو أي مصادر أخرى على الإنترنت.

ملاحظة

يتضمن المشروع ملف ‎.git-blame-ignore-revs الذي يتجنب اكتظاظ خرج git blame بإيداعات (commits) تخص تنسيق الشيفرة فقط دون أي تغييرات وظيفية. راجع توثيق git blame لمعرفة كيفية استخدام ذلك.

الحصول على الشيفرة

يُنصح بأن تحتفظ بنسخة متفرعة (fork) من مستودع MicroPython لأغراض التطوير الخاصة بك. تتضمن عملية الحصول على الشيفرة المصدرية ما يلي:

  1. أنشئ نسخة متفرعة من المستودع https://github.com/micropython/micropython

  2. سيكون لديك الآن نسخة متفرعة على <https://github.com/<your-user-name>/micropython>.

  3. استنسخ المستودع المتفرّع باستخدام الأمر التالي:

$ git clone https://github.com/<your-user-name>/micropython

ثم هيّئ المستودعات البعيدة لتتمكن من التعاون في مشروع MicroPython.

تهيئة upstream البعيد:

$ cd micropython
$ git remote add upstream https://github.com/micropython/micropython

من الشائع تهيئة upstream و origin على مستودع متفرّع للمساعدة في مشاركة تغييرات الشيفرة. يمكنك الاحتفاظ بربطك الخاص ولكن يُنصح بأن يشير origin إلى نسختك المتفرّعة و upstream إلى مستودع MicroPython الرئيسي.

بعد التهيئة المذكورة أعلاه، ينبغي أن يكون إعدادك مشابهًا لهذا:

$ git remote -v
origin       https://github.com/<your-user-name>/micropython (fetch)
origin       https://github.com/<your-user-name>/micropython (push)
upstream     https://github.com/micropython/micropython (fetch)
upstream     https://github.com/micropython/micropython (push)

ينبغي أن يكون لديك الآن نسخة من الشيفرة المصدرية. افتراضيًا، تشير إلى فرع master. للاستعداد لمزيد من التطوير، يُنصح بالعمل على فرع تطوير.

$ git checkout -b dev-branch

يمكنك إعطاؤه أي اسم. سيتعين عليك تصريف MicroPython كلما انتقلت إلى فرع مختلف.

تصريف الشيفرة وبناؤها

عند تصريف MicroPython، فإنك تصرّف منفذًا (port) محددًا، يستهدف عادةً لوحة (board) محددة. ابدأ بتثبيت التبعيات المطلوبة. ثم ابنِ المصرّف المتقاطع (cross-compiler) الخاص بـ MicroPython قبل أن تتمكن من التصريف والبناء بنجاح. ينطبق هذا تحديدًا عند استخدام Linux للتصريف. تُقدَّم تعليمات Windows في قسم لاحق.

التبعيات المطلوبة

ثبّت التبعيات المطلوبة لنظام Linux:

$ sudo apt-get install build-essential libffi-dev git pkg-config

بالنسبة لمنفذ stm32، يلزم المصرّف المتقاطع لـ ARM:

$ sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi

راجع سلسلة أدوات ARM GCC للحصول على أحدث التفاصيل.

يلزم أيضًا Python 3. تحقق من توفر Python على نظامك:

$ python3
Python 3.5.0 (default, Jul 17 2020, 14:04:10)
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

لجميع المنافذ المدعومة متطلبات تبعيات مختلفة، راجع ملفات readme الخاصة بها.

بناء المصرّف المتقاطع لـ MicroPython

تتطلب جميع المنافذ تقريبًا بناء mpy-cross أولًا لإجراء التصريف المسبق لشيفرة Python التي ستُضمَّن في البرنامج الثابت للمنفذ:

$ cd mpy-cross
$ make

ملاحظة

لاحظ أنه يجب بناء mpy-cross لمعمارية المضيف وليس لمعمارية الهدف.

إذا بُني بنجاح، فينبغي أن ترى رسالة مشابهة لهذه:

LINK mpy-cross
   text          data    bss     dec     hex filename
 279328          776     880  280984   44998 mpy-cross

ملاحظة

استخدم make -C mpy-cross لبناء المصرّف المتقاطع في تعليمة واحدة دون الانتقال إلى دليل mpy-cross، وإلا فسيتعين عليك تنفيذ cd .. للخطوات التالية.

بناء منفذ Unix لـ MicroPython

منفذ Unix هو إصدار من MicroPython يعمل على Linux وmacOS وأنظمة التشغيل الأخرى الشبيهة بـ Unix. وهو مفيد للغاية لتطوير MicroPython لأنه يتجنب الحاجة إلى نشر شيفرتك على جهاز لاختبارها. وهو يعمل من نواحٍ عديدة بطريقة تشبه إلى حد كبير الملف الثنائي python في CPython.

للبناء لمنفذ Unix، تأكد من تثبيت جميع التبعيات المتعلقة بـ Linux كما هو مفصّل في قسم التبعيات المطلوبة. راجع التبعيات المطلوبة للتأكد من تثبيت جميع التبعيات لهذا المنفذ. وتأكد أيضًا من وجود بيئة عمل صالحة لـ gcc و GNU make. استُخدمت Ubuntu 20.04 في المثال أدناه ولكن من المفترض أن تعمل أنظمة unix الأخرى بتعديل بسيط:

$ gcc --version
gcc (Ubuntu 9.3.0-10ubuntu2) 9.3.0
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

ثم ابنِ:

$ cd ports/unix
$ make submodules
$ make

إذا بُنيت MicroPython بشكل صحيح، فينبغي أن ترى ما يلي:

LINK micropython
   text         data     bss     dec     hex filename
 412033         5680    2496  420209   66971 micropython

الآن شغّله:

$ ./micropython
MicroPython v1.13-38-gc67012d-dirty on 2020-09-13; linux version
Use Ctrl-D to exit, Ctrl-E for paste mode
>>> print("hello world")
hello world
>>>

بناء منفذ Windows

يتضمن منفذ Windows ملف مشروع Visual Studio باسم micropython.vcxproj يمكنك استخدامه لبناء micropython.exe. يمكن فتحه في Visual Studio أو بناؤه من سطر الأوامر باستخدام msbuild. بدلًا من ذلك، يمكن بناؤه باستخدام mingw، إما في Windows مع Cygwin، أو على Linux. راجع توثيق منفذ windows لمزيد من المعلومات.

بناء منفذ STM32

مثل منفذ Unix، تحتاج إلى تثبيت بعض التبعيات المطلوبة كما هو مفصّل في قسم التبعيات المطلوبة، ثم ابنِ:

$ cd ports/stm32
$ make submodules
$ make

يُرجى الرجوع إلى توثيق stm32 لمزيد من التفاصيل حول وميض البرنامج الثابت.

ملاحظة

راجع التبعيات المطلوبة للتأكد من تثبيت جميع التبعيات لهذا المنفذ. يلزم المصرّف المتقاطع. ينبغي أيضًا أن يكون arm-none-eabi-gcc موجودًا في ‎$PATH أو محددًا يدويًا عبر CROSS_COMPILE، إما بتعيين متغير البيئة أو في وسائط سطر أوامر make.

يمكنك أيضًا تحديد اللوحة المراد استخدامها:

$ cd ports/stm32
$ make BOARD=<board> submodules
$ make BOARD=<board>

راجع ports/stm32/boards للاطلاع على اللوحات المتوفرة. مثل "OPENMV4" أو "OPENMV4P".

بناء التوثيق

يُنشَأ توثيق MicroPython باستخدام Sphinx. إذا كنت قد ثبّت Python بالفعل، فثبّت Sphinx باستخدام pip. يُنصح باستخدام بيئة افتراضية:

$ python3 -m venv env
$ source env/bin/activate
$ pip install -r docs/requirements.txt

انتقل إلى دليل docs:

$ cd docs

ابنِ التوثيق:

$ make html

افتح docs/build/html/index.html في متصفحك لعرض التوثيق محليًا. راجع التوثيق حول استيراد توثيقك لاستخدام Read the Docs.

تشغيل الاختبارات

لتشغيل جميع الاختبارات في مجموعة الاختبارات على منفذ Unix، استخدم:

$ cd ports/unix
$ make test

لتشغيل مجموعة مختارة من الاختبارات على لوحة/جهاز متصل عبر USB، استخدم:

$ cd tests
$ ./run-tests.py -t /dev/ttyACM0

راجع أيضًا كتابة الاختبارات.

أهداف make إضافية للمطورين

في جميع المنافذ المعتمدة على make، يوجد هدف لطباعة حجم ملف كائن محدد. عندما يقتصر التغيير على ملف واحد، يكون هذا مفيدًا عند اختبار التنويعات لإيجاد بدائل أصغر حجمًا.

على سبيل المثال، لطباعة حجم objstr.o في دليل py/ عند إنشاء بناء unix قياسي:

$ make build-standard/py/objstr.sz

وبالمثل، يوجد هدف لحفظ النسخة المعالَجة مسبقًا من ملف:

$ make build-standard/py/objstr.pp

في ports/unix توجد أهداف إضافية متعلقة بتشغيل الاختبارات:

$ make test//int       # Run all tests matching the pattern "int"
$ make test/ports/unix # Run all tests in ports/unix
$ make test-failures   # Re-run only the failed tests
$ make print-failures  # print the differences for failed tests
$ make clean-failures  # delete the .exp and .out files from failed tests

استخدام ci.sh محليًا

تستخدم MicroPython آلية GitHub Actions للتكامل المستمر. لتقليل الاعتماد على أي نظام تكامل مستمر محدد، توجد خطوات البناء الفعلية للبنى المعتمدة على Unix في الملف tools/ci.sh. يمكن استخدام هذا أيضًا كبرنامج نصي على أجهزة المطورين المكتبية، مع بعض التحفظات:

  • بالنسبة لمعظم الخطوات، يُفترض وجود نظام Ubuntu/Debian مشابه للنظام المستخدم أثناء التكامل المستمر.

  • تفترض بعض الخطوات المحددة إصدارات Ubuntu محددة.

  • قد تستدعي خطوات الإعداد مدير حزم النظام لتثبيت الحزم، وتنزيل وتثبيت البرامج من الإنترنت، وما إلى ذلك.

للحصول على رسالة استخدام تتضمن قائمة الأوامر، شغّل:

$ tools/ci.sh --help

كمثال، يمكنك بناء واختبار منفذ unix الأدنى باستخدام:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

إذا كنت تستخدم صدفة bash، يمكنك إضافة أمر ci مع إكمال الجدولة (tab):

$ eval $(tools/ci.sh --bash-completion)

بالنسبة لصدفة zsh، استبدل --bash-completion بـ --zsh-completion. وبالنسبة لصدفة fish، استبدل --bash-completion بـ --fish-completion.

ثم، عند كتابة:

$ ci unix_cov<tab>

سيؤدي هذا إلى إكمال اسم خطوة ci إلى unix_coverage_. وسيؤدي الضغط على tab مرة ثانية إلى عرض قائمة الخطوات المطابقة:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

بنية المجلدات

هناك عدد من الأدلة الجديرة بالملاحظة من حيث موضع تفاصيل تنفيذ معينة. وفيما يلي تفصيل للمجلدات عالية المستوى في الشيفرة المصدرية.

py

يحتوي على المصرّف ووقت التشغيل وتنفيذ المكتبة الأساسية.

mpy-cross

يحتوي على المصرّف المتقاطع لـ MicroPython الذي يصرّف برامج Python النصية مسبقًا إلى شيفرة بايت (bytecode).

ports

شيفرة جميع إصدارات MicroPython للمنافذ المدعومة.

lib

مكتبات C منخفضة المستوى يستخدمها أي منفذ، وهي في الغالب مكتبات من أطراف ثالثة.

drivers

يحتوي على مشغّلات لعتاد محدد ومصممة للعمل عبر منافذ متعددة.

extmod

يحتوي على تنفيذ بلغة C لمزيد من الوحدات غير الأساسية.

docs

يحتوي على التوثيق القياسي الموجود على https://docs.micropython.org/.

tests

تنفيذ لمجموعة الاختبارات.

tools

يحتوي على البرامج النصية المستخدمة في عملية البناء والتكامل المستمر، إضافة إلى أدوات المستخدم مثل mpremote.

examples

شيفرة مثال لبناء MicroPython كمكتبة إضافة إلى الوحدات الأصلية (native modules).