OpenMV MicroPython
Bắt Đầu¶
Hướng dẫn này bao gồm quy trình từng bước để thiết lập kiểm soát phiên bản, lấy và xây dựng bản sao mã nguồn cho một port, xây dựng tài liệu, chạy các bài kiểm tra, và mô tả cấu trúc thư mục của cơ sở mã MicroPython.
Kiểm soát phiên bản với git¶
MicroPython được lưu trữ trên GitHub và sử dụng Git để kiểm soát phiên bản. Quy trình làm việc là kéo và đẩy mã từ kho lưu trữ chính. Cài đặt phiên bản Git tương ứng cho hệ điều hành của bạn để thực hiện theo các bước tiếp theo.
Ghi chú
Để tham khảo hướng dẫn cài đặt, vui lòng xem hướng dẫn cài đặt Git. Tìm hiểu các lệnh git cơ bản trong Git Handbook này hoặc các nguồn khác trên internet.
Ghi chú
Một tệp .git-blame-ignore-revs được bao gồm để tránh đầu ra của git blame bị lộn xộn bởi các commit chỉ dùng để định dạng mã nhưng không có thay đổi chức năng. Xem tài liệu git blame về cách sử dụng tính năng này.
Lấy mã nguồn¶
Khuyến nghị bạn duy trì một fork của kho lưu trữ MicroPython cho mục đích phát triển của mình. Quy trình lấy mã nguồn bao gồm các bước sau:
Fork kho lưu trữ https://github.com/micropython/micropython
Bây giờ bạn sẽ có một fork tại <https://github.com/<your-user-name>/micropython>.
Clone kho lưu trữ đã fork bằng lệnh sau:
$ git clone https://github.com/<your-user-name>/micropython
Sau đó, cấu hình các kho lưu trữ từ xa để có thể cộng tác trong dự án MicroPython.
Cấu hình remote upstream:
$ cd micropython
$ git remote add upstream https://github.com/micropython/micropython
Thông thường người ta cấu hình upstream và origin trên kho lưu trữ đã fork để hỗ trợ chia sẻ các thay đổi mã. Bạn có thể duy trì ánh xạ của riêng mình nhưng khuyến nghị rằng origin ánh xạ đến fork của bạn và upstream đến kho lưu trữ MicroPython chính.
Sau cấu hình trên, thiết lập của bạn sẽ tương tự như sau:
$ 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)
Bây giờ bạn sẽ có một bản sao của mã nguồn. Theo mặc định, bạn đang trỏ đến nhánh master. Để chuẩn bị cho việc phát triển tiếp theo, khuyến nghị làm việc trên một nhánh phát triển.
$ git checkout -b dev-branch
Bạn có thể đặt tên bất kỳ. Bạn sẽ phải biên dịch MicroPython mỗi khi chuyển sang một nhánh khác.
Biên dịch và xây dựng mã¶
Khi biên dịch MicroPython, bạn biên dịch một port cụ thể, thường nhắm đến một board cụ thể. Bắt đầu bằng cách cài đặt các phụ thuộc cần thiết. Sau đó xây dựng trình biên dịch chéo MicroPython trước khi có thể biên dịch và xây dựng thành công. Điều này áp dụng cụ thể khi sử dụng Linux để biên dịch. Hướng dẫn cho Windows được cung cấp trong phần sau.
Các phụ thuộc cần thiết¶
Cài đặt các phụ thuộc cần thiết cho Linux:
$ sudo apt-get install build-essential libffi-dev git pkg-config
Đối với port stm32, cần có trình biên dịch chéo ARM:
$ sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi
Xem ARM GCC toolchain để biết chi tiết mới nhất.
Python 3 cũng là bắt buộc. Kiểm tra xem bạn có Python trên hệ thống không:
$ 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.
>>>
Tất cả các port được hỗ trợ có yêu cầu phụ thuộc khác nhau, xem các tệp readme tương ứng của chúng.
Xây dựng trình biên dịch chéo MicroPython¶
Hầu hết tất cả các port đều yêu cầu xây dựng mpy-cross trước để thực hiện tiền biên dịch mã Python sẽ được bao gồm trong firmware của port:
$ cd mpy-cross
$ make
Ghi chú
Lưu ý rằng, mpy-cross phải được xây dựng cho kiến trúc máy chủ, không phải kiến trúc đích.
Nếu xây dựng thành công, bạn sẽ thấy thông báo tương tự như sau:
LINK mpy-cross
text data bss dec hex filename
279328 776 880 280984 44998 mpy-cross
Ghi chú
Sử dụng make -C mpy-cross để xây dựng trình biên dịch chéo trong một câu lệnh mà không cần di chuyển đến thư mục mpy-cross, nếu không bạn sẽ cần thực hiện cd .. cho các bước tiếp theo.
Xây dựng port Unix của MicroPython¶
Port Unix là phiên bản MicroPython chạy trên Linux, macOS, và các hệ điều hành giống Unix khác. Nó cực kỳ hữu ích cho việc phát triển MicroPython vì tránh phải triển khai mã của bạn lên thiết bị để kiểm tra. Theo nhiều cách, nó hoạt động rất giống với nhị phân python của CPython.
Để xây dựng cho port Unix, hãy đảm bảo tất cả các phụ thuộc liên quan đến Linux được cài đặt như chi tiết trong phần phụ thuộc cần thiết. Xem Các phụ thuộc cần thiết để đảm bảo rằng tất cả các phụ thuộc được cài đặt cho port này. Ngoài ra, hãy đảm bảo bạn có môi trường làm việc cho gcc và GNU make. Ubuntu 20.04 đã được sử dụng cho ví dụ dưới đây nhưng các hệ điều hành Unix khác cũng hoạt động với ít thay đổi:
$ 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.
sau đó xây dựng:
$ cd ports/unix
$ make submodules
$ make
Nếu MicroPython được xây dựng đúng cách, bạn sẽ thấy như sau:
LINK micropython
text data bss dec hex filename
412033 5680 2496 420209 66971 micropython
Bây giờ hãy chạy nó:
$ ./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
>>>
Xây dựng port Windows¶
Port Windows bao gồm tệp dự án Visual Studio micropython.vcxproj mà bạn có thể dùng để xây dựng micropython.exe. Nó có thể được mở trong Visual Studio hoặc xây dựng từ dòng lệnh sử dụng msbuild. Ngoài ra, nó có thể được xây dựng sử dụng mingw, trong Windows với Cygwin hoặc trên Linux. Xem tài liệu port windows để biết thêm thông tin.
Xây dựng port STM32¶
Giống như port Unix, bạn cần cài đặt một số phụ thuộc cần thiết như chi tiết trong phần Các phụ thuộc cần thiết, sau đó xây dựng:
$ cd ports/stm32
$ make submodules
$ make
Vui lòng tham khảo tài liệu stm32 để biết thêm chi tiết về việc nạp firmware.
Ghi chú
Xem Các phụ thuộc cần thiết để đảm bảo rằng tất cả các phụ thuộc được cài đặt cho port này. Trình biên dịch chéo là cần thiết. arm-none-eabi-gcc cũng nên có trong $PATH hoặc được chỉ định thủ công qua CROSS_COMPILE, bằng cách đặt biến môi trường hoặc trong đối số dòng lệnh make.
Bạn cũng có thể chỉ định board nào sẽ sử dụng:
$ cd ports/stm32
$ make BOARD=<board> submodules
$ make BOARD=<board>
Xem ports/stm32/boards để biết các board có sẵn. Ví dụ: "OPENMV4" hoặc "OPENMV4P".
Xây dựng tài liệu¶
Tài liệu MicroPython được tạo bằng Sphinx. Nếu bạn đã cài đặt Python, thì hãy cài đặt Sphinx bằng pip. Khuyến nghị bạn sử dụng môi trường ảo:
$ python3 -m venv env
$ source env/bin/activate
$ pip install -r docs/requirements.txt
Điều hướng đến thư mục docs:
$ cd docs
Xây dựng tài liệu:
$ make html
Mở docs/build/html/index.html trong trình duyệt của bạn để xem tài liệu cục bộ. Tham khảo tài liệu về importing your documentation để sử dụng Read the Docs.
Chạy các bài kiểm tra¶
Để chạy tất cả các bài kiểm tra trong bộ kiểm tra trên port Unix, sử dụng:
$ cd ports/unix
$ make test
Để chạy một tập hợp các bài kiểm tra trên board/thiết bị được kết nối qua USB, sử dụng:
$ cd tests
$ ./run-tests.py -t /dev/ttyACM0
Xem thêm Viết kiểm thử.
Các mục tiêu make bổ sung cho nhà phát triển¶
Trong tất cả các port dựa trên make, có một mục tiêu để in kích thước của tệp đối tượng cụ thể. Khi một thay đổi giới hạn trong một tệp đơn, điều này hữu ích khi kiểm tra các biến thể để tìm các lựa chọn thay thế nhỏ hơn.
Ví dụ: để in kích thước của objstr.o trong thư mục py/ khi thực hiện một bản dựng unix tiêu chuẩn:
$ make build-standard/py/objstr.sz
Tương tự, có một mục tiêu để lưu phiên bản đã được tiền xử lý của một tệp:
$ make build-standard/py/objstr.pp
Trong ports/unix có các mục tiêu bổ sung liên quan đến việc chạy các bài kiểm tra:
$ 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
Sử dụng ci.sh cục bộ¶
MicroPython sử dụng GitHub Actions cho tích hợp liên tục. Để giảm sự phụ thuộc vào bất kỳ hệ thống CI cụ thể nào, các bước xây dựng thực tế cho các bản dựng dựa trên Unix nằm trong tệp tools/ci.sh. Tệp này cũng có thể được sử dụng như một tập lệnh trên máy tính của nhà phát triển, với một số lưu ý:
Đối với hầu hết các bước, hệ thống Ubuntu/Debian tương tự như hệ thống được sử dụng trong CI được giả định.
Một số bước cụ thể giả định các phiên bản Ubuntu cụ thể.
Các bước thiết lập có thể gọi trình quản lý gói hệ thống để cài đặt các gói, tải xuống và cài đặt phần mềm từ internet, v.v.
Để nhận thông báo sử dụng bao gồm danh sách các lệnh, hãy chạy:
$ tools/ci.sh --help
Ví dụ: bạn có thể xây dựng và kiểm tra port unix minimal với:
$ tools/ci.sh unix_minimal_build unix_minimal_run_tests
Nếu bạn sử dụng shell bash, bạn có thể thêm lệnh ci với tính năng tự động hoàn thành tab:
$ eval $(tools/ci.sh --bash-completion)
Đối với shell zsh, thay --bash-completion bằng --zsh-completion. Đối với shell fish, thay --bash-completion bằng --fish-completion.
Sau đó, gõ:
$ ci unix_cov<tab>
Điều này sẽ hoàn thành tên bước ci thành unix_coverage_. Nhấn tab lần thứ hai sẽ hiển thị danh sách các bước phù hợp:
$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…
Cấu trúc thư mục¶
Có một số thư mục cần lưu ý về nơi chứa các chi tiết triển khai nhất định. Sau đây là phân tích các thư mục cấp cao nhất trong mã nguồn.
py
Chứa trình biên dịch, runtime và triển khai thư viện lõi.
mpy-cross
Có trình biên dịch chéo MicroPython, tiền biên dịch các tập lệnh Python thành bytecode.
ports
Mã cho tất cả các phiên bản MicroPython cho các port được hỗ trợ.
lib
Các thư viện C cấp thấp được sử dụng bởi bất kỳ port nào, phần lớn là thư viện bên thứ ba.
drivers
Có các driver cho phần cứng cụ thể và được thiết kế để hoạt động trên nhiều port.
extmod
Chứa triển khai C của các module không phải lõi.
docs
Có tài liệu tiêu chuẩn tìm thấy tại https://docs.micropython.org/.
tests
Một triển khai của bộ kiểm tra.
tools
Chứa các tập lệnh được sử dụng bởi quá trình xây dựng và CI, cũng như các công cụ người dùng như
mpremote.
examples
Mã ví dụ để xây dựng MicroPython như một thư viện cũng như các module native.