Pierwsze kroki

Ten przewodnik opisuje krok po kroku proces konfigurowania kontroli wersji, pobierania i budowania kopii kodu źródłowego dla danego portu, budowania dokumentacji, uruchamiania testów oraz zawiera opis struktury katalogów bazy kodu MicroPython.

Kontrola wersji za pomocą git

MicroPython jest hostowany na GitHub i wykorzystuje Git do kontroli wersji. Przepływ pracy polega na pobieraniu kodu z głównego repozytorium oraz wysyłaniu go do niego. Aby wykonać dalsze kroki, zainstaluj odpowiednią wersję Git dla swojego systemu operacyjnego.

Informacja

Instrukcje dotyczące instalacji znajdziesz w instrukcji instalacji Git. Poznaj podstawowe polecenia git w tym Podręczniku Git lub w innych źródłach w internecie.

Informacja

Dołączony jest plik .git-blame-ignore-revs, który zapobiega zaśmiecaniu wyników git blame przez commity dotyczące wyłącznie formatowania kodu, niewprowadzające żadnych zmian funkcjonalnych. Informacje o jego użyciu znajdziesz w dokumentacji git blame.

Pobierz kod

Zaleca się utrzymywanie własnego forka repozytorium MicroPython na potrzeby rozwoju oprogramowania. Proces pobierania kodu źródłowego obejmuje następujące kroki:

  1. Utwórz forka repozytorium https://github.com/micropython/micropython

  2. Będziesz teraz mieć forka pod adresem <https://github.com/<your-user-name>/micropython>.

  3. Sklonuj sforkowane repozytorium za pomocą następującego polecenia:

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

Następnie skonfiguruj zdalne repozytoria, aby móc współpracować nad projektem MicroPython.

Skonfiguruj zdalne upstream:

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

Często konfiguruje się upstream oraz origin w sforkowanym repozytorium, aby ułatwić dzielenie się zmianami w kodzie. Możesz utrzymywać własne mapowanie, ale zaleca się, aby origin wskazywał na Twojego forka, a upstream na główne repozytorium MicroPython.

Po powyższej konfiguracji Twoje ustawienia powinny wyglądać podobnie do tego:

$ 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)

Powinieneś teraz mieć kopię kodu źródłowego. Domyślnie wskazujesz na gałąź master. Aby przygotować się do dalszego rozwoju, zaleca się pracę na gałęzi deweloperskiej.

$ git checkout -b dev-branch

Możesz nadać jej dowolną nazwę. Za każdym razem, gdy przełączysz się na inną gałąź, będziesz musiał skompilować MicroPython.

Kompilowanie i budowanie kodu

Kompilując MicroPython, kompilujesz konkretny port, zazwyczaj dla określonej płytki. Zacznij od zainstalowania wymaganych zależności. Następnie zbuduj kompilator skrośny MicroPython, zanim będziesz mógł pomyślnie skompilować i zbudować projekt. Dotyczy to w szczególności kompilacji w systemie Linux. Instrukcje dla systemu Windows znajdują się w dalszej części.

Wymagane zależności

Zainstaluj wymagane zależności dla systemu Linux:

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

Dla portu stm32 wymagany jest kompilator skrośny ARM:

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

Najnowsze informacje znajdziesz w łańcuchu narzędzi ARM GCC.

Wymagany jest również Python 3. Sprawdź, czy Python jest dostępny w Twoim systemie:

$ 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.
>>>

Wszystkie obsługiwane porty mają różne wymagania co do zależności, zobacz ich odpowiednie pliki readme.

Budowanie kompilatora skrośnego MicroPython

Niemal wszystkie porty wymagają najpierw zbudowania mpy-cross, aby wstępnie skompilować kod Python, który zostanie dołączony do oprogramowania układowego portu:

$ cd mpy-cross
$ make

Informacja

Zwróć uwagę, że mpy-cross musi być zbudowany dla architektury hosta, a nie dla architektury docelowej.

Jeśli budowanie zakończyło się pomyślnie, powinieneś zobaczyć komunikat podobny do tego:

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

Informacja

Użyj make -C mpy-cross, aby zbudować kompilator skrośny jednym poleceniem, bez przechodzenia do katalogu mpy-cross; w przeciwnym razie do wykonania kolejnych kroków będziesz musiał wpisać cd ...

Budowanie portu Unix MicroPython

Port Unix to wersja MicroPython działająca na systemach Linux, macOS i innych systemach uniksopodobnych. Jest niezwykle przydatny podczas rozwijania MicroPython, ponieważ pozwala uniknąć wdrażania kodu na urządzenie w celu jego przetestowania. Pod wieloma względami działa podobnie do binarki python z CPython.

Aby zbudować port Unix, upewnij się, że wszystkie zależności związane z systemem Linux są zainstalowane, jak opisano w sekcji dotyczącej wymaganych zależności. Zajrzyj do Wymagane zależności, aby upewnić się, że wszystkie zależności dla tego portu są zainstalowane. Upewnij się również, że masz działające środowisko dla gcc oraz GNU make. W poniższym przykładzie użyto Ubuntu 20.04, ale inne systemy uniksowe również powinny działać przy niewielkich modyfikacjach:

$ 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.

następnie zbuduj:

$ cd ports/unix
$ make submodules
$ make

Jeśli MicroPython został zbudowany poprawnie, powinieneś zobaczyć następujący komunikat:

LINK micropython
   text         data     bss     dec     hex filename
 412033         5680    2496  420209   66971 micropython

Teraz go uruchom:

$ ./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
>>>

Budowanie portu Windows

