Primeros pasos

Esta guía describe paso a paso cómo configurar el control de versiones, obtener y compilar una copia del código fuente de un port, generar la documentación, ejecutar las pruebas, además de una descripción de la estructura de directorios del código base de MicroPython.

Control de versiones con git

MicroPython está alojado en GitHub y utiliza Git para el control de versiones. El flujo de trabajo consiste en obtener y enviar código desde y hacia el repositorio principal. Instala la versión correspondiente de Git para tu sistema operativo para poder seguir el resto de los pasos.

Nota

Para consultar las instrucciones de instalación, consulta las instrucciones de instalación de Git. Aprende los comandos básicos de git en este Manual de Git o en cualquier otra fuente de internet.

Nota

Se incluye un archivo .git-blame-ignore-revs que evita que la salida de git blame se sature con commits que solo formatean el código pero no implican cambios funcionales. Consulta la documentación de git blame para saber cómo usarlo.

Obtener el código

Se recomienda que mantengas un fork del repositorio de MicroPython para tus tareas de desarrollo. El proceso para obtener el código fuente incluye lo siguiente:

  1. Haz un fork del repositorio https://github.com/micropython/micropython

  2. Ahora tendrás un fork en <https://github.com/<your-user-name>/micropython>.

  3. Clona el repositorio bifurcado con el siguiente comando:

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

Luego, configura los repositorios remotos para poder colaborar en el proyecto MicroPython.

Configura el remoto upstream:

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

Es habitual configurar upstream y origin en un repositorio bifurcado para facilitar el intercambio de cambios de código. Puedes mantener tu propia asignación, pero se recomienda que origin apunte a tu fork y upstream al repositorio principal de MicroPython.

Tras la configuración anterior, tu entorno debería quedar similar a esto:

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

Ahora deberías tener una copia del código fuente. De forma predeterminada, estás apuntando a la rama master. Para prepararte para seguir desarrollando, se recomienda trabajar en una rama de desarrollo.

$ git checkout -b dev-branch

Puedes darle cualquier nombre. Tendrás que compilar MicroPython cada vez que cambies a una rama diferente.

Compilar y construir el código

Al compilar MicroPython, compilas un port específico, que normalmente apunta a una placa concreta. Empieza por instalar las dependencias necesarias. Luego, compila el compilador cruzado de MicroPython antes de poder compilar y construir correctamente. Esto aplica específicamente al compilar bajo Linux. Las instrucciones para Windows se proporcionan en una sección posterior.

Dependencias necesarias

Instala las dependencias necesarias para Linux:

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

Para el port stm32, se requiere el compilador cruzado de ARM:

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

Consulta la cadena de herramientas ARM GCC para conocer los detalles más recientes.

También se requiere Python 3. Comprueba que tienes Python disponible en tu sistema:

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

Todos los ports admitidos tienen distintos requisitos de dependencias; consulta sus respectivos archivos readme.

Compilar el compilador cruzado de MicroPython

Casi todos los ports requieren compilar primero mpy-cross para realizar la precompilación del código Python que se incluirá en el firmware del port:

$ cd mpy-cross
$ make

Nota

Ten en cuenta que mpy-cross debe compilarse para la arquitectura del host y no para la arquitectura de destino.

Si se compiló correctamente, deberías ver un mensaje similar a este:

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

Nota

Usa make -C mpy-cross para compilar el compilador cruzado en una sola instrucción sin cambiar al directorio mpy-cross; de lo contrario, tendrás que ejecutar cd .. para los siguientes pasos.

Compilar el port Unix de MicroPython

El port Unix es una versión de MicroPython que se ejecuta en Linux, macOS y otros sistemas operativos de tipo Unix. Es extremadamente útil para desarrollar MicroPython, ya que evita tener que desplegar tu código en un dispositivo para probarlo. En muchos sentidos, funciona de forma muy parecida al binario python de CPython.

Para compilar el port Unix, asegúrate de que todas las dependencias relacionadas con Linux estén instaladas tal como se detalla en la sección de dependencias necesarias. Consulta Dependencias necesarias para asegurarte de que todas las dependencias de este port estén instaladas. Asimismo, asegúrate de tener un entorno funcional para gcc y GNU make. En el ejemplo siguiente se ha utilizado Ubuntu 20.04, pero otros sistemas Unix deberían funcionar con pocas modificaciones:

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

luego compila:

$ cd ports/unix
$ make submodules
$ make

Si MicroPython se compiló correctamente, deberías ver lo siguiente:

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

Ahora ejecútalo:

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

Compilar el port de Windows

El port de Windows incluye un archivo de proyecto de Visual Studio micropython.vcxproj que puedes usar para compilar micropython.exe. Se puede abrir en Visual Studio o compilar desde la línea de comandos usando msbuild. Como alternativa, se puede compilar con mingw, ya sea en Windows con Cygwin o en Linux. Consulta la documentación del port de Windows para más información.

