เริ่มต้นใช้งาน

คู่มือนี้ครอบคลุมกระบวนการทีละขั้นตอนในการตั้งค่าการควบคุมเวอร์ชัน การรับและสร้างซอร์สโค้ดสำหรับพอร์ต การสร้างเอกสาร การรันการทดสอบ และคำอธิบายโครงสร้างไดเรกทอรีของโค้ดเบส MicroPython

การควบคุมซอร์สโค้ดด้วย git

MicroPython ถูกโฮสต์บน GitHub และใช้ Git สำหรับการควบคุมซอร์สโค้ด ขั้นตอนการทำงานคือการดึงและส่งโค้ดไปยังและจากที่เก็บข้อมูลหลัก ติดตั้ง Git เวอร์ชันที่เหมาะสมกับระบบปฏิบัติการของคุณเพื่อดำเนินการขั้นตอนที่เหลือ

Note

สำหรับข้อมูลอ้างอิงเกี่ยวกับคำแนะนำการติดตั้ง โปรดดูที่ คำแนะนำการติดตั้ง Git เรียนรู้คำสั่ง git เบื้องต้นใน Git Handbook นี้หรือแหล่งข้อมูลอื่น ๆ บนอินเทอร์เน็ต

Note

ไฟล์ .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. Clone ที่เก็บข้อมูลที่ fork ด้วยคำสั่งดังต่อไปนี้:

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

จากนั้น กำหนดค่าที่เก็บข้อมูลระยะไกล เพื่อสามารถร่วมมือในโปรเจกต์ MicroPython ได้

กำหนดค่า remote upstream:

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

เป็นเรื่องปกติที่จะกำหนดค่า upstream และ origin บนที่เก็บข้อมูลที่ fork เพื่อช่วยในการแชร์การเปลี่ยนแปลงโค้ด คุณสามารถเก็บการแมปของตัวเองได้ แต่แนะนำให้ 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)

ตอนนี้คุณควรมีสำเนาของซอร์สโค้ดแล้ว โดยค่าเริ่มต้นคุณกำลังชี้ไปยัง branch master เพื่อเตรียมพัฒนาต่อไป แนะนำให้ทำงานบน branch สำหรับการพัฒนา

$ git checkout -b dev-branch

คุณสามารถตั้งชื่อได้ตามต้องการ คุณจะต้องคอมไพล์ MicroPython ทุกครั้งที่เปลี่ยนไปยัง branch อื่น

คอมไพล์และสร้างโค้ด

เมื่อคอมไพล์ MicroPython คุณจะคอมไพล์ port เฉพาะ ซึ่งมักจะกำหนดเป้าหมายไปยัง board เฉพาะ เริ่มต้นด้วยการติดตั้งดีเพนเดนซีที่จำเป็น จากนั้นสร้าง MicroPython cross-compiler ก่อนที่คุณจะสามารถคอมไพล์และสร้างได้สำเร็จ สิ่งนี้ใช้เฉพาะเมื่อใช้ Linux ในการคอมไพล์ คำแนะนำสำหรับ Windows มีอยู่ในส่วนถัดไป

ดีเพนเดนซีที่จำเป็น

ติดตั้งดีเพนเดนซีที่จำเป็นสำหรับ Linux:

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

สำหรับพอร์ต stm32 จำเป็นต้องใช้ ARM cross-compiler:

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

ดูที่ ARM GCC toolchain สำหรับรายละเอียดล่าสุด

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 files ของแต่ละพอร์ต

การสร้าง MicroPython cross-compiler

พอร์ตเกือบทั้งหมดต้องการการสร้าง mpy-cross ก่อนเพื่อทำการ pre-compilation ของสคริปต์ Python ที่จะรวมอยู่ใน firmware ของพอร์ต:

$ cd mpy-cross
$ make

Note

หมายเหตุ mpy-cross ต้องสร้างสำหรับสถาปัตยกรรมของโฮสต์ ไม่ใช่สถาปัตยกรรมเป้าหมาย

หากสร้างสำเร็จ คุณควรเห็นข้อความที่คล้ายกับนี้:

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

Note

ใช้ make -C mpy-cross เพื่อสร้าง cross-compiler ในคำสั่งเดียวโดยไม่ต้องย้ายไปยังไดเรกทอรี mpy-cross มิฉะนั้นคุณจะต้องทำ cd .. สำหรับขั้นตอนถัดไป

การสร้าง Unix port ของ MicroPython

Unix port เป็นเวอร์ชัน MicroPython ที่ทำงานบน Linux, macOS และระบบปฏิบัติการที่คล้าย Unix อื่น ๆ มีประโยชน์มากสำหรับการพัฒนา MicroPython เพราะหลีกเลี่ยงการต้องนำโค้ดของคุณไปทดสอบบนอุปกรณ์จริง ในหลายแง่มุม มันทำงานคล้ายกับไบนารี python ของ CPython

หากต้องการสร้างสำหรับ Unix port ตรวจสอบให้แน่ใจว่าติดตั้งดีเพนเดนซีที่เกี่ยวกับ 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 port

Windows port รวมไฟล์โปรเจกต์ Visual Studio micropython.vcxproj ที่คุณสามารถใช้สร้าง micropython.exe ได้ สามารถเปิดใน Visual Studio หรือสร้างจาก command line โดยใช้ msbuild หรือจะสร้างโดยใช้ mingw ทั้งบน Windows ด้วย Cygwin หรือบน Linux ก็ได้ ดู เอกสาร windows port สำหรับข้อมูลเพิ่มเติม

การสร้าง STM32 port

เช่นเดียวกับ Unix port คุณต้องติดตั้งดีเพนเดนซีที่จำเป็นบางอย่างตามที่ระบุในส่วน ดีเพนเดนซีที่จำเป็น จากนั้นสร้าง:

