Erste Schritte

Diese Anleitung beschreibt Schritt für Schritt das Einrichten der Versionsverwaltung, das Beziehen und Erstellen einer Kopie des Quellcodes für einen Port, das Erstellen der Dokumentation, das Ausführen von Tests sowie eine Beschreibung der Verzeichnisstruktur der MicroPython-Codebasis.

Versionsverwaltung mit git

MicroPython wird auf GitHub gehostet und verwendet Git zur Versionsverwaltung. Der Arbeitsablauf ist so gestaltet, dass Code aus dem Haupt-Repository gezogen und dorthin übertragen wird. Installieren Sie die für Ihr Betriebssystem passende Version von Git, um die folgenden Schritte nachvollziehen zu können.

Bemerkung

Eine Referenz für die Installationsanweisungen finden Sie in der Git-Installationsanleitung. Die grundlegenden git-Befehle lernen Sie in diesem Git-Handbuch oder anhand anderer Quellen im Internet kennen.

Bemerkung

Eine Datei .git-blame-ignore-revs ist enthalten, die verhindert, dass die Ausgabe von git blame durch Commits unübersichtlich wird, die nur der Formatierung von Code dienen, aber keine funktionalen Änderungen enthalten. Wie Sie diese verwenden, lesen Sie in der git-blame-Dokumentation.

Den Code beziehen

Es wird empfohlen, für Ihre Entwicklungszwecke einen Fork des MicroPython-Repositorys zu pflegen. Der Vorgang zum Beziehen des Quellcodes umfasst Folgendes:

  1. Forken Sie das Repository https://github.com/micropython/micropython

  2. Sie haben nun einen Fork unter <https://github.com/<your-user-name>/micropython>.

  3. Klonen Sie das geforkte Repository mit dem folgenden Befehl:

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

Anschließend konfigurieren Sie die Remote-Repositorys, um am MicroPython-Projekt mitarbeiten zu können.

Remote upstream konfigurieren:

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

Üblicherweise werden upstream und origin in einem geforkten Repository konfiguriert, um das Teilen von Codeänderungen zu erleichtern. Sie können Ihre eigene Zuordnung pflegen, es wird jedoch empfohlen, dass origin auf Ihren Fork und upstream auf das Haupt-MicroPython-Repository verweist.

Nach der obigen Konfiguration sollte Ihre Einrichtung in etwa so aussehen:

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

Sie sollten nun über eine Kopie des Quellcodes verfügen. Standardmäßig verweisen Sie auf den master-Branch. Zur Vorbereitung der weiteren Entwicklung wird empfohlen, auf einem Entwicklungs-Branch zu arbeiten.

$ git checkout -b dev-branch

Sie können ihm einen beliebigen Namen geben. Sie müssen MicroPython jedes Mal neu kompilieren, wenn Sie zu einem anderen Branch wechseln.

Den Code kompilieren und erstellen

Beim Kompilieren von MicroPython kompilieren Sie einen bestimmten port, der üblicherweise auf ein bestimmtes board abzielt. Beginnen Sie mit der Installation der erforderlichen Abhängigkeiten. Erstellen Sie anschließend den MicroPython-Cross-Compiler, bevor Sie erfolgreich kompilieren und erstellen können. Dies gilt insbesondere beim Kompilieren unter Linux. Die Anweisungen für Windows finden Sie in einem späteren Abschnitt.

Erforderliche Abhängigkeiten

Installieren Sie die erforderlichen Abhängigkeiten für Linux:

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

Für den stm32-Port ist der ARM-Cross-Compiler erforderlich:

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

Aktuelle Details finden Sie in der ARM-GCC-Toolchain.

Python 3 ist ebenfalls erforderlich. Prüfen Sie, ob Python auf Ihrem System verfügbar ist:

$ 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 unterstützten Ports haben unterschiedliche Abhängigkeitsanforderungen, siehe ihre jeweiligen readme-Dateien.

Den MicroPython-Cross-Compiler erstellen