Compilar el port STM32

Al igual que con el port Unix, necesitas instalar algunas dependencias requeridas tal como se detalla en la sección Dependencias necesarias, y luego compilar:

$ cd ports/stm32
$ make submodules
$ make

Consulta la documentación de stm32 para obtener más detalles sobre cómo grabar el firmware.

Nota

Consulta Dependencias necesarias para asegurarte de que todas las dependencias de este port estén instaladas. Se necesita el compilador cruzado. arm-none-eabi-gcc también debe estar en el $PATH o especificarse manualmente mediante CROSS_COMPILE, ya sea estableciendo la variable de entorno o en los argumentos de la línea de comandos de make.

También puedes especificar qué placa usar:

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

Consulta ports/stm32/boards para ver las placas disponibles. Por ejemplo, «OPENMV4» u «OPENMV4P».

Generar la documentación

La documentación de MicroPython se crea con Sphinx. Si ya has instalado Python, instala Sphinx mediante pip. Se recomienda que utilices un entorno virtual:

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

Navega hasta el directorio docs:

$ cd docs

Genera la documentación:

$ make html

Abre docs/build/html/index.html en tu navegador para ver la documentación localmente. Consulta la documentación sobre cómo importar tu documentación para usar Read the Docs.

Ejecutar las pruebas

Para ejecutar todas las pruebas del conjunto de pruebas en el port Unix usa:

$ cd ports/unix
$ make test

Para ejecutar una selección de pruebas en una placa/dispositivo conectado por USB usa:

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

Consulta también Escribir pruebas.

Objetivos make adicionales para desarrolladores

En todos los ports basados en make, existe un objetivo para imprimir el tamaño de un archivo objeto específico. Cuando un cambio se limita a un solo archivo, esto resulta útil al probar variaciones para encontrar alternativas más pequeñas.

Por ejemplo, para imprimir el tamaño de objstr.o en el directorio py/ al hacer una compilación estándar de unix:

$ make build-standard/py/objstr.sz

De forma similar, existe un objetivo para guardar la versión preprocesada de un archivo:

$ make build-standard/py/objstr.pp

En ports/unix hay objetivos adicionales relacionados con la ejecución de pruebas:

$ 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

Usar ci.sh localmente

MicroPython usa GitHub Actions para la integración continua. Para reducir la dependencia de cualquier sistema de CI específico, los pasos reales de compilación para las builds basadas en Unix se encuentran en el archivo tools/ci.sh. Este también puede usarse como un script en los equipos de los desarrolladores, con algunas salvedades:

  • Para la mayoría de los pasos, se asume un sistema Ubuntu/Debian similar al utilizado durante la CI.

  • Algunos pasos concretos asumen versiones específicas de Ubuntu.

  • Los pasos de configuración pueden invocar el gestor de paquetes del sistema para instalar paquetes, descargar e instalar software de internet, etc.

Para obtener un mensaje de uso que incluya la lista de comandos, ejecuta:

$ tools/ci.sh --help

Como ejemplo, puedes compilar y probar el port unix mínimo con:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Si usas el shell bash, puedes añadir un comando ci con autocompletado por tabulador:

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

Para el shell zsh, reemplaza --bash-completion por --zsh-completion. Para el shell fish, reemplaza --bash-completion por --fish-completion.

Luego, al escribir:

$ ci unix_cov<tab>

Esto completará el nombre del paso de ci como unix_coverage_. Al pulsar tab una segunda vez se mostrará la lista de pasos coincidentes:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Estructura de carpetas

Hay un par de directorios que conviene tener en cuenta respecto a dónde se encuentran ciertos detalles de implementación. A continuación se desglosan las carpetas de nivel superior del código fuente.

py

Contiene el compilador, el entorno de ejecución y la implementación de la biblioteca principal.

mpy-cross

Contiene el compilador cruzado de MicroPython, que precompila los scripts de Python a bytecode.

ports

Código de todas las versiones de MicroPython para los ports admitidos.

lib

Bibliotecas C de bajo nivel utilizadas por cualquier port, en su mayoría bibliotecas de terceros.

drivers

Contiene controladores para hardware específico, diseñados para funcionar en múltiples ports.

extmod

Contiene una implementación en C de más módulos no esenciales.

docs

Contiene la documentación estándar que se encuentra en https://docs.micropython.org/.

tests

Una implementación del conjunto de pruebas.

tools

Contiene scripts utilizados por el proceso de compilación y de CI, así como herramientas de usuario como mpremote.

examples

Código de ejemplo para compilar MicroPython como biblioteca, así como módulos nativos.