Začínáme

Tato příručka popisuje krok za krokem nastavení správy verzí, získání a sestavení kopie zdrojového kódu pro daný port, sestavení dokumentace, spouštění testů a popis adresářové struktury kódové základny MicroPythonu.

Správa zdrojového kódu pomocí git

MicroPython je hostován na GitHubu a pro správu zdrojového kódu používá Git. Pracovní postup je takový, že se kód stahuje a odesílá do hlavního repozitáře a z něj. Nainstalujte si příslušnou verzi Gitu pro svůj operační systém, abyste mohli pokračovat ve zbývajících krocích.

Poznámka

Pokyny k instalaci najdete v instrukcích pro instalaci Gitu. Základní příkazy gitu se naučíte v této příručce Git Handbook nebo z jiných zdrojů na internetu.

Poznámka

Součástí je soubor .git-blame-ignore-revs, který zabraňuje tomu, aby výstup git blame byl zahlcen commity, jež pouze formátují kód, ale nepřinášejí žádné funkční změny. Jak jej použít, najdete v dokumentaci git blame.

Získání kódu

Pro účely vývoje se doporučuje udržovat fork repozitáře MicroPython. Proces získání zdrojového kódu zahrnuje následující:

  1. Forkněte repozitář https://github.com/micropython/micropython

  2. Nyní budete mít fork na adrese <https://github.com/<your-user-name>/micropython>.

  3. Naklonujte forknutý repozitář pomocí následujícího příkazu:

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

Poté nakonfigurujte vzdálené repozitáře, abyste mohli na projektu MicroPython spolupracovat.

Konfigurace vzdáleného upstreamu:

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

U forknutého repozitáře je běžné nakonfigurovat upstream a origin pro usnadnění sdílení změn kódu. Můžete si udržovat vlastní mapování, ale doporučuje se, aby origin odkazoval na váš fork a upstream na hlavní repozitář MicroPython.

Po výše uvedené konfiguraci by vaše nastavení mělo vypadat přibližně takto:

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

Nyní byste měli mít kopii zdrojového kódu. Ve výchozím nastavení ukazujete na větev master. Pro přípravu na další vývoj se doporučuje pracovat ve vývojové větvi.

$ git checkout -b dev-branch

Můžete jí dát libovolný název. MicroPython budete muset zkompilovat pokaždé, když přepnete na jinou větev.

Kompilace a sestavení kódu

Při kompilaci MicroPythonu kompilujete konkrétní port, obvykle cílený na konkrétní desku. Začněte instalací požadovaných závislostí. Poté sestavte cross-kompilátor MicroPythonu, než budete moci úspěšně zkompilovat a sestavit. To platí specificky při kompilaci v Linuxu. Pokyny pro Windows jsou uvedeny v pozdější části.

Požadované závislosti

Nainstalujte požadované závislosti pro Linux:

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

Pro port stm32 je vyžadován ARM cross-kompilátor:

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

Aktuální podrobnosti najdete v nástrojovém řetězci ARM GCC.

Vyžadován je také Python 3. Ověřte, že máte Python ve svém systému k dispozici:

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

Všechny podporované porty mají různé požadavky na závislosti, viz jejich příslušné soubory readme.

Sestavení cross-kompilátoru MicroPythonu

Téměř všechny porty vyžadují nejprve sestavení mpy-cross pro provedení předběžné kompilace Python kódu, který bude součástí firmwaru portu:

$ cd mpy-cross
$ make

Poznámka

Pozor, mpy-cross musí být sestaven pro hostitelskou architekturu, nikoli pro cílovou architekturu.

Pokud se sestavení podařilo, měli byste vidět zprávu podobnou této:

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

Poznámka

Použijte make -C mpy-cross k sestavení cross-kompilátoru jediným příkazem bez přechodu do adresáře mpy-cross; v opačném případě budete pro následující kroky muset provést cd ...

Sestavení Unixového portu MicroPythonu

Unixový port je verze MicroPythonu, která běží na Linuxu, macOS a dalších unixových operačních systémech. Je mimořádně užitečný pro vývoj MicroPythonu, protože odpadá nutnost nasazovat kód na zařízení kvůli testování. V mnoha ohledech funguje velmi podobně jako binárka python v CPythonu.

Pro sestavení Unixového portu se ujistěte, že jsou nainstalovány všechny závislosti související s Linuxem, jak je popsáno v části o požadovaných závislostech. Viz Požadované závislosti, abyste se ujistili, že jsou pro tento port nainstalovány všechny závislosti. Dále se ujistěte, že máte funkční prostředí pro gcc a GNU make. V níže uvedeném příkladu byl použit Ubuntu 20.04, ale s malými úpravami by měly fungovat i jiné unixy:

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

poté sestavte:

$ cd ports/unix
$ make submodules
$ make

Pokud se MicroPython sestavil správně, měli byste vidět následující:

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

Nyní jej spusťte:

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

Sestavení portu pro Windows

