Početak rada

Ovaj vodič opisuje postupak korak po korak za postavljanje kontrole verzija, dohvaćanje i izgradnju kopije izvornog koda za određeni port, izgradnju dokumentacije, pokretanje testova te opis strukture direktorija MicroPython baze koda.

Kontrola izvornog koda pomoću gita

MicroPython se nalazi na GitHubu i koristi Git za kontrolu izvornog koda. Radni tijek je takav da se kod dohvaća i šalje iz i u glavni repozitorij. Instalirajte odgovarajuću verziju Gita za svoj operativni sustav kako biste mogli pratiti ostatak koraka.

Napomena

Za upute o instalaciji pogledajte upute za instalaciju Gita. O osnovnim git naredbama saznajte više u ovom Git priručniku ili iz bilo kojeg drugog izvora na internetu.

Napomena

Uključena je datoteka .git-blame-ignore-revs koja sprječava da izlaz naredbe git blame bude zatrpan commitovima koji služe samo za oblikovanje koda, ali nemaju funkcionalnih promjena. Pogledajte dokumentaciju za git blame za upute o korištenju ove mogućnosti.

Dohvaćanje koda

Preporučuje se da za svoje razvojne potrebe održavate vlastiti fork MicroPython repozitorija. Postupak dohvaćanja izvornog koda uključuje sljedeće:

  1. Forkajte repozitorij https://github.com/micropython/micropython

  2. Sada ćete imati fork na <https://github.com/<your-user-name>/micropython>.

  3. Klonirajte forkani repozitorij pomoću sljedeće naredbe:

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

Zatim konfigurirajte udaljene repozitorije kako biste mogli surađivati na MicroPython projektu.

Konfigurirajte udaljeni upstream:

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

Uobičajeno je da se na forkanom repozitoriju konfiguriraju upstream i origin radi lakšeg dijeljenja promjena koda. Možete održavati vlastito mapiranje, ali preporučuje se da origin upućuje na vaš fork, a upstream na glavni MicroPython repozitorij.

Nakon gornje konfiguracije, vaše postavke trebale bi biti slične ovima:

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

Sada biste trebali imati kopiju izvornog koda. Prema zadanim postavkama, upućujete na master granu. Kako biste se pripremili za daljnji razvoj, preporučuje se da radite na razvojnoj grani.

$ git checkout -b dev-branch

Možete joj dati bilo koje ime. MicroPython ćete morati ponovno kompilirati svaki put kada prijeđete na drugu granu.

Kompilacija i izgradnja koda

Pri kompiliranju MicroPythona kompilirate određeni port, obično ciljajući određenu ploču. Započnite instaliranjem potrebnih ovisnosti. Zatim izgradite MicroPython unakrsni kompilator prije nego što uspješno kompilirate i izgradite. Ovo se posebno odnosi na korištenje Linuxa za kompiliranje. Upute za Windows nalaze se u kasnijem odjeljku.

Potrebne ovisnosti

Instalirajte potrebne ovisnosti za Linux:

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

Za stm32 port potreban je ARM unakrsni kompilator:

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

Pogledajte ARM GCC toolchain za najnovije pojedinosti.

Potreban je i Python 3. Provjerite je li Python dostupan na vašem sustavu:

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

Svi podržani portovi imaju različite zahtjeve za ovisnostima, pogledajte njihove odgovarajuće readme datoteke.

Izgradnja MicroPython unakrsnog kompilatora

Gotovo svi portovi zahtijevaju da se najprije izgradi mpy-cross radi pretkompilacije Python koda koji će biti uključen u firmware porta:

$ cd mpy-cross
$ make

Napomena

Imajte na umu da se mpy-cross mora izgraditi za arhitekturu domaćina, a ne za ciljnu arhitekturu.

Ako je izgradnja uspješna, trebali biste vidjeti poruku sličnu ovoj:

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

Napomena

Koristite make -C mpy-cross za izgradnju unakrsnog kompilatora jednom naredbom bez prelaska u mpy-cross direktorij, inače ćete za sljedeće korake morati izvršiti cd ...

Izgradnja Unix porta MicroPythona

Unix port je verzija MicroPythona koja se izvodi na Linuxu, macOS-u i drugim operativnim sustavima sličnima Unixu. Iznimno je koristan za razvoj MicroPythona jer izbjegava potrebu za postavljanjem koda na uređaj radi testiranja. Na mnogo načina radi vrlo slično CPythonovom python binarnom programu.

Za izgradnju Unix porta provjerite jesu li sve ovisnosti vezane uz Linux instalirane kako je opisano u odjeljku o potrebnim ovisnostima. Pogledajte Potrebne ovisnosti kako biste provjerili jesu li sve ovisnosti instalirane za ovaj port. Također provjerite imate li ispravno radno okruženje za gcc i GNU make. U primjeru u nastavku korišten je Ubuntu 20.04, ali i drugi unixi trebali bi raditi uz manje izmjene:

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

zatim izgradite:

$ cd ports/unix
$ make submodules
$ make

Ako je MicroPython ispravno izgrađen, trebali biste vidjeti sljedeće:

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

Sada ga pokrenite:

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

Izgradnja Windows porta

