Aloittaminen

Tämä opas käy vaihe vaiheelta läpi versionhallinnan käyttöönoton, portin lähdekoodin hankkimisen ja kääntämisen, dokumentaation rakentamisen, testien suorittamisen sekä kuvaa MicroPython-koodikannan hakemistorakenteen.

Versionhallinta gitillä

MicroPython sijaitsee GitHubissa ja käyttää versionhallintaan Git -työkalua. Työnkulku on sellainen, että koodia haetaan ja viedään päärepositorioon ja sieltä pois. Asenna käyttöjärjestelmääsi sopiva Git-versio, jotta voit seurata loppuosaa vaiheista.

Muista

Asennusohjeiden osalta katso Gitin asennusohjeet. Tutustu Gitin peruskomentoihin Git-käsikirjassa tai muista internetin lähteistä.

Muista

Mukana on .git-blame-ignore-revs-tiedosto, joka estää git blame -tulosteen sotkeutumisen sellaisista committeista, jotka muotoilevat koodia mutta eivät sisällä toiminnallisia muutoksia. Katso git blame -dokumentaatio tämän käyttöohjeista.

Hae koodi

On suositeltavaa, että ylläpidät kehitystäsi varten omaa haarukkaa (fork) MicroPython-repositoriosta. Lähdekoodin hankkiminen sisältää seuraavat vaiheet:

  1. Haarukoi (fork) repositorio https://github.com/micropython/micropython

  2. Sinulla on nyt haarukka osoitteessa <https://github.com/<your-user-name>/micropython>.

  3. Kloonaa haarukoitu repositorio seuraavalla komennolla:

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

Tämän jälkeen määritä etärepositoriot, jotta voit tehdä yhteistyötä MicroPython-projektissa.

Määritä etä-upstream:

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

On yleistä määrittää haarukoituun repositorioon upstream ja origin koodimuutosten jakamisen helpottamiseksi. Voit ylläpitää omaa kytkentääsi, mutta on suositeltavaa, että origin osoittaa haarukkaasi ja upstream MicroPythonin päärepositorioon.

Yllä olevan määrityksen jälkeen kokoonpanosi pitäisi olla tämän kaltainen:

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

Sinulla pitäisi nyt olla kopio lähdekoodista. Oletuksena osoitat master-haaraan. Jatkokehitykseen valmistautuaksesi on suositeltavaa työskennellä kehityshaarassa.

$ git checkout -b dev-branch

Voit antaa sille minkä tahansa nimen. Sinun täytyy kääntää MicroPython aina kun vaihdat eri haaraan.

Käännä ja rakenna koodi

MicroPythonia kääntäessäsi käännät tietyn port-portin, joka tavallisesti kohdistuu tiettyyn korttiin. Aloita asentamalla vaaditut riippuvuudet. Rakenna sitten MicroPythonin ristikääntäjä, ennen kuin voit onnistuneesti kääntää ja rakentaa. Tämä koskee erityisesti Linuxilla kääntämistä. Windows-ohjeet annetaan myöhemmässä osiossa.

Vaaditut riippuvuudet

Asenna Linuxille vaaditut riippuvuudet:

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

stm32-porttia varten tarvitaan ARM-ristikääntäjä:

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

Katso uusimmat tiedot ARM GCC -työkaluketjusta.

Myös Python 3 vaaditaan. Tarkista, että Python on käytettävissä järjestelmässäsi:

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

Kaikilla tuetuilla porteilla on erilaiset riippuvuusvaatimukset, katso niiden vastaavat readme-tiedostot.

MicroPythonin ristikääntäjän rakentaminen

Lähes kaikki portit vaativat mpy-cross-ristikääntäjän rakentamisen ensin, jotta voidaan esikääntää portin laiteohjelmistoon sisällytettävä Python-koodi:

$ cd mpy-cross
$ make

Muista

Huomaa, että mpy-cross on rakennettava isäntäarkkitehtuurille eikä kohdearkkitehtuurille.

Jos rakentaminen onnistui, sinun pitäisi nähdä tämän kaltainen viesti:

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

Muista

Käytä make -C mpy-cross rakentaaksesi ristikääntäjän yhdellä komennolla siirtymättä mpy-cross-hakemistoon; muuten sinun täytyy suorittaa cd .. seuraavia vaiheita varten.

MicroPythonin Unix-portin rakentaminen

Unix-portti on MicroPython-versio, joka toimii Linuxilla, macOS:llä ja muilla Unix-tyyppisillä käyttöjärjestelmillä. Se on erittäin hyödyllinen MicroPythonin kehittämisessä, koska se poistaa tarpeen viedä koodi laitteeseen testaamista varten. Monin tavoin se toimii hyvin samaan tapaan kuin CPythonin python-binääri.

Rakentaaksesi Unix-portin varmista, että kaikki Linuxiin liittyvät riippuvuudet on asennettu vaadittujen riippuvuuksien osiossa kuvatulla tavalla. Katso Vaaditut riippuvuudet varmistaaksesi, että kaikki tämän portin riippuvuudet on asennettu. Varmista myös, että sinulla on toimiva ympäristö gcc- ja GNU make -työkaluille. Alla olevassa esimerkissä on käytetty Ubuntu 20.04:ää, mutta muiden unixien pitäisi toimia pienin muutoksin:

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

rakenna sitten:

$ cd ports/unix
$ make submodules
$ make

Jos MicroPython rakentui oikein, sinun pitäisi nähdä seuraava:

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

Suorita se nyt:

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

Windows-portti sisältää Visual Studio -projektitiedoston micropython.vcxproj, jolla voit rakentaa micropython.exe-tiedoston. Sen voi avata Visual Studiossa tai rakentaa komentoriviltä msbuild-työkalulla. Vaihtoehtoisesti sen voi rakentaa mingw-työkalulla joko Windowsissa Cygwinin avulla tai Linuxilla. Lisätietoja löytyy Windows-portin dokumentaatiosta.