Fast alle Ports erfordern, dass zunächst mpy-cross erstellt wird, um die Vorkompilierung von Python-Code durchzuführen, der in die Port-Firmware aufgenommen wird:

$ cd mpy-cross
$ make

Bemerkung

Beachten Sie, dass mpy-cross für die Host-Architektur und nicht für die Zielarchitektur erstellt werden muss.

Wenn der Build erfolgreich war, sollten Sie eine Meldung ähnlich dieser sehen:

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

Bemerkung

Verwenden Sie make -C mpy-cross, um den Cross-Compiler in einer einzigen Anweisung zu erstellen, ohne in das mpy-cross-Verzeichnis zu wechseln; andernfalls müssen Sie für die nächsten Schritte cd .. ausführen.

Den Unix-Port von MicroPython erstellen

Der Unix-Port ist eine Version von MicroPython, die unter Linux, macOS und anderen unixähnlichen Betriebssystemen läuft. Er ist äußerst nützlich für die Entwicklung von MicroPython, da man so vermeidet, seinen Code zum Testen auf ein Gerät übertragen zu müssen. In vielerlei Hinsicht funktioniert er ganz ähnlich wie das python-Binary von CPython.

Stellen Sie zum Erstellen des Unix-Ports sicher, dass alle Linux-bezogenen Abhängigkeiten installiert sind, wie im Abschnitt zu den erforderlichen Abhängigkeiten beschrieben. Siehe Erforderliche Abhängigkeiten, um sicherzustellen, dass alle Abhängigkeiten für diesen Port installiert sind. Stellen Sie außerdem sicher, dass Sie eine funktionierende Umgebung für gcc und GNU make haben. Für das folgende Beispiel wurde Ubuntu 20.04 verwendet, andere Unix-Systeme sollten jedoch mit geringfügigen Anpassungen ebenfalls funktionieren:

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

dann erstellen:

$ cd ports/unix
$ make submodules
$ make

Wenn MicroPython korrekt erstellt wurde, sollten Sie Folgendes sehen:

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

Führen Sie es nun aus:

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

Den Windows-Port erstellen

Der Windows-Port enthält eine Visual-Studio-Projektdatei micropython.vcxproj, mit der Sie micropython.exe erstellen können. Sie kann in Visual Studio geöffnet oder über die Befehlszeile mit msbuild erstellt werden. Alternativ kann sie mit mingw erstellt werden, entweder unter Windows mit Cygwin oder unter Linux. Weitere Informationen finden Sie in der Windows-Port-Dokumentation.

Den STM32-Port erstellen

Wie beim Unix-Port müssen Sie einige erforderliche Abhängigkeiten installieren, wie im Abschnitt Erforderliche Abhängigkeiten beschrieben, und dann erstellen:

$ cd ports/stm32
$ make submodules
$ make

Weitere Details zum Flashen der Firmware finden Sie in der stm32-Dokumentation.

Bemerkung

Siehe Erforderliche Abhängigkeiten, um sicherzustellen, dass alle Abhängigkeiten für diesen Port installiert sind. Der Cross-Compiler wird benötigt. arm-none-eabi-gcc sollte sich ebenfalls im $PATH befinden oder manuell über CROSS_COMPILE angegeben werden, entweder durch Setzen der Umgebungsvariable oder in den Befehlszeilenargumenten von make.

Sie können auch angeben, welches Board verwendet werden soll:

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

Die verfügbaren Boards finden Sie unter ports/stm32/boards, z. B. „OPENMV4“ oder „OPENMV4P“.

Die Dokumentation erstellen

Die MicroPython-Dokumentation wird mit Sphinx erstellt. Wenn Sie Python bereits installiert haben, installieren Sie Sphinx mit pip. Es wird empfohlen, eine virtuelle Umgebung zu verwenden:

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

Navigieren Sie in das docs-Verzeichnis:

$ cd docs

Erstellen Sie die Dokumentation:

$ make html

Öffnen Sie docs/build/html/index.html in Ihrem Browser, um die Dokumentation lokal anzuzeigen. Wie Sie Read the Docs verwenden, lesen Sie in der Dokumentation zum Importieren Ihrer Dokumentation.