Windows port uključuje Visual Studio projektnu datoteku micropython.vcxproj koju možete koristiti za izgradnju micropython.exe. Može se otvoriti u Visual Studiju ili izgraditi iz naredbenog retka pomoću msbuild. Alternativno, može se izgraditi pomoću mingw, bilo na Windowsima uz Cygwin, bilo na Linuxu. Za više informacija pogledajte dokumentaciju Windows porta.

Izgradnja STM32 porta

Kao i kod Unix porta, morate instalirati neke potrebne ovisnosti kako je opisano u odjeljku Potrebne ovisnosti, a zatim izgraditi:

$ cd ports/stm32
$ make submodules
$ make

Za više pojedinosti o flešanju firmwarea pogledajte dokumentaciju za stm32.

Napomena

Pogledajte Potrebne ovisnosti kako biste provjerili jesu li sve ovisnosti instalirane za ovaj port. Potreban je unakrsni kompilator. arm-none-eabi-gcc također bi trebao biti u $PATH ili ručno naveden putem CROSS_COMPILE, bilo postavljanjem varijable okruženja, bilo u argumentima naredbenog retka naredbe make.

Možete također navesti koju ploču koristiti:

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

Pogledajte ports/stm32/boards za dostupne ploče. Npr. „OPENMV4” ili „OPENMV4P”.

Izgradnja dokumentacije

MicroPython dokumentacija stvara se pomoću Sphinx. Ako ste već instalirali Python, instalirajte Sphinx pomoću pip. Preporučuje se korištenje virtualnog okruženja:

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

Idite u docs direktorij:

$ cd docs

Izgradite dokumentaciju:

$ make html

Otvorite docs/build/html/index.html u svom pregledniku za lokalni pregled dokumentacije. Za korištenje Read the Docs pogledajte dokumentaciju o uvozu vaše dokumentacije.

Pokretanje testova

Za pokretanje svih testova u testnom paketu na Unix portu koristite:

$ cd ports/unix
$ make test

Za pokretanje odabranog skupa testova na ploči/uređaju spojenom putem USB-a koristite:

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

Pogledajte i Pisanje testova.

Dodatni make ciljevi za razvojne programere

U svim portovima temeljenima na make postoji cilj za ispis veličine određene objektne datoteke. Kada je promjena ograničena na jednu datoteku, ovo je korisno pri testiranju varijacija radi pronalaska manjih alternativa.

Na primjer, za ispis veličine objstr.o u py/ direktoriju prilikom izrade standardne unix izgradnje:

$ make build-standard/py/objstr.sz

Slično tome, postoji cilj za spremanje pretprocesirane verzije datoteke:

$ make build-standard/py/objstr.pp

U ports/unix postoje dodatni ciljevi vezani uz pokretanje testova:

$ 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

Lokalno korištenje ci.sh

MicroPython koristi GitHub Actions za kontinuiranu integraciju. Kako bi se smanjila ovisnost o bilo kojem određenom CI sustavu, stvarni koraci izgradnje za izgradnje temeljene na Unixu nalaze se u datoteci tools/ci.sh. Ona se može koristiti i kao skripta na računalima razvojnih programera, uz neka ograničenja:

  • Za većinu koraka pretpostavlja se Ubuntu/Debian sustav sličan onome koji se koristi tijekom CI-ja.

  • Neki specifični koraci pretpostavljaju određene verzije Ubuntua.

  • Koraci postavljanja mogu pozvati upravitelj paketa sustava radi instaliranja paketa, preuzimanja i instaliranja softvera s interneta itd.

Za prikaz poruke o korištenju koja uključuje popis naredbi, pokrenite:

$ tools/ci.sh --help

Kao primjer, možete izgraditi i testirati unix minimal port pomoću:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Ako koristite bash ljusku, možete dodati naredbu ci s dovršavanjem pomoću tipke tab:

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

Za zsh ljusku zamijenite --bash-completion s --zsh-completion. Za fish ljusku zamijenite --bash-completion s --fish-completion.

Zatim, upisivanjem:

$ ci unix_cov<tab>

Time će se naziv ci koraka dovršiti u unix_coverage_. Drugim pritiskom na tab prikazat će se popis odgovarajućih koraka:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Struktura mapa

Postoji nekoliko direktorija koje treba zapamtiti u smislu toga gdje se nalaze određeni detalji implementacije. Slijedi pregled mapa najviše razine u izvornom kodu.

py

Sadrži kompilator, runtime i implementaciju osnovne biblioteke.

mpy-cross

Sadrži MicroPython unakrsni kompilator koji pretkompilira Python skripte u bytecode.

ports

Kod za sve verzije MicroPythona za podržane portove.

lib

Niskorazinske C biblioteke koje koristi bilo koji port, a koje su uglavnom biblioteke trećih strana.

drivers

Sadrži upravljačke programe za određeni hardver, namijenjene radu na više portova.

extmod

Sadrži C implementaciju dodatnih modula koji nisu dio jezgre.

docs

Sadrži standardnu dokumentaciju dostupnu na https://docs.micropython.org/.

tests

Implementacija testnog paketa.

tools

Sadrži skripte koje koriste procesi izgradnje i CI-ja, kao i korisničke alate poput mpremote.

examples

Primjeri koda za izgradnju MicroPythona kao biblioteke te za izradu nativnih modula.