Primeiros Passos

Este guia descreve passo a passo o processo de configuração do controlo de versões, obtenção e compilação do código-fonte de um port, criação da documentação, execução de testes e uma descrição da estrutura de diretórios do código base do MicroPython.

Controlo de versões com git

O MicroPython está alojado no GitHub e utiliza o Git para controlo de versões. O fluxo de trabalho consiste em obter e enviar código de e para o repositório principal. Instale a versão adequada do Git para o seu sistema operativo para seguir os passos seguintes.

Nota

Para consultar as instruções de instalação, consulte as instruções de instalação do Git. Aprenda os comandos básicos do git neste Git Handbook ou noutras fontes disponíveis na internet.

Nota

Está incluído um ficheiro .git-blame-ignore-revs que evita que a saída do git blame fique sobrecarregada com commits apenas de formatação de código sem alterações funcionais. Consulte a documentação do git blame para saber como utilizá-lo.

Obter o código

Recomenda-se que mantenha um fork do repositório MicroPython para fins de desenvolvimento. O processo de obtenção do código-fonte inclui os seguintes passos:

  1. Faça fork do repositório https://github.com/micropython/micropython

  2. Ficará agora com um fork em <https://github.com/<your-user-name>/micropython>.

  3. Clone o repositório com fork usando o seguinte comando:

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

Em seguida, configure os repositórios remotos para poder colaborar no projeto MicroPython.

Configurar o remoto upstream:

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

É comum configurar upstream e origin num repositório com fork para facilitar a partilha de alterações de código. Pode definir o seu próprio mapeamento, mas recomenda-se que origin aponte para o seu fork e upstream para o repositório principal do MicroPython.

Após a configuração acima, a sua configuração deverá ser semelhante a esta:

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

Deverá agora ter uma cópia do código-fonte. Por predefinição, está a apontar para o ramo master. Para preparar o desenvolvimento futuro, recomenda-se trabalhar num ramo de desenvolvimento.

$ git checkout -b dev-branch

Pode dar-lhe qualquer nome. Terá de compilar o MicroPython sempre que mudar para um ramo diferente.

Compilar e construir o código

Ao compilar o MicroPython, compila um port específico, geralmente destinado a uma placa específica. Comece por instalar as dependências necessárias. Em seguida, compile o compilador cruzado do MicroPython antes de conseguir compilar e construir com sucesso. Isto aplica-se especificamente quando se utiliza Linux para compilar. As instruções para Windows são fornecidas numa secção posterior.

Dependências necessárias

Instale as dependências necessárias para Linux:

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

Para o port stm32, é necessário o compilador cruzado ARM:

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

Consulte a toolchain ARM GCC para obter os detalhes mais recentes.

O Python 3 também é necessário. Verifique se tem o Python disponível no seu 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 os ports suportados têm requisitos de dependências diferentes; consulte os respetivos ficheiros readme.

Compilar o compilador cruzado do MicroPython

Quase todos os ports requerem a compilação de mpy-cross primeiro para realizar a pré-compilação de código Python que será incluído no firmware do port:

$ cd mpy-cross
$ make

Nota

Note que mpy-cross deve ser compilado para a arquitetura do host e não para a arquitetura alvo.

Se a compilação for bem-sucedida, deverá ver uma mensagem semelhante a esta:

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

Nota

Use make -C mpy-cross para compilar o compilador cruzado numa única instrução sem mudar para o diretório mpy-cross; caso contrário, precisará de executar cd .. para os passos seguintes.

Compilar o port Unix do MicroPython

O port Unix é uma versão do MicroPython que corre em Linux, macOS e outros sistemas operativos semelhantes ao Unix. É extremamente útil para desenvolver o MicroPython, pois evita ter de implementar o código num dispositivo para o testar. Em muitos aspetos, funciona de forma semelhante ao binário python do CPython.

Para compilar o port Unix, certifique-se de que todas as dependências relacionadas com Linux estão instaladas conforme descrito na secção de dependências necessárias. Consulte Dependências necessárias para se certificar de que todas as dependências estão instaladas para este port. Certifique-se também de que tem um ambiente funcional para gcc e GNU make. O Ubuntu 20.04 foi utilizado no exemplo abaixo, mas outros sistemas unix deverão funcionar com poucas modificações:

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

depois compile:

$ cd ports/unix
$ make submodules
$ make

Se o MicroPython compilar corretamente, deverá ver o seguinte:

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

Agora execute-o:

$ ./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 o port Windows

