Primii pași

Acest ghid acoperă procesul pas cu pas de configurare a controlului versiunilor, de obținere și compilare a unei copii a codului sursă pentru un port, de generare a documentației, de rulare a testelor și o descriere a structurii de directoare a bazei de cod MicroPython.

Controlul versiunilor cu git

MicroPython este găzduit pe GitHub și folosește Git pentru controlul versiunilor. Fluxul de lucru constă în preluarea (pull) și trimiterea (push) codului către și dinspre depozitul principal. Instalați versiunea de Git corespunzătoare sistemului dumneavoastră de operare pentru a parcurge restul pașilor.

Notă

Pentru instrucțiuni de instalare, consultați instrucțiunile de instalare a Git. Aflați despre comenzile de bază git din acest Git Handbook sau din orice alte surse de pe internet.

Notă

Este inclus un fișier .git-blame-ignore-revs care împiedică aglomerarea rezultatului comenzii git blame cu commit-uri care sunt destinate doar formatării codului, dar care nu aduc modificări funcționale. Consultați documentația git blame pentru a afla cum să folosiți acest fișier.

Obțineți codul

Este recomandat să mențineți un fork al depozitului MicroPython în scopurile dumneavoastră de dezvoltare. Procesul de obținere a codului sursă include următoarele:

  1. Faceți fork depozitului https://github.com/micropython/micropython

  2. Veți avea acum un fork la adresa <https://github.com/<your-user-name>/micropython>.

  3. Clonați depozitul după care ați făcut fork folosind următoarea comandă:

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

Apoi, configurați depozitele la distanță pentru a putea colabora la proiectul MicroPython.

Configurați upstream-ul la distanță:

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

Este obișnuit să configurați upstream și origin pe un depozit după care s-a făcut fork pentru a facilita partajarea modificărilor de cod. Puteți menține propria asociere, dar este recomandat ca origin să indice către fork-ul dumneavoastră, iar upstream către depozitul principal MicroPython.

După configurarea de mai sus, setarea dumneavoastră ar trebui să fie similară cu aceasta:

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

Acum ar trebui să aveți o copie a codului sursă. În mod implicit, indicați către ramura master. Pentru a vă pregăti pentru dezvoltarea ulterioară, este recomandat să lucrați pe o ramură de dezvoltare.

$ git checkout -b dev-branch

Îi puteți da orice nume. Va trebui să compilați MicroPython ori de câte ori treceți la o altă ramură.

Compilați și construiți codul

La compilarea MicroPython, compilați un anumit port, vizând de obicei o anumită placă. Începeți prin a instala dependențele necesare. Apoi construiți cross-compilatorul MicroPython înainte de a putea compila și construi cu succes. Acest lucru se aplică în special atunci când folosiți Linux pentru compilare. Instrucțiunile pentru Windows sunt furnizate într-o secțiune ulterioară.

Dependențe necesare

Instalați dependențele necesare pentru Linux:

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

Pentru portul stm32 este necesar cross-compilatorul ARM:

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

Consultați setul de instrumente ARM GCC pentru cele mai recente detalii.

Este necesar și Python 3. Verificați că aveți Python disponibil pe sistemul dumneavoastră:

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

Toate porturile acceptate au cerințe de dependențe diferite; consultați fișierele readme corespunzătoare.

Construirea cross-compilatorului MicroPython

Aproape toate porturile necesită construirea mai întâi a mpy-cross pentru a efectua precompilarea codului Python care va fi inclus în firmware-ul portului:

$ cd mpy-cross
$ make

Notă

Rețineți că mpy-cross trebuie construit pentru arhitectura gazdă, nu pentru arhitectura țintă.

Dacă s-a construit cu succes, ar trebui să vedeți un mesaj similar cu acesta:

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

Notă

Folosiți make -C mpy-cross pentru a construi cross-compilatorul într-o singură instrucțiune fără a vă muta în directorul mpy-cross; în caz contrar, va trebui să executați cd .. pentru pașii următori.

Construirea portului Unix al MicroPython

Portul Unix este o versiune de MicroPython care rulează pe Linux, macOS și alte sisteme de operare de tip Unix. Este extrem de util pentru dezvoltarea MicroPython, deoarece evită necesitatea de a implementa codul pe un dispozitiv pentru a-l testa. În multe privințe, funcționează la fel ca binarul python al CPython.

Pentru a construi pentru portul Unix, asigurați-vă că toate dependențele legate de Linux sunt instalate, așa cum se detaliază în secțiunea referitoare la dependențele necesare. Consultați Dependențe necesare pentru a vă asigura că toate dependențele sunt instalate pentru acest port. De asemenea, asigurați-vă că aveți un mediu funcțional pentru gcc și GNU make. Pentru exemplul de mai jos s-a folosit Ubuntu 20.04, dar și alte sisteme unix ar trebui să funcționeze cu mici modificări:

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

apoi construiți:

$ cd ports/unix
$ make submodules
$ make

Dacă MicroPython s-a construit corect, ar trebui să vedeți următoarele:

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

Acum rulați-l:

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

Construirea portului Windows