$ cd ports/stm32
$ make submodules
$ make

โปรดดูที่ เอกสาร stm32 สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับการ flash เฟิร์มแวร์

Note

ดู ดีเพนเดนซีที่จำเป็น เพื่อให้แน่ใจว่าติดตั้งดีเพนเดนซีทั้งหมดสำหรับพอร์ตนี้แล้ว จำเป็นต้องใช้ cross-compiler arm-none-eabi-gcc ควรอยู่ใน $PATH หรือระบุด้วยตนเองผ่าน CROSS_COMPILE โดยการตั้งค่าตัวแปรสภาพแวดล้อมหรือใน make command line arguments

คุณยังสามารถระบุว่าจะใช้บอร์ดใด:

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

ดู ports/stm32/boards สำหรับบอร์ดที่พร้อมใช้งาน เช่น "OPENMV4" หรือ "OPENMV4P"

การสร้างเอกสาร

เอกสาร MicroPython สร้างขึ้นโดยใช้ Sphinx หากคุณติดตั้ง Python ไปแล้ว ให้ติดตั้ง Sphinx ด้วย pip แนะนำให้ใช้ virtual environment:

$ 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 port ใช้:

$ cd ports/unix
$ make test

หากต้องการรันการทดสอบบางส่วนบนบอร์ด/อุปกรณ์ที่เชื่อมต่อผ่าน USB ใช้:

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

ดูเพิ่มเติมที่ การเขียนการทดสอบ

เป้าหมาย make เพิ่มเติมสำหรับนักพัฒนา

ในพอร์ตที่ใช้ make ทั้งหมด มีเป้าหมายสำหรับพิมพ์ขนาดของไฟล์อ็อบเจกต์เฉพาะ เมื่อการเปลี่ยนแปลงจำกัดอยู่ที่ไฟล์เดียว สิ่งนี้มีประโยชน์เมื่อทดสอบรูปแบบต่าง ๆ เพื่อหาทางเลือกที่เล็กกว่า

ตัวอย่างเช่น หากต้องการพิมพ์ขนาดของ objstr.o ในไดเรกทอรี py/ เมื่อสร้าง unix standard build:

$ 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 สำหรับ continuous integration เพื่อลดการพึ่งพาระบบ CI เฉพาะใด ขั้นตอนการสร้างจริงสำหรับ Unix-based builds อยู่ในไฟล์ tools/ci.sh ซึ่งยังสามารถใช้เป็นสคริปต์บนเดสก์ท็อปของนักพัฒนาได้ โดยมีข้อควรระวัง:

  • สำหรับขั้นตอนส่วนใหญ่ ระบบ Ubuntu/Debian ที่คล้ายกับที่ใช้ระหว่าง CI จะถูกสันนิษฐานว่ามีอยู่

  • ขั้นตอนเฉพาะบางอย่างสันนิษฐานเวอร์ชัน Ubuntu เฉพาะ

  • ขั้นตอนการตั้งค่าอาจเรียกใช้ตัวจัดการแพ็คเกจระบบเพื่อติดตั้งแพ็คเกจ ดาวน์โหลดและติดตั้งซอฟต์แวร์จากอินเทอร์เน็ต เป็นต้น

หากต้องการข้อความช่วยเหลือรวมถึงรายการคำสั่ง ให้รัน:

$ tools/ci.sh --help

ตัวอย่างเช่น คุณสามารถสร้างและทดสอบ unix minimal port ด้วย:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

หากคุณใช้ bash shell คุณสามารถเพิ่มคำสั่ง ci พร้อม tab completion:

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

สำหรับ zsh shell ให้แทนที่ --bash-completion ด้วย --zsh-completion สำหรับ fish shell ให้แทนที่ --bash-completion ด้วย --fish-completion

จากนั้นพิมพ์:

$ ci unix_cov<tab>

ซึ่งจะเติม ci step name เป็น unix_coverage_ การกด tab ครั้งที่สองจะแสดงรายการ step ที่ตรงกัน:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

โครงสร้างโฟลเดอร์

มีไดเรกทอรีสองสามรายการที่ควรสังเกตในแง่ของตำแหน่งรายละเอียดการดำเนินงานบางอย่าง ต่อไปนี้คือการแยกรายละเอียดของโฟลเดอร์ระดับบนสุดในซอร์สโค้ด

py

มีการดำเนินการ compiler, runtime และไลบรารีหลัก

mpy-cross

มี MicroPython cross-compiler ซึ่ง pre-compiles สคริปต์ Python เป็น bytecode

ports

โค้ดสำหรับ MicroPython ทุกเวอร์ชันสำหรับพอร์ตที่รองรับ

lib

ไลบรารี C ระดับต่ำที่ใช้โดยพอร์ตต่าง ๆ ซึ่งส่วนใหญ่เป็นไลบรารีของบุคคลที่สาม

drivers

มีไดรเวอร์สำหรับฮาร์ดแวร์เฉพาะและตั้งใจให้ทำงานข้ามพอร์ตหลายรายการ

extmod

มีการดำเนินการ C ของโมดูลที่ไม่ใช่หลักเพิ่มเติม

docs

มีเอกสารมาตรฐานที่พบที่ https://docs.micropython.org/

tests

การดำเนินการของชุดทดสอบ

tools

มีสคริปต์ที่ใช้โดยกระบวนการ build และ CI รวมถึงเครื่องมือผู้ใช้เช่น mpremote

examples

ตัวอย่างโค้ดสำหรับการสร้าง MicroPython เป็นไลบรารีรวมถึงโมดูลเนทีฟ