Komma igång

Den här guiden beskriver steg för steg hur du ställer in versionshantering, hämtar och bygger en kopia av källkoden för en port, bygger dokumentationen, kör tester samt en beskrivning av katalogstrukturen i MicroPython-kodbasen.

Versionshantering med git

MicroPython finns på GitHub och använder Git för versionshantering. Arbetsflödet innebär att kod hämtas och skickas till och från huvudförrådet. Installera motsvarande version av Git för ditt operativsystem för att kunna följa de resterande stegen.

Anteckning

För en referens till installationsinstruktionerna, se Git installation instructions. Lär dig de grundläggande git-kommandona i denna Git Handbook eller från andra källor på internet.

Anteckning

En .git-blame-ignore-revs-fil är inkluderad som förhindrar att utdata från git blame blir rörigt av commits som endast handlar om kodformatering men inte har några funktionella ändringar. Se git blame documentation för hur du använder detta.

Hämta koden

Det rekommenderas att du underhåller en fork av MicroPython-förrådet för dina utvecklingsändamål. Processen för att hämta källkoden omfattar följande:

  1. Forka förrådet https://github.com/micropython/micropython

  2. Du har nu en fork på <https://github.com/<your-user-name>/micropython>.

  3. Klona det forkade förrådet med följande kommando:

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

Sedan, configure the remote repositories för att kunna samarbeta i MicroPython-projektet.

Konfigurera fjärrkällan upstream:

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

Det är vanligt att konfigurera upstream och origin på ett forkat förråd för att underlätta delning av kodändringar. Du kan upprätthålla din egen mappning, men det rekommenderas att origin pekar mot din fork och upstream mot huvudförrådet för MicroPython.

Efter ovanstående konfiguration bör din uppsättning likna detta:

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

Du bör nu ha en kopia av källkoden. Som standard pekar du mot master-grenen. För att förbereda för vidare utveckling rekommenderas det att du arbetar i en utvecklingsgren.

$ git checkout -b dev-branch

Du kan ge den vilket namn som helst. Du måste kompilera MicroPython varje gång du byter till en annan gren.

Kompilera och bygg koden

När du kompilerar MicroPython kompilerar du en specifik port, vanligtvis riktad mot ett specifikt board. Börja med att installera de nödvändiga beroendena. Bygg sedan korskompilatorn för MicroPython innan du kan kompilera och bygga med framgång. Detta gäller specifikt när du använder Linux för att kompilera. Instruktionerna för Windows finns i ett senare avsnitt.

Nödvändiga beroenden

Installera de nödvändiga beroendena för Linux:

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

För stm32-porten krävs ARM-korskompilatorn:

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

Se ARM GCC toolchain för de senaste detaljerna.

Python 3 krävs också. Kontrollera att du har Python tillgängligt på ditt system:

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

Alla stödda portar har olika beroendekrav, se deras respektive readme files.

Bygga korskompilatorn för MicroPython

Nästan alla portar kräver att mpy-cross byggs först för att förkompilera den Python-kod som ska inkluderas i portens firmware:

$ cd mpy-cross
$ make

Anteckning

Observera att mpy-cross måste byggas för värdarkitekturen och inte målarkitekturen.

Om bygget lyckades bör du se ett meddelande som liknar detta:

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

Anteckning

Använd make -C mpy-cross för att bygga korskompilatorn med ett enda kommando utan att flytta till katalogen mpy-cross, annars måste du köra cd .. inför nästa steg.

Bygga Unix-porten av MicroPython

Unix-porten är en version av MicroPython som körs på Linux, macOS och andra Unix-liknande operativsystem. Den är mycket användbar för att utveckla MicroPython eftersom den slipper kravet att distribuera din kod till en enhet för att testa den. På många sätt fungerar den ungefär som CPythons python-binärfil.

För att bygga för Unix-porten, se till att alla Linux-relaterade beroenden är installerade enligt beskrivningen i avsnittet om nödvändiga beroenden. Se Nödvändiga beroenden för att säkerställa att alla beroenden är installerade för denna port. Se även till att du har en fungerande miljö för gcc och GNU make. Ubuntu 20.04 har använts i exemplet nedan, men andra unix-system bör fungera med små ändringar:

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

bygg sedan:

$ cd ports/unix
$ make submodules
$ make

Om MicroPython byggdes korrekt bör du se följande:

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

Kör den nu:

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

Bygga Windows-porten