Port Windows zawiera plik projektu Visual Studio micropython.vcxproj, którego możesz użyć do zbudowania micropython.exe. Można go otworzyć w Visual Studio lub zbudować z wiersza poleceń za pomocą msbuild. Alternatywnie można go zbudować przy użyciu mingw, zarówno w systemie Windows z Cygwin, jak i w systemie Linux. Więcej informacji znajdziesz w dokumentacji portu windows.

Budowanie portu STM32

Podobnie jak w przypadku portu Unix, musisz zainstalować niektóre wymagane zależności, jak opisano w sekcji Wymagane zależności, a następnie zbudować:

$ cd ports/stm32
$ make submodules
$ make

Więcej szczegółów na temat wgrywania oprogramowania układowego znajdziesz w dokumentacji stm32.

Informacja

Zajrzyj do Wymagane zależności, aby upewnić się, że wszystkie zależności dla tego portu są zainstalowane. Wymagany jest kompilator skrośny. arm-none-eabi-gcc powinien również znajdować się w $PATH lub być wskazany ręcznie za pomocą CROSS_COMPILE, poprzez ustawienie zmiennej środowiskowej albo w argumentach wiersza poleceń make.

Możesz również określić, której płytki użyć:

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

Dostępne płytki znajdziesz w ports/stm32/boards, np. „OPENMV4” lub „OPENMV4P”.

Budowanie dokumentacji

Dokumentacja MicroPython jest tworzona za pomocą Sphinx. Jeśli masz już zainstalowany Python, zainstaluj Sphinx za pomocą pip. Zaleca się korzystanie ze środowiska wirtualnego:

$ python3 -m venv env
$ source env/bin/activate
$ pip install -r docs/requirements.txt

Przejdź do katalogu docs:

$ cd docs

Zbuduj dokumentację:

$ make html

Otwórz docs/build/html/index.html w przeglądarce, aby przeglądać dokumentację lokalnie. Aby korzystać z Read the Docs, zapoznaj się z dokumentacją dotyczącą importowania dokumentacji.

Uruchamianie testów

Aby uruchomić wszystkie testy z zestawu testów na porcie Unix, użyj:

$ cd ports/unix
$ make test

Aby uruchomić wybrane testy na płytce/urządzeniu podłączonym przez USB, użyj:

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

Zobacz także Pisanie testów.

Dodatkowe cele make dla deweloperów

We wszystkich portach opartych na make istnieje cel służący do wypisywania rozmiaru konkretnego pliku obiektowego. Gdy zmiana dotyczy pojedynczego pliku, jest to przydatne podczas testowania wariantów w celu znalezienia mniejszych alternatyw.

Na przykład, aby wypisać rozmiar objstr.o w katalogu py/ podczas wykonywania standardowej kompilacji unix:

$ make build-standard/py/objstr.sz

Podobnie istnieje cel służący do zapisania wstępnie przetworzonej wersji pliku:

$ make build-standard/py/objstr.pp

W ports/unix istnieją dodatkowe cele związane z uruchamianiem testów:

$ 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

Lokalne użycie ci.sh

MicroPython wykorzystuje GitHub Actions do ciągłej integracji. Aby zmniejszyć zależność od konkretnego systemu CI, właściwe kroki budowania dla kompilacji opartych na systemie Unix znajdują się w pliku tools/ci.sh. Może on być również używany jako skrypt na komputerach deweloperów, z pewnymi zastrzeżeniami:

  • W przypadku większości kroków zakłada się system Ubuntu/Debian podobny do tego używanego podczas CI.

  • Niektóre konkretne kroki zakładają konkretne wersje Ubuntu.

  • Kroki konfiguracyjne mogą wywoływać systemowy menedżer pakietów w celu instalacji pakietów, pobierania i instalowania oprogramowania z internetu itp.

Aby uzyskać komunikat o sposobie użycia wraz z listą poleceń, uruchom:

$ tools/ci.sh --help

Na przykład, możesz zbudować i przetestować minimalny port unix za pomocą:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Jeśli używasz powłoki bash, możesz dodać polecenie ci z uzupełnianiem tabulatorem:

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

Dla powłoki zsh zastąp --bash-completion przez --zsh-completion. Dla powłoki fish zastąp --bash-completion przez --fish-completion.

Następnie wpisanie:

$ ci unix_cov<tab>

Spowoduje to uzupełnienie nazwy kroku ci do unix_coverage_. Ponowne naciśnięcie tabulatora wyświetli listę pasujących kroków:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Struktura katalogów

Istnieje kilka katalogów, na które warto zwrócić uwagę pod kątem tego, gdzie znajdują się określone szczegóły implementacji. Poniżej przedstawiono zestawienie folderów najwyższego poziomu w kodzie źródłowym.

py

Zawiera kompilator, środowisko uruchomieniowe oraz implementację rdzennej biblioteki.

mpy-cross

Zawiera kompilator skrośny MicroPython, który wstępnie kompiluje skrypty Python do kodu bajtowego.

ports

Kod wszystkich wersji MicroPython dla obsługiwanych portów.

lib

Niskopoziomowe biblioteki C używane przez dowolny port, w większości biblioteki firm trzecich.

drivers

Zawiera sterowniki dla konkretnego sprzętu, przeznaczone do działania na wielu portach.

extmod

Zawiera implementację w języku C dodatkowych modułów spoza rdzenia.

docs

Zawiera standardową dokumentację dostępną pod adresem https://docs.micropython.org/.

tests

Implementacja zestawu testów.

tools

Zawiera skrypty używane w procesie budowania i CI, a także narzędzia użytkownika, takie jak mpremote.

examples

Przykładowy kod do budowania MicroPython jako biblioteki, a także moduły natywne.