תחילת העבודה

מדריך זה מכסה תהליך שלב-אחר-שלב של הגדרת ניהול גרסאות, השגה ובנייה של עותק מקוד המקור עבור port, בניית התיעוד, הרצת בדיקות, ותיאור של מבנה הספריות של בסיס הקוד של MicroPython.

ניהול גרסאות עם git

MicroPython מתארחת ב-GitHub ומשתמשת ב-Git לניהול גרסאות. תהליך העבודה הוא כזה שבו הקוד נמשך ונדחף אל ומן המאגר הראשי. התקינו את הגרסה המתאימה של Git עבור מערכת ההפעלה שלכם כדי להמשיך בשאר השלבים.

הערה

להפניה אל הוראות ההתקנה, אנא עיינו ב-הוראות התקנת Git. למדו על פקודות git הבסיסיות ב-מדריך Git זה או בכל מקור אחר באינטרנט.

הערה

כלול קובץ ‎.git-blame-ignore-revs‎ אשר מונע מהפלט של git blame להיות עמוס בקומיטים שנועדו רק לעיצוב הקוד אך אין בהם שינויים פונקציונליים. ראו את תיעוד git blame לגבי אופן השימוש בכך.

השגת הקוד

מומלץ שתחזיקו fork של מאגר MicroPython למטרות הפיתוח שלכם. תהליך השגת קוד המקור כולל את הצעדים הבאים:

  1. בצעו fork למאגר https://github.com/micropython/micropython

  2. כעת יהיה לכם fork בכתובת <https://github.com/<your-user-name>/micropython>.

  3. שכפלו את המאגר המפוצל (forked) באמצעות הפקודה הבאה:

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

לאחר מכן, הגדירו את המאגרים המרוחקים כדי שתוכלו לשתף פעולה בפרויקט MicroPython.

הגדירו את upstream המרוחק:

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

נהוג להגדיר upstream ו-origin במאגר מפוצל (forked) כדי לסייע בשיתוף שינויי קוד. תוכלו לתחזק מיפוי משלכם אך מומלץ ש-origin ימופה אל ה-fork שלכם ו-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

עבור port ה-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.
>>>

לכל ה-ports הנתמכים יש דרישות תלות שונות, ראו את קובצי ה-readme המתאימים שלהם.

בניית מהדר ההצלבה של MicroPython

כמעט כל ה-ports דורשים תחילה לבנות את mpy-cross כדי לבצע הידור מוקדם של קוד Python שייכלל בקושחת ה-port:

$ 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 .. עבור השלבים הבאים.

בניית ה-port של Unix עבור MicroPython

ה-port של Unix הוא גרסה של MicroPython הרצה על Linux, macOS ומערכות הפעלה אחרות דמויות Unix. הוא שימושי ביותר לפיתוח MicroPython מאחר שהוא חוסך את הצורך לפרוס את הקוד שלכם להתקן כדי לבדוק אותו. במובנים רבים, הוא עובד בדומה מאוד לקובץ הבינארי python של CPython.

כדי לבנות עבור ה-port של Unix, ודאו שכל התלויות הקשורות ל-Linux מותקנות כמפורט בסעיף התלויות הנדרשות. ראו את תלויות נדרשות כדי לוודא שכל התלויות מותקנות עבור port זה. כמו כן, ודאו שיש לכם סביבת עבודה תקינה עבור 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
>>>

בניית ה-port של Windows

ה-port של Windows כולל קובץ פרויקט של Visual Studio בשם micropython.vcxproj שבו תוכלו להשתמש כדי לבנות את micropython.exe. ניתן לפתוח אותו ב-Visual Studio או לבנות אותו משורת הפקודה באמצעות msbuild. לחלופין, ניתן לבנות אותו באמצעות mingw, בין אם ב-Windows עם Cygwin, או ב-Linux. ראו תיעוד port של Windows למידע נוסף.

בניית ה-port של STM32

בדומה ל-port של Unix, עליכם להתקין כמה תלויות נדרשות כמפורט בסעיף תלויות נדרשות, ואז לבנות:

$ cd ports/stm32
$ make submodules
$ make

אנא עיינו ב-תיעוד stm32 לפרטים נוספים על צריבת הקושחה.

הערה

ראו את תלויות נדרשות כדי לוודא שכל התלויות מותקנות עבור port זה. נדרש מהדר ההצלבה. arm-none-eabi-gcc אמור להיות גם הוא ב-$PATH או מצוין ידנית באמצעות CROSS_COMPILE, בין אם על ידי הגדרת משתנה הסביבה או בארגומנטים של שורת הפקודה של make.

תוכלו גם לציין באיזה board להשתמש:

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

ראו ports/stm32/boards עבור ה-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.

הרצת הבדיקות

כדי להריץ את כל הבדיקות בערכת הבדיקות על ה-port של Unix השתמשו ב:

$ cd ports/unix
$ make test

כדי להריץ מבחר בדיקות על board/התקן המחובר דרך USB השתמשו ב:

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

ראו גם כתיבת בדיקות.

יעדי make נוספים למפתחים

בכל ה-ports המבוססים על make, קיים יעד להדפסת הגודל של קובץ אובייקט מסוים. כאשר שינוי מוגבל לקובץ יחיד, זה שימושי בעת בדיקת וריאציות כדי למצוא חלופות קטנות יותר.

לדוגמה, כדי להדפיס את הגודל של objstr.o בספריית py/ בעת ביצוע בנייה סטנדרטית של unix:

$ make build-standard/py/objstr.sz

באופן דומה, קיים יעד לשמירת הגרסה המעובדת מראש (preprocessed) של קובץ:

$ 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 לאינטגרציה רציפה. כדי להפחית את התלות במערכת CI ספציפית כלשהי, שלבי הבנייה בפועל עבור בניות מבוססות-Unix נמצאים בקובץ tools/ci.sh. ניתן להשתמש בו גם כסקריפט על שולחנות העבודה של מפתחים, עם הסתייגויות:

  • עבור רוב השלבים, מונחת מערכת Ubuntu/Debian הדומה לזו שבה נעשה שימוש במהלך ה-CI.

  • שלבים ספציפיים מסוימים מניחים גרסאות Ubuntu ספציפיות.

  • שלבי ההתקנה עשויים להפעיל את מנהל החבילות של המערכת כדי להתקין חבילות, להוריד ולהתקין תוכנה מהאינטרנט וכדומה.

כדי לקבל הודעת שימוש הכוללת את רשימת הפקודות, הריצו:

$ tools/ci.sh --help

כדוגמה, תוכלו לבנות ולבדוק את ה-port המינימלי של 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 עבור ה-ports הנתמכים.

lib

ספריות C ברמה נמוכה הנמצאות בשימוש על ידי כל port, ברובן ספריות צד שלישי.

drivers

כולל מנהלי התקנים עבור חומרה ספציפית ומיועד לעבוד על פני מספר ports.

extmod

מכיל מימוש C של מודולים נוספים שאינם ליבה.

docs

כולל את התיעוד הסטנדרטי הנמצא בכתובת https://docs.micropython.org/.

tests

מימוש של ערכת הבדיקות.

tools

מכיל סקריפטים הנמצאים בשימוש על ידי תהליך הבנייה וה-CI, וכן כלי משתמש כגון mpremote.

examples

קוד לדוגמה לבניית MicroPython כספרייה וכן מודולים נייטיביים.