Початок роботи#

Цей посібник охоплює покроковий процес налаштування системи контролю версій, отримання та збирання вихідного коду для певного порту, побудову документації, запуск тестів, а також опис структури директорій кодової бази MicroPython.

Контроль версій за допомогою git#

MicroPython розміщено на GitHub та використовує Git для контролю версій. Робочий процес передбачає витягування та відправлення коду до і з головного репозиторію. Встановіть відповідну версію Git для вашої операційної системи, щоб виконати наступні кроки.

Примітка

Для ознайомлення з інструкціями зі встановлення зверніться до інструкцій зі встановлення Git. Дізнайтесь про базові команди git з цього Git Handbook або інших джерел в Інтернеті.

Примітка

До репозиторію включено файл .git-blame-ignore-revs, який дозволяє уникнути засмічення виводу git blame комітами, що стосуються лише форматування коду без функціональних змін. Дивіться документацію git blame щодо того, як це використовувати.

Отримання коду#

Рекомендується підтримувати форк репозиторію 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, зазвичай для конкретної плати. Почніть зі встановлення необхідних залежностей. Потім зберіть крос-компілятор 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 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-файли.

Збирання крос-компілятора 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 для безперервної інтеграції. Щоб зменшити залежність від конкретної CI-системи, фактичні кроки збирання для Unix-систем містяться у файлі tools/ci.sh. Його також можна використовувати як скрипт на робочих станціях розробників з певними застереженнями:

  • Для більшості кроків передбачається Ubuntu/Debian-система, подібна до тієї, що використовується під час CI.

  • Деякі конкретні кроки передбачають певні версії Ubuntu.

  • Кроки налаштування можуть викликати системний менеджер пакетів для встановлення пакетів, завантаження та встановлення програмного забезпечення з Інтернету тощо.

Для отримання повідомлення про використання, включаючи список команд, виконайте:

$ tools/ci.sh --help

Наприклад, ви можете зібрати та протестувати мінімальний unix-порт за допомогою:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Якщо ви використовуєте оболонку bash, ви можете додати команду ci з автодоповненням табуляцією:

$ 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 до байткоду.

ports

Код для всіх версій MicroPython для підтримуваних портів.

lib

Низькорівневі C-бібліотеки, що використовуються будь-яким портом, переважно сторонні бібліотеки.

drivers

Містить драйвери для конкретного апаратного забезпечення, призначені для роботи з кількома портами.

extmod

Містить реалізацію на C більш неосновних модулів.

docs

Містить стандартну документацію, розміщену за адресою https://docs.micropython.org/.

tests

Реалізація набору тестів.

tools

Містить скрипти, що використовуються в процесі збирання та CI, а також інструменти для користувачів, такі як mpremote.

examples

Приклади коду для збирання MicroPython як бібліотеки, а також нативних модулів.