Aan de slag

Deze gids beschrijft stap voor stap hoe je versiebeheer instelt, een kopie van de broncode voor een port verkrijgt en bouwt, de documentatie bouwt, tests uitvoert, en geeft een beschrijving van de mappenstructuur van de MicroPython-codebase.

Versiebeheer met git

MicroPython wordt gehost op GitHub en gebruikt Git voor versiebeheer. De workflow is zo opgezet dat code wordt opgehaald van en gepusht naar de hoofdrepository. Installeer de betreffende versie van Git voor jouw besturingssysteem om de rest van de stappen te kunnen volgen.

Notitie

Raadpleeg voor de installatie-instructies de Git-installatie-instructies. Leer de basis git-commando’s in dit Git Handbook of via andere bronnen op het internet.

Notitie

Er is een .git-blame-ignore-revs-bestand inbegrepen dat voorkomt dat de uitvoer van git blame onoverzichtelijk wordt door commits die alleen code opmaken maar geen functionele wijzigingen bevatten. Zie de git blame-documentatie over hoe je dit gebruikt.

De code ophalen

Het wordt aanbevolen om voor je ontwikkeldoeleinden een fork van de MicroPython-repository te onderhouden. Het verkrijgen van de broncode omvat het volgende:

  1. Fork de repository https://github.com/micropython/micropython

  2. Je hebt nu een fork op <https://github.com/<your-user-name>/micropython>.

  3. Kloon de geforkte repository met het volgende commando:

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

Configureer vervolgens de externe repositories zodat je kunt samenwerken aan het MicroPython-project.

Configureer de remote upstream:

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

Het is gebruikelijk om upstream en origin op een geforkte repository te configureren om het delen van codewijzigingen te vergemakkelijken. Je kunt je eigen indeling aanhouden, maar het wordt aanbevolen om origin te laten verwijzen naar je fork en upstream naar de hoofd-MicroPython-repository.

Na de bovenstaande configuratie zou je opzet er ongeveer zo uit moeten zien:

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

Je zou nu een kopie van de broncode moeten hebben. Standaard wijs je naar de master-branch. Ter voorbereiding op verdere ontwikkeling wordt het aanbevolen om op een ontwikkelbranch te werken.

$ git checkout -b dev-branch

Je kunt deze elke gewenste naam geven. Je moet MicroPython opnieuw compileren telkens wanneer je naar een andere branch wisselt.

De code compileren en bouwen

Bij het compileren van MicroPython compileer je een specifieke port, meestal gericht op een specifiek board. Begin met het installeren van de vereiste afhankelijkheden. Bouw vervolgens de MicroPython-cross-compiler voordat je succesvol kunt compileren en bouwen. Dit geldt specifiek wanneer je Linux gebruikt om te compileren. De Windows-instructies worden in een later gedeelte gegeven.

Vereiste afhankelijkheden

Installeer de vereiste afhankelijkheden voor Linux:

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

Voor de stm32-port is de ARM-cross-compiler vereist:

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

Zie de ARM GCC toolchain voor de nieuwste details.

Python 3 is ook vereist. Controleer of je Python beschikbaar hebt op je systeem:

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

Alle ondersteunde ports hebben verschillende afhankelijkheidsvereisten; zie hun respectievelijke readme-bestanden.

De MicroPython-cross-compiler bouwen

Bijna alle ports vereisen dat je eerst mpy-cross bouwt om de Python-code voor te compileren die in de port-firmware wordt opgenomen:

$ cd mpy-cross
$ make

Notitie

Merk op dat mpy-cross gebouwd moet worden voor de hostarchitectuur en niet voor de doelarchitectuur.

Als het succesvol is gebouwd, zou je een bericht moeten zien dat hierop lijkt:

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

Notitie

Gebruik make -C mpy-cross om de cross-compiler in één opdracht te bouwen zonder naar de map mpy-cross te gaan; anders moet je cd .. uitvoeren voor de volgende stappen.

De Unix-port van MicroPython bouwen

De Unix-port is een versie van MicroPython die draait op Linux, macOS en andere Unix-achtige besturingssystemen. Hij is uiterst nuttig voor het ontwikkelen van MicroPython, omdat je je code niet naar een apparaat hoeft te deployen om hem te testen. In veel opzichten werkt hij net als het python-binary van CPython.

Om voor de Unix-port te bouwen, zorg je ervoor dat alle Linux-gerelateerde afhankelijkheden zijn geïnstalleerd zoals beschreven in het gedeelte over vereiste afhankelijkheden. Zie Vereiste afhankelijkheden om er zeker van te zijn dat alle afhankelijkheden voor deze port zijn geïnstalleerd. Zorg er ook voor dat je een werkende omgeving hebt voor gcc en GNU make. Voor het onderstaande voorbeeld is Ubuntu 20.04 gebruikt, maar andere unix-systemen zouden met weinig aanpassingen ook moeten werken:

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

bouw vervolgens:

$ cd ports/unix
$ make submodules
$ make

Als MicroPython correct is gebouwd, zou je het volgende moeten zien:

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

Voer het nu uit:

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

De Windows-port bouwen

