Első lépések

Ez az útmutató lépésről lépésre bemutatja a verziókövetés beállítását, egy port forráskódjának beszerzését és lefordítását, a dokumentáció elkészítését, a tesztek futtatását, valamint ismerteti a MicroPython kódbázis könyvtárszerkezetét.

Verziókövetés a git segítségével

A MicroPython a GitHubon található, és a verziókövetéshez Gitet használ. A munkafolyamat lényege, hogy a kódot a fő tárolóból töltöd le, illetve oda töltöd fel. A további lépések követéséhez telepítsd a Git operációs rendszerednek megfelelő verzióját.

Megjegyzés

A telepítési útmutatóért lásd a Git telepítési útmutatóját. Az alapvető git parancsokról ebből a Git kézikönyvből vagy bármely más internetes forrásból tájékozódhatsz.

Megjegyzés

Tartalmaz egy .git-blame-ignore-revs fájlt, amely megakadályozza, hogy a git blame kimenetét zsúfolttá tegyék a kizárólag kódformázást végző, funkcionális változtatást nem tartalmazó commitok. Ennek használatáról lásd a git blame dokumentációját.

Szerezd be a kódot

Fejlesztési célokra ajánlott a MicroPython tároló saját forkját fenntartani. A forráskód beszerzésének folyamata a következőkből áll:

  1. Forkold a https://github.com/micropython/micropython tárolót

  2. Ezután lesz egy forkod a <https://github.com/<your-user-name>/micropython> címen.

  3. Klónozd a forkolt tárolót a következő paranccsal:

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

Ezután konfiguráld a távoli tárolókat, hogy közreműködhess a MicroPython projektben.

Konfiguráld a távoli upstreamet:

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

Egy forkolt tárolón gyakori az upstream és az origin konfigurálása a kódváltoztatások megosztásának megkönnyítésére. Saját leképezést is fenntarthatsz, de ajánlott, hogy az origin a forkodra, az upstream pedig a fő MicroPython tárolóra mutasson.

A fenti konfiguráció után a beállításodnak ehhez hasonlónak kell lennie:

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

Most már rendelkezned kell a forráskód másolatával. Alapértelmezés szerint a master ágra mutatsz. A további fejlesztés előkészítéseként ajánlott egy fejlesztői ágon dolgozni.

$ git checkout -b dev-branch

Tetszőleges nevet adhatsz neki. A MicroPythont mindig le kell fordítanod, amikor másik ágra váltasz.

Fordítsd és építsd le a kódot

A MicroPython fordításakor egy adott port-ot fordítasz le, általában egy adott board-ot megcélozva. Kezdd a szükséges függőségek telepítésével. Ezután építsd le a MicroPython keresztfordítóját, mielőtt sikeresen tudnál fordítani és építeni. Ez különösen a Linux alatti fordításra vonatkozik. A Windowsra vonatkozó útmutató egy későbbi szakaszban található.

Szükséges függőségek

Telepítsd a Linuxhoz szükséges függőségeket:

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

Az stm32 porthoz az ARM keresztfordítóra van szükség:

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

A legfrissebb részletekért lásd az ARM GCC eszközkészletet.

Python 3 is szükséges. Ellenőrizd, hogy elérhető-e a Python a rendszereden:

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

Minden támogatott portnak eltérő függőségi követelményei vannak, lásd a hozzájuk tartozó readme fájlokat.

A MicroPython keresztfordító leépítése

Szinte minden porthoz először az mpy-cross leépítésére van szükség, amely előfordítja a port firmware-ébe kerülő Python kódot:

$ cd mpy-cross
$ make

Megjegyzés

Vedd figyelembe, hogy az mpy-cross programot a gazda architektúrára kell leépíteni, nem a célarchitektúrára.

Ha sikeresen leépült, ehhez hasonló üzenetet kell látnod:

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

Megjegyzés

A make -C mpy-cross paranccsal egyetlen utasításban leépítheted a keresztfordítót anélkül, hogy átlépnél az mpy-cross könyvtárba; ellenkező esetben a következő lépésekhez cd .. parancsra lesz szükséged.

A MicroPython Unix portjának leépítése

A Unix port a MicroPython olyan változata, amely Linuxon, macOS-en és más Unix-szerű operációs rendszereken fut. Rendkívül hasznos a MicroPython fejlesztéséhez, mivel megkíméli attól, hogy a kódot egy eszközre kelljen telepítened a teszteléshez. Sok szempontból nagyon hasonlóan működik, mint a CPython python bináris programja.

A Unix port leépítéséhez győződj meg róla, hogy minden Linuxhoz kapcsolódó függőség telepítve van, ahogyan azt a szükséges függőségek szakasz részletezi. Nézd meg a Szükséges függőségek szakaszt, hogy minden függőség telepítve legyen ehhez a porthoz. Győződj meg arról is, hogy működő környezeted van a gcc és a GNU make számára. Az alábbi példához Ubuntu 20.04-et használtunk, de más unix rendszereknek is működniük kell csekély módosítással:

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

majd építsd le:

$ cd ports/unix
$ make submodules
$ make

Ha a MicroPython helyesen leépült, a következőt kell látnod:

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

Most futtasd:

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

A Windows port leépítése

