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

Цей посібник охоплює покроковий процес налаштування системи контролю версій, отримання та збирання вихідного коду для певного порту, побудову документації, запуск тестів, а також опис структури директорій кодової бази 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 як бібліотеки, а також нативних модулів.