De Windows-port bevat een Visual Studio-projectbestand micropython.vcxproj dat je kunt gebruiken om micropython.exe te bouwen. Het kan worden geopend in Visual Studio of vanaf de opdrachtregel worden gebouwd met msbuild. Als alternatief kan het worden gebouwd met mingw, hetzij in Windows met Cygwin, hetzij op Linux. Zie de documentatie van de Windows-port voor meer informatie.

De STM32-port bouwen

Net als bij de Unix-port moet je enkele vereiste afhankelijkheden installeren zoals beschreven in het gedeelte Vereiste afhankelijkheden, en vervolgens bouwen:

$ cd ports/stm32
$ make submodules
$ make

Raadpleeg de stm32-documentatie voor meer details over het flashen van de firmware.

Notitie

Zie Vereiste afhankelijkheden om er zeker van te zijn dat alle afhankelijkheden voor deze port zijn geïnstalleerd. De cross-compiler is nodig. arm-none-eabi-gcc moet ook in het $PATH staan of handmatig worden opgegeven via CROSS_COMPILE, hetzij door de omgevingsvariabele in te stellen, hetzij via de opdrachtregelargumenten van make.

Je kunt ook opgeven welk board je wilt gebruiken:

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

Zie ports/stm32/boards voor de beschikbare boards, bijv. “OPENMV4” of “OPENMV4P”.

De documentatie bouwen

De MicroPython-documentatie wordt gemaakt met Sphinx. Als je Python al hebt geïnstalleerd, installeer dan Sphinx met pip. Het wordt aanbevolen om een virtuele omgeving te gebruiken:

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

Navigeer naar de map docs:

$ cd docs

Bouw de documentatie:

$ make html

Open docs/build/html/index.html in je browser om de documentatie lokaal te bekijken. Raadpleeg de documentatie over het importeren van je documentatie om Read the Docs te gebruiken.

De tests uitvoeren

Om alle tests in de testsuite op de Unix-port uit te voeren, gebruik je:

$ cd ports/unix
$ make test

Om een selectie van tests uit te voeren op een board/apparaat dat via USB is verbonden, gebruik je:

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

Zie ook Tests schrijven.

Aanvullende make-targets voor ontwikkelaars

In alle op make gebaseerde ports is er een target om de grootte van een specifiek objectbestand af te drukken. Wanneer een wijziging beperkt blijft tot één bestand, is dit nuttig bij het testen van variaties om kleinere alternatieven te vinden.

Om bijvoorbeeld de grootte van objstr.o in de map py/ af te drukken bij het maken van een unix-standaardbuild:

$ make build-standard/py/objstr.sz

Op vergelijkbare wijze is er een target om de voorbewerkte versie van een bestand op te slaan:

$ make build-standard/py/objstr.pp

In ports/unix zijn er aanvullende targets met betrekking tot het uitvoeren van tests:

$ 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 lokaal gebruiken

MicroPython gebruikt GitHub Actions voor continuous integration. Om de afhankelijkheid van een specifiek CI-systeem te verminderen, staan de feitelijke buildstappen voor Unix-gebaseerde builds in het bestand tools/ci.sh. Dit kan ook als script worden gebruikt op de desktops van ontwikkelaars, met de volgende kanttekeningen:

  • Voor de meeste stappen wordt uitgegaan van een Ubuntu/Debian-systeem dat lijkt op het systeem dat tijdens CI wordt gebruikt.

  • Sommige specifieke stappen gaan uit van specifieke Ubuntu-versies.

  • De setup-stappen kunnen de systeempakketbeheerder aanroepen om pakketten te installeren, software van het internet te downloaden en te installeren, enzovoort.

Om een gebruiksbericht inclusief de lijst met commando’s te krijgen, voer je uit:

$ tools/ci.sh --help

Als voorbeeld kun je de unix-minimal-port bouwen en testen met:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Als je de bash-shell gebruikt, kun je een ci-commando met tab-aanvulling toevoegen:

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

Voor de zsh-shell vervang je --bash-completion door --zsh-completion. Voor de fish-shell vervang je --bash-completion door --fish-completion.

Vervolgens, door te typen:

$ ci unix_cov<tab>

Dit vult de ci-stapnaam aan tot unix_coverage_. Door een tweede keer op tab te drukken wordt de lijst met overeenkomende stappen weergegeven:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Mappenstructuur

Er zijn een paar mappen die het vermelden waard zijn wat betreft waar bepaalde implementatiedetails zich bevinden. Hieronder volgt een uitsplitsing van de mappen op het hoogste niveau in de broncode.

py

Bevat de compiler, runtime en de implementatie van de kernbibliotheek.

mpy-cross

Bevat de MicroPython-cross-compiler die de Python-scripts voorcompileert naar bytecode.

ports

Code voor alle versies van MicroPython voor de ondersteunde ports.

lib

Low-level C-bibliotheken die door elke port worden gebruikt en die voornamelijk bibliotheken van derden zijn.

drivers

Bevat drivers voor specifieke hardware, bedoeld om over meerdere ports te werken.

extmod

Bevat een C-implementatie van meer niet-kernmodules.

docs

Bevat de standaarddocumentatie die te vinden is op https://docs.micropython.org/.

tests

Een implementatie van de testsuite.

tools

Bevat scripts die worden gebruikt door het build- en CI-proces, evenals gebruikerstools zoals mpremote.

examples

Voorbeeldcode voor het bouwen van MicroPython als bibliotheek en voor native modules.