STM32-portin rakentaminen

Unix-portin tapaan sinun täytyy asentaa joitakin vaadittuja riippuvuuksia Vaaditut riippuvuudet -osiossa kuvatulla tavalla, ja rakentaa sitten:

$ cd ports/stm32
$ make submodules
$ make

Katso laiteohjelmiston flashaamisesta lisätietoja stm32-dokumentaatiosta.

Muista

Katso Vaaditut riippuvuudet varmistaaksesi, että kaikki tämän portin riippuvuudet on asennettu. Ristikääntäjää tarvitaan. Myös arm-none-eabi-gcc tulisi olla $PATH-polussa tai määritetty manuaalisesti CROSS_COMPILE-muuttujan kautta, joko ympäristömuuttujaa asettamalla tai make-komennon argumenteissa.

Voit myös määrittää, mitä korttia käytetään:

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

Katso saatavilla olevat kortit kohdasta ports/stm32/boards. Esim. ”OPENMV4” tai ”OPENMV4P”.

Dokumentaation rakentaminen

MicroPython-dokumentaatio luodaan Sphinx-työkalulla. Jos olet jo asentanut Pythonin, asenna Sphinx pip-työkalulla. On suositeltavaa käyttää virtuaaliympäristöä:

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

Siirry docs-hakemistoon:

$ cd docs

Rakenna dokumentaatio:

$ make html

Avaa docs/build/html/index.html selaimessasi tarkastellaksesi dokumentaatiota paikallisesti. Read the Docs -palvelun käytöstä katso dokumentaatio dokumentaatiosi tuonnista.

Testien suorittaminen

Suorittaaksesi kaikki testikokoelman testit Unix-portilla käytä:

$ cd ports/unix
$ make test

Suorittaaksesi valikoiman testejä USB:n kautta kytketyllä kortilla/laitteella käytä:

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

Katso myös Testien kirjoittaminen.

Lisää make-kohteita kehittäjille

Kaikissa make-pohjaisissa porteissa on kohde, joka tulostaa tietyn objektitiedoston koon. Kun muutos rajoittuu yhteen tiedostoon, tämä on hyödyllinen testattaessa muunnelmia pienempien vaihtoehtojen löytämiseksi.

Esimerkiksi tulostaaksesi objstr.o-tiedoston koon py/-hakemistossa unix-standardirakennusta tehtäessä:

$ make build-standard/py/objstr.sz

Vastaavasti on kohde, joka tallentaa tiedoston esikäsitellyn version:

$ make build-standard/py/objstr.pp

ports/unix-hakemistossa on lisäkohteita, jotka liittyvät testien suorittamiseen:

$ 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:n käyttäminen paikallisesti

MicroPython käyttää jatkuvaan integrointiin GitHub Actionsia. Vähentääkseen riippuvuutta mistään tietystä CI-järjestelmästä Unix-pohjaisten rakennusten varsinaiset rakennusvaiheet ovat tiedostossa tools/ci.sh. Tätä voidaan käyttää myös skriptinä kehittäjien työpöydillä tietyin varauksin:

  • Useimpia vaiheita varten oletetaan CI:n aikana käytettyä Ubuntu/Debian-järjestelmää muistuttava järjestelmä.

  • Jotkin tietyt vaiheet olettavat tiettyjä Ubuntu-versioita.

  • Asennusvaiheet voivat kutsua järjestelmän pakettienhallintaa pakettien asentamiseksi, ladata ja asentaa ohjelmistoja internetistä jne.

Saadaksesi käyttöviestin, joka sisältää komentojen luettelon, suorita:

$ tools/ci.sh --help

Esimerkkinä voit rakentaa ja testata unix minimal -portin näin:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Jos käytät bash-kuorta, voit lisätä ci-komennon, jossa on sarkaintäydennys:

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

Zsh-kuorelle korvaa --bash-completion arvolla --zsh-completion. Fish-kuorelle korvaa --bash-completion arvolla --fish-completion.

Kirjoittamalla sitten:

$ ci unix_cov<tab>

Tämä täydentää ci-vaiheen nimen muotoon unix_coverage_. Sarkaimen painaminen toisen kerran näyttää luettelon vastaavista vaiheista:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Kansiorakenne

On muutamia hakemistoja, jotka kannattaa panna merkille sen suhteen, missä tietyt toteutusyksityiskohdat sijaitsevat. Seuraavassa on erittely lähdekoodin ylimmän tason kansioista.

py

Sisältää kääntäjän, ajonaikaisen ympäristön ja ydinkirjaston toteutuksen.

mpy-cross

Sisältää MicroPython-ristikääntäjän, joka esikääntää Python-skriptit tavukoodiksi.

ports

Koodi kaikille MicroPython-versioille tuettujen porttien osalta.

lib

Matalan tason C-kirjastot, joita mikä tahansa portti käyttää ja jotka ovat enimmäkseen kolmannen osapuolen kirjastoja.

drivers

Sisältää ajurit tietyille laitteistoille, ja ne on tarkoitettu toimimaan useiden porttien välillä.

extmod

Sisältää useampien ei-ydinmoduulien C-toteutuksen.

docs

Sisältää vakiodokumentaation, joka löytyy osoitteesta https://docs.micropython.org/.

tests

Testikokoelman toteutus.

tools

Sisältää rakennus- ja CI-prosessin käyttämiä skriptejä sekä käyttäjätyökaluja kuten mpremote.

examples

Esimerkkikoodia MicroPythonin rakentamiseen kirjastona sekä natiivimoduuleille.