A Windows port tartalmaz egy micropython.vcxproj nevű Visual Studio projektfájlt, amellyel leépítheted a micropython.exe-t. Megnyitható Visual Studióban, vagy lefordítható a parancssorból az msbuild segítségével. Másik lehetőségként leépíthető mingw használatával, akár Windowson Cygwinnel, akár Linuxon. További információért lásd a windows port dokumentációját.

Az STM32 port leépítése

A Unix porthoz hasonlóan néhány szükséges függőséget telepítened kell, ahogyan azt a Szükséges függőségek szakasz részletezi, majd építsd le:

$ cd ports/stm32
$ make submodules
$ make

A firmware flashelésével kapcsolatos további részletekért lásd az stm32 dokumentációt.

Megjegyzés

Nézd meg a Szükséges függőségek szakaszt, hogy minden függőség telepítve legyen ehhez a porthoz. A keresztfordítóra szükség van. Az arm-none-eabi-gcc programnak szintén szerepelnie kell a $PATH változóban, vagy manuálisan kell megadni a CROSS_COMPILE-on keresztül, akár a környezeti változó beállításával, akár a make parancssori argumentumaiban.

Azt is megadhatod, melyik boardot szeretnéd használni:

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

Az elérhető boardokért lásd a ports/stm32/boards könyvtárat. Pl. „OPENMV4” vagy „OPENMV4P”.

A dokumentáció leépítése

A MicroPython dokumentációja a Sphinx segítségével készül. Ha már telepítetted a Pythont, akkor telepítsd a Sphinx-et a pip segítségével. Ajánlott virtuális környezetet használni:

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

Lépj a docs könyvtárba:

$ cd docs

Építsd le a dokumentációt:

$ make html

Nyisd meg a docs/build/html/index.html fájlt a böngésződben a dokumentáció helyi megtekintéséhez. A Read the Docs használatához olvasd el a dokumentációd importálásáról szóló dokumentációt.

A tesztek futtatása

A tesztkészlet összes tesztjének futtatásához a Unix porton használd:

$ cd ports/unix
$ make test

Egy USB-n keresztül csatlakoztatott board/eszközön a tesztek egy részének futtatásához használd:

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

Lásd még: Tesztek írása.

További make célok fejlesztők számára

Minden make alapú portban van egy cél egy adott objektumfájl méretének kiírására. Amikor egy változtatás egyetlen fájlra korlátozódik, ez hasznos a változatok tesztelésekor a kisebb alternatívák megtalálásához.

Például az objstr.o méretének kiírásához a py/ könyvtárban egy unix standard build készítésekor:

$ make build-standard/py/objstr.sz

Hasonlóképpen van egy cél egy fájl előfeldolgozott változatának mentésére:

$ make build-standard/py/objstr.pp

A ports/unix könyvtárban további, a tesztek futtatásához kapcsolódó célok találhatók:

$ 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

A ci.sh helyi használata

A MicroPython a folyamatos integrációhoz GitHub Actionst használ. Ahhoz, hogy csökkentse a függőséget bármely adott CI rendszertől, a Unix alapú buildek tényleges build lépései a tools/ci.sh fájlban találhatók. Ez fejlesztői gépeken szkriptként is használható, néhány megkötéssel:

  • A legtöbb lépésnél a CI során használthoz hasonló Ubuntu/Debian rendszert feltételezünk.

  • Néhány konkrét lépés bizonyos Ubuntu verziókat feltételez.

  • A beállítási lépések meghívhatják a rendszer csomagkezelőjét csomagok telepítéséhez, szoftverek letöltéséhez és telepítéséhez az internetről stb.

A parancsok listáját is tartalmazó használati üzenet megjelenítéséhez futtasd:

$ tools/ci.sh --help

Példaként a unix minimal portot a következővel építheted le és tesztelheted:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Ha bash shellt használsz, hozzáadhatsz egy ci parancsot tabulátoros kiegészítéssel:

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

A zsh shell esetén cseréld le a --bash-completion opciót a --zsh-completion opcióra. A fish shell esetén cseréld le a --bash-completion opciót a --fish-completion opcióra.

Ezután a következő begépelése:

$ ci unix_cov<tab>

Ez kiegészíti a ci lépés nevét unix_coverage_ alakra. A tabulátor második megnyomása megjeleníti az illeszkedő lépések listáját:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Mappaszerkezet

Néhány könyvtárat érdemes megjegyezni azzal kapcsolatban, hogy egyes implementációs részletek hol találhatók. Az alábbiakban a forráskód legfelső szintű mappáinak lebontása következik.

py

Tartalmazza a fordítót, a futtatókörnyezetet és az alapkönyvtár implementációját.

mpy-cross

A MicroPython keresztfordítóját tartalmazza, amely a Python szkripteket bájtkóddá előfordítja.

ports

A MicroPython összes változatának kódja a támogatott portokhoz.

lib

Bármely port által használt alacsony szintű C könyvtárak, amelyek többnyire harmadik féltől származó könyvtárak.

drivers

Adott hardverekhez tartozó illesztőprogramokat tartalmaz, amelyek több porton átívelő működésre szolgálnak.

extmod

Több, nem alaprész modul C implementációját tartalmazza.

docs

A https://docs.micropython.org/ címen található szabványos dokumentációt tartalmazza.

tests

A tesztkészlet egy implementációja.

tools

A build és CI folyamat által használt szkripteket tartalmaz, valamint olyan felhasználói eszközöket, mint az mpremote.

examples

Példakód a MicroPython könyvtárként történő leépítéséhez, valamint natív modulokhoz.