Начало работы

Это руководство описывает пошаговый процесс настройки системы контроля версий, получения и сборки копии исходного кода для порта, сборки документации, запуска тестов, а также содержит описание структуры каталогов кодовой базы MicroPython.

Контроль версий с помощью git

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

Примечание

В качестве справки по установке обратитесь к инструкциям по установке Git. Изучите основные команды git в Руководстве по Git или в любых других источниках в интернете.

Примечание

В состав включён файл .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.

Также требуется 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_. Повторное нажатие табуляции покажет список подходящих шагов:

$ 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 как библиотеки, а также нативных модулей.