Windows-porten innehåller en Visual Studio-projektfil micropython.vcxproj som du kan använda för att bygga micropython.exe. Den kan öppnas i Visual Studio eller byggas från kommandoraden med msbuild. Alternativt kan den byggas med mingw, antingen i Windows med Cygwin eller på Linux. Se windows port documentation för mer information.

Bygga STM32-porten

Precis som med Unix-porten behöver du installera några nödvändiga beroenden enligt beskrivningen i avsnittet Nödvändiga beroenden, bygg sedan:

$ cd ports/stm32
$ make submodules
$ make

Se stm32 documentation för mer information om att flasha firmware.

Anteckning

Se Nödvändiga beroenden för att säkerställa att alla beroenden är installerade för denna port. Korskompilatorn behövs. arm-none-eabi-gcc bör också finnas i $PATH eller anges manuellt via CROSS_COMPILE, antingen genom att ställa in miljövariabeln eller i kommandoradsargumenten till make.

Du kan även ange vilket kort som ska användas:

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

Se ports/stm32/boards för de tillgängliga korten, t.ex. ”OPENMV4” eller ”OPENMV4P”.

Bygga dokumentationen

MicroPython-dokumentationen skapas med Sphinx. Om du redan har installerat Python, installera då Sphinx med pip. Det rekommenderas att du använder en virtuell miljö:

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

Navigera till katalogen docs:

$ cd docs

Bygg dokumentationen:

$ make html

Öppna docs/build/html/index.html i din webbläsare för att visa dokumentationen lokalt. Se dokumentationen om importing your documentation för att använda Read the Docs.

Köra testerna

För att köra alla tester i testsviten på Unix-porten, använd:

$ cd ports/unix
$ make test

För att köra ett urval av tester på ett kort/en enhet ansluten via USB, använd:

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

Se även Skriva tester.

Ytterligare make-mål för utvecklare

I alla make-baserade portar finns det ett mål för att skriva ut storleken på en specifik objektfil. När en ändring är begränsad till en enda fil är detta användbart vid testning av variationer för att hitta mindre alternativ.

Till exempel, för att skriva ut storleken på objstr.o i katalogen py/ vid ett standardbygge för unix:

$ make build-standard/py/objstr.sz

På liknande sätt finns det ett mål för att spara den förbehandlade versionen av en fil:

$ make build-standard/py/objstr.pp

I ports/unix finns det ytterligare mål kopplade till att köra tester:

$ 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

Använda ci.sh lokalt

MicroPython använder GitHub Actions för kontinuerlig integration. För att minska beroendet av något specifikt CI-system finns de faktiska byggstegen för Unix-baserade byggen i filen tools/ci.sh. Denna kan även användas som ett skript på utvecklares datorer, med vissa förbehåll:

  • För de flesta steg antas ett Ubuntu/Debian-system som liknar det som används under CI.

  • Vissa specifika steg förutsätter specifika Ubuntu-versioner.

  • Installationsstegen kan anropa systemets pakethanterare för att installera paket, ladda ner och installera programvara från internet osv.

För att få ett användningsmeddelande inklusive listan över kommandon, kör:

$ tools/ci.sh --help

Som ett exempel kan du bygga och testa unix minimal-porten med:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Om du använder bash-skalet kan du lägga till ett ci-kommando med tabbkomplettering:

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

För zsh-skalet, ersätt --bash-completion med --zsh-completion. För fish-skalet, ersätt --bash-completion med --fish-completion.

Skriv sedan:

$ ci unix_cov<tab>

Detta kompletterar ci-stegnamnet till unix_coverage_. Om du trycker på tab en andra gång visas listan över matchande steg:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Mappstruktur

Det finns ett par kataloger att notera när det gäller var vissa implementationsdetaljer finns. Följande är en uppdelning av topp-mapparna i källkoden.

py

Innehåller kompilatorn, körningsmiljön och implementationen av kärnbiblioteket.

mpy-cross

Innehåller korskompilatorn för MicroPython som förkompilerar Python-skripten till bytekod.

ports

Kod för alla versioner av MicroPython för de stödda portarna.

lib

Lågnivå-C-bibliotek som används av valfri port och som mestadels är tredjepartsbibliotek.

drivers

Innehåller drivrutiner för specifik hårdvara och är avsedda att fungera över flera portar.

extmod

Innehåller en C-implementation av fler icke-kärnmoduler.

docs

Innehåller standarddokumentationen som finns på https://docs.micropython.org/.

tests

En implementation av testsviten.

tools

Innehåller skript som används av bygg- och CI-processen, samt användarverktyg som mpremote.

examples

Exempelkod för att bygga MicroPython som ett bibliotek samt nativa moduler.