Primeiros passos

Este guia aborda um processo passo a passo para configurar o controle de versão, obter e compilar uma cópia do código-fonte de um port, gerar a documentação, executar os testes e descreve a estrutura de diretórios da base de código do MicroPython.

Controle de versão com git

O MicroPython é hospedado no GitHub e usa o Git para controle de versão. O fluxo de trabalho consiste em fazer pull e push de código de e para o repositório principal. Instale a versão correspondente do Git para o seu sistema operacional para acompanhar o restante dos passos.

Nota

Para uma referência sobre 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 em qualquer outra fonte na internet.

Nota

Um arquivo .git-blame-ignore-revs está incluído para evitar que a saída do git blame fique poluída por commits que apenas formatam o código mas não têm alterações funcionais. Veja a documentação do git blame sobre como usar isso.

Obtenha o código

Recomenda-se que você mantenha um fork do repositório do MicroPython para seus propósitos de desenvolvimento. O processo de obtenção do código-fonte inclui o seguinte:

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

  2. Você agora terá um fork em <https://github.com/<seu-nome-de-usuario>/micropython>.

  3. Clone o repositório forkado 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 do MicroPython.

Configure o upstream remoto:

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

É comum configurar upstream e origin em um repositório forkado para ajudar a compartilhar alterações de código. Você pode manter 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, sua configuração deve 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)

Você agora deve ter uma cópia do código-fonte. Por padrão, você está apontando para o branch master. Para se preparar para desenvolvimentos futuros, recomenda-se trabalhar em um branch de desenvolvimento.

$ git checkout -b dev-branch

Você pode dar a ele qualquer nome. Você terá que compilar o MicroPython sempre que mudar para um branch diferente.

Compile e construa o código

Ao compilar o MicroPython, você compila um port específico, normalmente direcionado a uma placa específica. Comece instalando as dependências necessárias. Em seguida, compile o cross-compilador do MicroPython antes de conseguir compilar e construir com sucesso. Isso se aplica especificamente ao usar o Linux para compilar. As instruções para Windows são fornecidas em uma seção posterior.

Dependências necessárias

Instale as dependências necessárias para o Linux:

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

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

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

Veja o toolchain ARM GCC para os detalhes mais recentes.

O Python 3 também é necessário. Verifique se você tem o Python disponível em 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ência diferentes; veja seus respectivos arquivos readme.

Compilando o cross-compilador do MicroPython

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

$ cd mpy-cross
$ make

Nota

Observe que o mpy-cross deve ser compilado para a arquitetura do host e não para a arquitetura de destino.

Se a compilação for bem-sucedida, você deve 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 cross-compilador em um único comando sem entrar no diretório mpy-cross; caso contrário, você precisará executar cd .. para os próximos passos.

Compilando o port Unix do MicroPython

O port Unix é uma versão do MicroPython que roda no Linux, macOS e outros sistemas operacionais semelhantes ao Unix. Ele é extremamente útil para desenvolver o MicroPython, pois evita ter que implantar seu código em um dispositivo para testá-lo. De muitas formas, ele funciona de maneira muito semelhante ao binário python do CPython.

Para compilar o port Unix, certifique-se de que todas as dependências relacionadas ao Linux estejam instaladas conforme detalhado na seção de dependências necessárias. Veja as Dependências necessárias para garantir que todas as dependências deste port estejam instaladas. Além disso, certifique-se de ter um ambiente funcional para gcc e GNU make. O Ubuntu 20.04 foi usado no exemplo abaixo, mas outros unixes devem funcionar com pequenas 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.

em seguida compile:

$ cd ports/unix
$ make submodules
$ make

Se o MicroPython foi compilado corretamente, você deve 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
>>>

Compilando o port Windows

O port Windows inclui um arquivo de projeto do Visual Studio micropython.vcxproj que você pode usar para construir o micropython.exe. Ele pode ser aberto no Visual Studio ou compilado pela linha de comando usando o msbuild. Alternativamente, ele pode ser compilado usando o mingw, seja no Windows com Cygwin ou no Linux. Veja a documentação do port windows para mais informações.

Compilando o port STM32

Assim como no port Unix, você precisa instalar algumas dependências necessárias conforme detalhado na seção Dependências necessárias e, em seguida, compilar:

$ cd ports/stm32
$ make submodules
$ make

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

Nota

Veja as Dependências necessárias para garantir que todas as dependências deste port estejam instaladas. O cross-compilador é necessário. O arm-none-eabi-gcc também deve estar no $PATH ou ser especificado manualmente via CROSS_COMPILE, seja definindo a variável de ambiente ou nos argumentos da linha de comando do make.

Você também pode especificar qual placa usar:

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

Veja ports/stm32/boards para as placas disponíveis. Por exemplo, “OPENMV4” ou “OPENMV4P”.

Compilando a documentação

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

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

Navegue até o diretório docs:

$ cd docs

Compile a documentação:

$ make html

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

Executando os testes

Para executar todos os testes da suíte de testes no port Unix, use:

$ cd ports/unix
$ make test

Para executar uma seleção de testes em uma placa/dispositivo conectado por USB, use:

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

Veja também Escrevendo testes.

Targets de make adicionais para desenvolvedores

Em todos os ports baseados em make, há um target para imprimir o tamanho de um arquivo objeto específico. Quando uma alteração se limita a um único arquivo, isso é útil ao testar variações para encontrar alternativas menores.

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

$ make build-standard/py/objstr.sz

De forma semelhante, há um target para salvar a versão pré-processada de um arquivo:

$ make build-standard/py/objstr.pp

Em ports/unix há targets adicionais relacionados à 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

Usando o ci.sh localmente

O MicroPython usa o GitHub Actions para integração contínua. Para reduzir a dependência de qualquer sistema de CI específico, os passos reais de compilação para builds baseados em Unix estão no arquivo tools/ci.sh. Isso também pode ser usado como um script em desktops de desenvolvedores, com algumas ressalvas:

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

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

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

Para obter uma mensagem de uso incluindo a lista de comandos, execute:

$ tools/ci.sh --help

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

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Se você usa o shell bash, pode adicionar um comando ci com autocompletar 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, ao digitar:

$ ci unix_cov<tab>

Isso completará o nome do passo do ci para unix_coverage_. Pressionar 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

Há alguns diretórios a serem observados quanto a onde certos detalhes de implementação se encontram. A seguir, um detalhamento das pastas de nível superior no código-fonte.

py

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

mpy-cross

Possui o cross-compilador do MicroPython, que pré-compila os scripts Python para bytecode.

ports

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

lib

Bibliotecas C de baixo nível usadas por qualquer port, que são em sua maioria bibliotecas de terceiros.

drivers

Possui drivers para hardware específico, destinados a funcionar em vários ports.

extmod

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

docs

Possui a documentação padrão encontrada em https://docs.micropython.org/.

tests

Uma implementação da suíte de testes.

tools

Contém scripts usados pelos processos de compilação e CI, bem como ferramentas de usuário como o mpremote.

examples

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