Portul Windows include un fișier de proiect Visual Studio micropython.vcxproj pe care îl puteți folosi pentru a construi micropython.exe. Acesta poate fi deschis în Visual Studio sau construit din linia de comandă folosind msbuild. Alternativ, poate fi construit folosind mingw, fie în Windows cu Cygwin, fie pe Linux. Consultați documentația portului windows pentru mai multe informații.

Construirea portului STM32

La fel ca în cazul portului Unix, trebuie să instalați câteva dependențe necesare, așa cum se detaliază în secțiunea Dependențe necesare, apoi să construiți:

$ cd ports/stm32
$ make submodules
$ make

Vă rugăm să consultați documentația stm32 pentru mai multe detalii despre scrierea firmware-ului în memoria flash.

Notă

Consultați Dependențe necesare pentru a vă asigura că toate dependențele sunt instalate pentru acest port. Este necesar cross-compilatorul. arm-none-eabi-gcc ar trebui să fie de asemenea în $PATH sau specificat manual prin CROSS_COMPILE, fie prin setarea variabilei de mediu, fie în argumentele liniei de comandă make.

Puteți de asemenea să specificați ce placă să folosiți:

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

Consultați ports/stm32/boards pentru plăcile disponibile, de exemplu „OPENMV4” sau „OPENMV4P”.

Construirea documentației

Documentația MicroPython este creată folosind Sphinx. Dacă ați instalat deja Python, instalați Sphinx folosind pip. Este recomandat să folosiți un mediu virtual:

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

Navigați la directorul docs:

$ cd docs

Construiți documentația:

$ make html

Deschideți docs/build/html/index.html în browserul dumneavoastră pentru a vizualiza documentația local. Consultați documentația despre importarea documentației dumneavoastră pentru a folosi Read the Docs.

Rularea testelor

Pentru a rula toate testele din suita de teste pe portul Unix, folosiți:

$ cd ports/unix
$ make test

Pentru a rula o selecție de teste pe o placă/dispozitiv conectat prin USB, folosiți:

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

Consultați de asemenea Scrierea testelor.

Ținte make suplimentare pentru dezvoltatori

În toate porturile bazate pe make există o țintă pentru a afișa dimensiunea unui anumit fișier obiect. Atunci când o modificare este limitată la un singur fișier, acest lucru este util la testarea variantelor pentru a găsi alternative mai mici.

De exemplu, pentru a afișa dimensiunea objstr.o din directorul py/ la realizarea unei construcții standard unix:

$ make build-standard/py/objstr.sz

În mod similar, există o țintă pentru a salva versiunea preprocesată a unui fișier:

$ make build-standard/py/objstr.pp

În ports/unix există ținte suplimentare legate de rularea testelor:

$ 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

Folosirea ci.sh local

MicroPython folosește GitHub Actions pentru integrare continuă. Pentru a reduce dependența de un anumit sistem CI, pașii efectivi de construire pentru build-urile bazate pe Unix se află în fișierul tools/ci.sh. Acesta poate fi folosit și ca script pe stațiile de lucru ale dezvoltatorilor, cu unele rezerve:

  • Pentru majoritatea pașilor se presupune un sistem Ubuntu/Debian similar celui folosit în timpul CI.

  • Unii pași specifici presupun anumite versiuni de Ubuntu.

  • Pașii de configurare pot apela managerul de pachete al sistemului pentru a instala pachete, a descărca și instala software de pe internet etc.

Pentru a obține un mesaj de utilizare care include lista comenzilor, rulați:

$ tools/ci.sh --help

Ca exemplu, puteți construi și testa portul minimal unix cu:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Dacă folosiți shell-ul bash, puteți adăuga o comandă ci cu completare automată prin tab:

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

Pentru shell-ul zsh, înlocuiți --bash-completion cu --zsh-completion. Pentru shell-ul fish, înlocuiți --bash-completion cu --fish-completion.

Apoi, tastând:

$ ci unix_cov<tab>

Aceasta va completa numele pasului ci la unix_coverage_. Apăsând tab a doua oară se va afișa lista pașilor care se potrivesc:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Structura directoarelor

Există câteva directoare de reținut în privința locului unde se află anumite detalii de implementare. Următoarea este o defalcare a directoarelor de nivel superior din codul sursă.

py

Conține compilatorul, mediul de execuție și implementarea bibliotecii de bază.

mpy-cross

Conține cross-compilatorul MicroPython care precompilează scripturile Python în bytecode.

ports

Cod pentru toate versiunile de MicroPython aferente porturilor acceptate.

lib

Biblioteci C de nivel scăzut folosite de orice port, în mare parte biblioteci terțe.

drivers

Conține drivere pentru hardware specific, concepute pentru a funcționa pe mai multe porturi.

extmod

Conține o implementare în C a mai multor module care nu fac parte din nucleu.

docs

Conține documentația standard disponibilă la https://docs.micropython.org/.

tests

O implementare a suitei de teste.

tools

Conține scripturi folosite de procesul de construire și CI, precum și instrumente pentru utilizatori, cum ar fi mpremote.

examples

Cod exemplu pentru construirea MicroPython ca bibliotecă, precum și module native.