Die Tests ausführen

Um alle Tests der Testsuite auf dem Unix-Port auszuführen, verwenden Sie:

$ cd ports/unix
$ make test

Um eine Auswahl von Tests auf einem über USB verbundenen Board/Gerät auszuführen, verwenden Sie:

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

Siehe auch Tests schreiben.

Zusätzliche make-Targets für Entwickler

In allen make-basierten Ports gibt es ein Target, um die Größe einer bestimmten Objektdatei auszugeben. Wenn eine Änderung auf eine einzelne Datei beschränkt ist, ist dies nützlich, um Varianten zu testen und kleinere Alternativen zu finden.

Um beispielsweise die Größe von objstr.o im py/-Verzeichnis bei einem Unix-Standard-Build auszugeben:

$ make build-standard/py/objstr.sz

Ebenso gibt es ein Target, um die vorverarbeitete Version einer Datei zu speichern:

$ make build-standard/py/objstr.pp

In ports/unix gibt es zusätzliche Targets im Zusammenhang mit dem Ausführen von 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 lokal verwenden

MicroPython verwendet GitHub Actions für Continuous Integration. Um die Abhängigkeit von einem bestimmten CI-System zu reduzieren, befinden sich die eigentlichen Build-Schritte für Unix-basierte Builds in der Datei tools/ci.sh. Diese kann mit einigen Einschränkungen auch als Skript auf Entwickler-Desktops verwendet werden:

  • Für die meisten Schritte wird ein Ubuntu/Debian-System ähnlich dem während des CI verwendeten vorausgesetzt.

  • Einige spezifische Schritte setzen bestimmte Ubuntu-Versionen voraus.

  • Die Setup-Schritte können den Paketmanager des Systems aufrufen, um Pakete zu installieren, Software aus dem Internet herunterzuladen und zu installieren usw.

Um eine Verwendungsmeldung einschließlich der Liste der Befehle zu erhalten, führen Sie aus:

$ tools/ci.sh --help

Als Beispiel können Sie den minimalen Unix-Port wie folgt erstellen und testen:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Wenn Sie die bash-Shell verwenden, können Sie einen ci-Befehl mit Tab-Vervollständigung hinzufügen:

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

Ersetzen Sie für die zsh-Shell --bash-completion durch --zsh-completion. Ersetzen Sie für die fish-Shell --bash-completion durch --fish-completion.

Wenn Sie dann Folgendes eingeben:

$ ci unix_cov<tab>

Dies vervollständigt den Namen des ci-Schritts zu unix_coverage_. Ein zweites Drücken der Tab-Taste zeigt die Liste der passenden Schritte an:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Ordnerstruktur

Es gibt einige Verzeichnisse, die im Hinblick darauf zu beachten sind, wo sich bestimmte Implementierungsdetails befinden. Im Folgenden werden die obersten Ordner im Quellcode aufgeschlüsselt.

py

Enthält die Implementierung von Compiler, Laufzeitumgebung und Kernbibliothek.

mpy-cross

Enthält den MicroPython-Cross-Compiler, der die Python-Skripte zu Bytecode vorkompiliert.

ports

Code für alle Versionen von MicroPython für die unterstützten Ports.

lib

Low-Level-C-Bibliotheken, die von beliebigen Ports verwendet werden und größtenteils Bibliotheken von Drittanbietern sind.

drivers

Enthält Treiber für bestimmte Hardware, die portübergreifend funktionieren sollen.

extmod

Enthält eine C-Implementierung weiterer Nicht-Kernmodule.

docs

Enthält die Standarddokumentation, die unter https://docs.micropython.org/ zu finden ist.

tests

Eine Implementierung der Testsuite.

tools

Enthält Skripte, die vom Build- und CI-Prozess verwendet werden, sowie Benutzerwerkzeuge wie mpremote.

examples

Beispielcode zum Erstellen von MicroPython als Bibliothek sowie für native Module.