Port pro Windows obsahuje soubor projektu Visual Studio micropython.vcxproj, který můžete použít k sestavení micropython.exe. Lze jej otevřít ve Visual Studiu nebo sestavit z příkazové řádky pomocí msbuild. Případně jej lze sestavit pomocí mingw, a to buď ve Windows s Cygwinem, nebo v Linuxu. Více informací najdete v dokumentaci portu pro Windows.

Sestavení portu STM32

Stejně jako u Unixového portu musíte nainstalovat některé požadované závislosti, jak je popsáno v části Požadované závislosti, a poté sestavit:

$ cd ports/stm32
$ make submodules
$ make

Více podrobností o flashování firmwaru najdete v dokumentaci stm32.

Poznámka

Viz Požadované závislosti, abyste se ujistili, že jsou pro tento port nainstalovány všechny závislosti. Je potřeba cross-kompilátor. arm-none-eabi-gcc by také měl být v $PATH nebo zadán ručně prostřednictvím CROSS_COMPILE, buď nastavením proměnné prostředí, nebo v argumentech příkazové řádky make.

Můžete také určit, kterou desku použít:

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

Dostupné desky najdete v ports/stm32/boards, např. „OPENMV4“ nebo „OPENMV4P“.

Sestavení dokumentace

Dokumentace MicroPythonu se vytváří pomocí Sphinx. Pokud již máte nainstalovaný Python, nainstalujte Sphinx pomocí pip. Doporučuje se použít virtuální prostředí:

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

Přejděte do adresáře docs:

$ cd docs

Sestavte dokumentaci:

$ make html

Otevřete docs/build/html/index.html ve svém prohlížeči a zobrazte si dokumentaci lokálně. Pro použití Read the Docs si přečtěte dokumentaci o importu vaší dokumentace.

Spouštění testů

Pro spuštění všech testů v testovací sadě na Unixovém portu použijte:

$ cd ports/unix
$ make test

Pro spuštění výběru testů na desce/zařízení připojeném přes USB použijte:

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

Viz také Psaní testů.

Další cíle make pro vývojáře

Ve všech portech založených na make existuje cíl pro výpis velikosti konkrétního objektového souboru. Pokud je změna omezena na jediný soubor, je to užitečné při testování variant pro nalezení menších alternativ.

Například pro výpis velikosti objstr.o v adresáři py/ při vytváření standardního unixového sestavení:

$ make build-standard/py/objstr.sz

Podobně existuje cíl pro uložení předzpracované verze souboru:

$ make build-standard/py/objstr.pp

V ports/unix existují další cíle související se spouštěním testů:

$ 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

Lokální použití ci.sh

MicroPython používá pro kontinuální integraci GitHub Actions. Pro snížení závislosti na konkrétním CI systému jsou skutečné kroky sestavení pro unixová sestavení umístěny v souboru tools/ci.sh. Ten lze použít také jako skript na vývojářských stanicích, s těmito výhradami:

  • U většiny kroků se předpokládá systém Ubuntu/Debian podobný tomu, který se používá během CI.

  • Některé konkrétní kroky předpokládají konkrétní verze Ubuntu.

  • Kroky nastavení mohou vyvolat systémový správce balíčků pro instalaci balíčků, stahování a instalaci softwaru z internetu apod.

Pro získání zprávy o použití včetně seznamu příkazů spusťte:

$ tools/ci.sh --help

Jako příklad můžete sestavit a otestovat minimální unixový port pomocí:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Pokud používáte shell bash, můžete přidat příkaz ci s dokončováním pomocí tabulátoru:

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

Pro shell zsh nahraďte --bash-completion za --zsh-completion. Pro shell fish nahraďte --bash-completion za --fish-completion.

Poté napsáním:

$ ci unix_cov<tab>

Tím se název kroku ci doplní na unix_coverage_. Druhým stisknutím tabulátoru se zobrazí seznam odpovídajících kroků:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Struktura složek

Existuje několik adresářů, kterých si je třeba povšimnout z hlediska toho, kde se nacházejí určité implementační detaily. Následuje rozpis složek nejvyšší úrovně ve zdrojovém kódu.

py

Obsahuje implementaci kompilátoru, běhového prostředí a základní knihovny.

mpy-cross

Obsahuje cross-kompilátor MicroPythonu, který předkompilovává Python skripty do bytekódu.

ports

Kód pro všechny verze MicroPythonu pro podporované porty.

lib

Nízkoúrovňové C knihovny používané kterýmkoli portem, většinou knihovny třetích stran.

drivers

Obsahuje ovladače pro konkrétní hardware, určené k práci napříč více porty.

extmod

Obsahuje C implementaci dalších, nejádrových modulů.

docs

Obsahuje standardní dokumentaci dostupnou na https://docs.micropython.org/.

tests

Implementace testovací sady.

tools

Obsahuje skripty používané při sestavovacím a CI procesu, jakož i uživatelské nástroje jako mpremote.

examples

Ukázkový kód pro sestavení MicroPythonu jako knihovny a také pro nativní moduly.