OpenMV MicroPython
Premiers pas¶
Ce guide décrit pas à pas la mise en place du contrôle de version, l’obtention et la compilation d’une copie du code source d’un portage, la génération de la documentation, l’exécution des tests, ainsi qu’une description de la structure des répertoires de la base de code MicroPython.
Contrôle de version avec git¶
MicroPython est hébergé sur GitHub et utilise Git pour le contrôle de version. Le flux de travail consiste à récupérer (pull) et à envoyer (push) le code depuis et vers le dépôt principal. Installez la version de Git correspondant à votre système d’exploitation pour suivre la suite des étapes.
Note
Pour une référence sur les instructions d’installation, veuillez consulter les instructions d’installation de Git. Familiarisez-vous avec les commandes git de base dans ce Git Handbook ou via toute autre source sur Internet.
Note
Un fichier .git-blame-ignore-revs est inclus afin d’éviter que la sortie de git blame ne soit encombrée par des commits qui ne concernent que la mise en forme du code sans changement fonctionnel. Consultez la documentation de git blame pour savoir comment l’utiliser.
Obtenir le code¶
Il est recommandé de maintenir un fork du dépôt MicroPython pour vos besoins de développement. Le processus d’obtention du code source comprend les étapes suivantes :
Forkez le dépôt https://github.com/micropython/micropython
Vous disposerez alors d’un fork à l’adresse <https://github.com/<your-user-name>/micropython>.
Clonez le dépôt forké à l’aide de la commande suivante :
$ git clone https://github.com/<your-user-name>/micropython
Ensuite, configurez les dépôts distants afin de pouvoir collaborer sur le projet MicroPython.
Configurez le dépôt distant upstream :
$ cd micropython
$ git remote add upstream https://github.com/micropython/micropython
Il est courant de configurer upstream et origin sur un dépôt forké pour faciliter le partage des modifications de code. Vous pouvez conserver votre propre correspondance, mais il est recommandé que origin pointe vers votre fork et upstream vers le dépôt MicroPython principal.
Après la configuration ci-dessus, votre installation devrait ressembler à ceci :
$ 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)
Vous devriez maintenant disposer d’une copie du code source. Par défaut, vous pointez vers la branche master. Pour préparer la suite du développement, il est recommandé de travailler sur une branche de développement.
$ git checkout -b dev-branch
Vous pouvez lui donner n’importe quel nom. Vous devrez recompiler MicroPython chaque fois que vous changerez de branche.
Compiler et générer le code¶
Lorsque vous compilez MicroPython, vous compilez un port spécifique, ciblant généralement une board spécifique. Commencez par installer les dépendances requises. Compilez ensuite le compilateur croisé MicroPython avant de pouvoir compiler et générer avec succès. Cela s’applique en particulier lorsque vous compilez sous Linux. Les instructions pour Windows sont fournies dans une section ultérieure.
Dépendances requises¶
Installez les dépendances requises pour Linux :
$ sudo apt-get install build-essential libffi-dev git pkg-config
Pour le portage stm32, le compilateur croisé ARM est requis :
$ sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi
Consultez la chaîne d’outils ARM GCC pour les derniers détails.
Python 3 est également requis. Vérifiez que Python est disponible sur votre système :
$ 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.
>>>
Tous les portages pris en charge ont des exigences de dépendances différentes ; consultez leurs fichiers readme respectifs.
Compilation du compilateur croisé MicroPython¶
Presque tous les portages nécessitent de compiler d’abord mpy-cross pour effectuer la pré-compilation du code Python qui sera inclus dans le micrologiciel du portage :
$ cd mpy-cross
$ make
Note
Notez que mpy-cross doit être compilé pour l’architecture hôte et non pour l’architecture cible.
Si la compilation a réussi, vous devriez voir un message semblable à celui-ci :
LINK mpy-cross
text data bss dec hex filename
279328 776 880 280984 44998 mpy-cross
Note
Utilisez make -C mpy-cross pour compiler le compilateur croisé en une seule instruction sans vous déplacer dans le répertoire mpy-cross ; sinon, vous devrez faire cd .. pour les étapes suivantes.
Compilation du portage Unix de MicroPython¶
Le portage Unix est une version de MicroPython qui s’exécute sous Linux, macOS et d’autres systèmes d’exploitation de type Unix. Il est extrêmement utile pour développer MicroPython car il évite d’avoir à déployer votre code sur un appareil pour le tester. À bien des égards, il fonctionne comme le binaire python de CPython.
Pour compiler le portage Unix, assurez-vous que toutes les dépendances liées à Linux sont installées comme détaillé dans la section sur les dépendances requises. Consultez la section Dépendances requises pour vous assurer que toutes les dépendances de ce portage sont installées. Assurez-vous également de disposer d’un environnement fonctionnel pour gcc et GNU make. Ubuntu 20.04 a été utilisé pour l’exemple ci-dessous, mais d’autres systèmes Unix devraient fonctionner avec peu de modifications :
$ 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.
puis compilez :
$ cd ports/unix
$ make submodules
$ make
Si MicroPython a été compilé correctement, vous devriez voir ce qui suit :
LINK micropython
text data bss dec hex filename
412033 5680 2496 420209 66971 micropython
Exécutez-le maintenant :
$ ./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
>>>
Compilation du portage Windows¶
Le portage Windows comprend un fichier de projet Visual Studio micropython.vcxproj que vous pouvez utiliser pour compiler micropython.exe. Il peut être ouvert dans Visual Studio ou compilé en ligne de commande à l’aide de msbuild. Il peut également être compilé avec mingw, soit sous Windows avec Cygwin, soit sous Linux. Consultez la documentation du portage Windows pour plus d’informations.
Compilation du portage STM32¶
Comme pour le portage Unix, vous devez installer certaines dépendances requises comme détaillé dans la section Dépendances requises, puis compiler :
$ cd ports/stm32
$ make submodules
$ make
Veuillez consulter la documentation stm32 pour plus de détails sur le flashage du micrologiciel.
Note
Consultez la section Dépendances requises pour vous assurer que toutes les dépendances de ce portage sont installées. Le compilateur croisé est nécessaire. arm-none-eabi-gcc doit également se trouver dans le $PATH ou être spécifié manuellement via CROSS_COMPILE, soit en définissant la variable d’environnement, soit dans les arguments de la ligne de commande make.
Vous pouvez également spécifier la carte à utiliser :
$ cd ports/stm32
$ make BOARD=<board> submodules
$ make BOARD=<board>
Consultez ports/stm32/boards pour connaître les cartes disponibles, par exemple « OPENMV4 » ou « OPENMV4P ».
Génération de la documentation¶
La documentation de MicroPython est créée à l’aide de Sphinx. Si vous avez déjà installé Python, installez alors Sphinx à l’aide de pip. Il est recommandé d’utiliser un environnement virtuel :
$ python3 -m venv env
$ source env/bin/activate
$ pip install -r docs/requirements.txt
Placez-vous dans le répertoire docs :
$ cd docs
Générez la documentation :
$ make html
Ouvrez docs/build/html/index.html dans votre navigateur pour consulter la documentation en local. Reportez-vous à la documentation sur l”importation de votre documentation pour utiliser Read the Docs.
Exécution des tests¶
Pour exécuter tous les tests de la suite de tests sur le portage Unix, utilisez :
$ cd ports/unix
$ make test
Pour exécuter une sélection de tests sur une carte/un appareil connecté via USB, utilisez :
$ cd tests
$ ./run-tests.py -t /dev/ttyACM0
Voir aussi Écrire des tests.
Cibles make supplémentaires pour les développeurs¶
Dans tous les portages basés sur make, il existe une cible permettant d’afficher la taille d’un fichier objet spécifique. Lorsqu’une modification est confinée à un seul fichier, cela est utile pour tester des variations afin de trouver des alternatives plus petites.
Par exemple, pour afficher la taille de objstr.o dans le répertoire py/ lors d’une compilation standard unix :
$ make build-standard/py/objstr.sz
De même, il existe une cible permettant de sauvegarder la version pré-traitée d’un fichier :
$ make build-standard/py/objstr.pp
Dans ports/unix, il existe des cibles supplémentaires liées à l’exécution des 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
Utiliser ci.sh en local¶
MicroPython utilise GitHub Actions pour l’intégration continue. Pour réduire la dépendance à un système de CI particulier, les étapes de compilation réelles des builds basés sur Unix se trouvent dans le fichier tools/ci.sh. Celui-ci peut également être utilisé comme script sur les postes de développeurs, avec certaines réserves :
Pour la plupart des étapes, on suppose un système Ubuntu/Debian semblable à celui utilisé lors de la CI.
Certaines étapes spécifiques supposent des versions précises d’Ubuntu.
Les étapes de configuration peuvent invoquer le gestionnaire de paquets du système pour installer des paquets, télécharger et installer des logiciels depuis Internet, etc.
Pour obtenir un message d’utilisation incluant la liste des commandes, exécutez :
$ tools/ci.sh --help
À titre d’exemple, vous pouvez compiler et tester le portage unix minimal avec :
$ tools/ci.sh unix_minimal_build unix_minimal_run_tests
Si vous utilisez le shell bash, vous pouvez ajouter une commande ci avec complétion par tabulation :
$ eval $(tools/ci.sh --bash-completion)
Pour le shell zsh, remplacez --bash-completion par --zsh-completion. Pour le shell fish, remplacez --bash-completion par --fish-completion.
Ensuite, en tapant :
$ ci unix_cov<tab>
Cela complétera le nom de l’étape ci en unix_coverage_. Appuyer une deuxième fois sur la touche de tabulation affichera la liste des étapes correspondantes :
$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…
Structure des dossiers¶
Il y a quelques répertoires à connaître quant à l’emplacement de certains détails d’implémentation. Voici une description des dossiers de premier niveau du code source.
py
Contient le compilateur, le moteur d’exécution et l’implémentation de la bibliothèque de base.
mpy-cross
Contient le compilateur croisé MicroPython qui pré-compile les scripts Python en bytecode.
ports
Code de toutes les versions de MicroPython pour les portages pris en charge.
lib
Bibliothèques C de bas niveau utilisées par n’importe quel portage, qui sont pour la plupart des bibliothèques tierces.
drivers
Contient les pilotes pour du matériel spécifique, conçus pour fonctionner sur plusieurs portages.
extmod
Contient une implémentation en C de modules supplémentaires non essentiels.
docs
Contient la documentation standard disponible à l’adresse https://docs.micropython.org/.
tests
Une implémentation de la suite de tests.
tools
Contient les scripts utilisés par le processus de compilation et de CI, ainsi que des outils utilisateur tels que
mpremote.
examples
Exemple de code pour compiler MicroPython en tant que bibliothèque ainsi que des modules natifs.