O port Windows inclui um ficheiro de projeto do Visual Studio micropython.vcxproj que pode usar para compilar micropython.exe. Pode ser aberto no Visual Studio ou compilado a partir da linha de comandos usando msbuild. Em alternativa, pode ser compilado usando mingw, tanto no Windows com Cygwin como no Linux. Consulte a documentação do port windows para mais informações.

Compilar o port STM32

Tal como o port Unix, é necessário instalar algumas dependências conforme descrito na secção Dependências necessárias, depois compile:

$ cd ports/stm32
$ make submodules
$ make

Consulte a documentação do stm32 para mais detalhes sobre como fazer o flash do firmware.

Nota

Consulte Dependências necessárias para se certificar de que todas as dependências estão instaladas para este port. O compilador cruzado é necessário. arm-none-eabi-gcc deve também estar no $PATH ou especificado manualmente via CROSS_COMPILE, definindo a variável de ambiente ou nos argumentos da linha de comandos do make.

Pode também especificar qual a placa a utilizar:

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

Consulte ports/stm32/boards para as placas disponíveis. Por exemplo, «OPENMV4» ou «OPENMV4P».

Compilar a documentação

A documentação do MicroPython é criada usando Sphinx. Se já instalou o Python, instale o Sphinx usando pip. Recomenda-se a utilização de um ambiente virtual:

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

Navegue para o diretório docs:

$ cd docs

Compile a documentação:

$ make html

Abra docs/build/html/index.html no seu navegador para ver a documentação localmente. Consulte a documentação sobre importar a sua documentação para usar o Read the Docs.

Executar os testes

Para executar todos os testes da suite de testes no port Unix, use:

$ cd ports/unix
$ make test

Para executar uma seleção de testes numa placa/dispositivo ligado via USB, use:

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

Consulte também Escrever testes.

Alvos make adicionais para programadores

Em todos os ports baseados em make, existe um alvo para imprimir o tamanho de um ficheiro objeto específico. Quando uma alteração está limitada a um único ficheiro, isto é útil para testar variações à procura de alternativas mais compactas.

Por exemplo, para imprimir o tamanho de objstr.o no diretório py/ ao fazer uma compilação standard unix:

$ make build-standard/py/objstr.sz

De forma semelhante, existe um alvo para guardar a versão pré-processada de um ficheiro:

$ make build-standard/py/objstr.pp

Em ports/unix existem alvos adicionais relacionados com a execução de testes:

$ 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

O MicroPython usa GitHub Actions para integração contínua. Para reduzir a dependência de qualquer sistema de CI específico, os passos de compilação reais para compilações baseadas em Unix estão no ficheiro tools/ci.sh. Também pode ser usado como script nos desktops dos programadores, com algumas ressalvas:

  • Para a maioria dos passos, assume-se um sistema Ubuntu/Debian semelhante ao utilizado durante o CI.

  • Alguns passos específicos assumem versões específicas do Ubuntu.

  • Os passos de configuração podem invocar o gestor de pacotes do sistema para instalar pacotes, descarregar e instalar software da internet, etc.

Para obter uma mensagem de utilização incluindo a lista de comandos, execute:

$ tools/ci.sh --help

Como exemplo, pode compilar e testar o port minimal unix com:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Se usar o shell bash, pode adicionar um comando ci com completamento por tab:

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

Para o shell zsh, substitua --bash-completion por --zsh-completion. Para o shell fish, substitua --bash-completion por --fish-completion.

Em seguida, escrevendo:

$ ci unix_cov<tab>

Isto completará o nome do passo ci para unix_coverage_. Premindo tab uma segunda vez mostrará a lista de passos correspondentes:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Estrutura de pastas

Existem alguns diretórios a ter em atenção em termos de onde se encontram determinados detalhes de implementação. O seguinte é uma descrição das pastas de nível superior no código-fonte.

py

Contém a implementação do compilador, runtime e biblioteca principal.

mpy-cross

Tem o compilador cruzado do MicroPython que pré-compila os scripts Python para bytecode.

ports

Código para todas as versões do MicroPython para os ports suportados.

lib

Bibliotecas C de baixo nível usadas por qualquer port, maioritariamente bibliotecas de terceiros.

drivers

Contém drivers para hardware específico e destinados a funcionar em múltiplos ports.

extmod

Contém uma implementação em C de módulos não-essenciais adicionais.

docs

Tem a documentação padrão disponível em https://docs.micropython.org/.

tests

Uma implementação da suite de testes.

tools

Contém scripts usados pelo processo de compilação e CI, bem como ferramentas para utilizadores como o mpremote.

examples

Código de exemplo para compilar o MicroPython como biblioteca, bem como módulos nativos.