快速入门

This guide covers a step-by-step process on setting up version control, obtaining and building a copy of the source code for a port, building the documentation, running tests, and a description of the directory structure of the MicroPython code base.

采用 Git 控制源代码

MicroPython 托管在 GitHub 和使用 Git for source control. The workflow is such that code is pulled and pushed to and from the main repository. Install the respective version of Git for your operating system to follow through the rest of the steps.

注意

For a reference on the installation instructions, please refer to the Git installation instructions . Learn about the basic git commands in this Git Handbook or any other sources on the internet.

注意

A .git-blame-ignore-revs file is included which avoids the output of git blame getting cluttered by commits which are only for formatting code but have no functional changes. See git blame documentation on how to use this.

获取代码

It is recommended that you maintain a fork of the MicroPython repository for your development purposes. The process of obtaining the source code includes the following:

  1. 分叉存储库 https://github.com/micropython/micropython

  2. 现在将拥有分叉在 < https://github.com /<your-user-name>/micropython>.

  3. Clone the forked repository using the following command: 

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

Then, 配置远程存储库 to be able to collaborate on the MicroPython project.

配置远程上游： 

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

It is common to configure upstream and origin on a forked repository to assist with sharing code changes. You can maintain your own mapping but it is recommended that origin maps to your fork and upstream to the main MicroPython repository.

After the above configuration, your setup should be similar to this: 

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

You should now have a copy of the source code. By default, you are pointing to the master branch. To prepare for further development, it is recommended to work on a development branch. 

$ git checkout -b dev-branch

You can give it any name. You will have to compile MicroPython whenever you change to a different branch.

编译和构建代码

当编译 MicroPython 时，编译特定 port , usually targeting a specific board . Start by installing the required dependencies. Then build the MicroPython cross-compiler before you can successfully compile and build. This applies specifically when using Linux to compile. The Windows instructions are provided in a later section.

所需依赖

安装所需依赖为 Linux： 

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

For the stm32 port, the ARM cross-compiler is required: 

$ sudo apt-get install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib

见 ARM GCC 工具链 了解最新细节。

Python is also required. Python 2 is supported for now, but we recommend using Python 3. Check that you have Python available on your system: 

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

All supported ports have different dependency requirements, see their respective readme files .

构建 MicroPython 交叉编译器

Almost all ports require building mpy-cross first to perform pre-compilation of Python code that will be included in the port firmware: 

$ cd mpy-cross
$ make

注意

注意， mpy-cross must be built for the host architecture and not the target architecture.

If it built successfully, you should see a message similar to this: 

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

注意

使用 make -C mpy-cross to build the cross-compiler in one statement without moving to the mpy-cross directory otherwise, you will need to do cd .. for the next steps.

构建 MicroPython 的 Unix port

The Unix port is a version of MicroPython that runs on Linux, macOS, and other Unix-like operating systems. It’s extremely useful for developing MicroPython as it avoids having to deploy your code to a device to test it. In many ways, it works a lot like CPython’s python binary.

To build for the Unix port, make sure all Linux related dependencies are installed as detailed in the required dependencies section. See the 所需依赖 to make sure that all dependencies are installed for this port. Also, make sure you have a working environment for gcc and GNU make . Ubuntu 20.04 has been used for the example below but other unixes ought to work with little modification: 

$ 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.then build:
												
$ cd ports/unix
$ make submodules
$ make

If MicroPython built correctly, you should see the following: 

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

现在运行它： 

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

构建 Windows port

The Windows port includes a Visual Studio project file micropython.vcxproj that you can use to build micropython.exe. It can be opened in Visual Studio or built from the command line using msbuild. Alternatively, it can be built using mingw, either in Windows with Cygwin, or on Linux. See Windows port 文档编制 了解更多信息。

构建 STM32 port

Like the Unix port, you need to install some required dependencies as detailed in the 所需依赖 section, then build: 

$ cd ports/stm32
$ make submodules
$ make

请参考 STM32 文档编制 for more details on flashing the firmware.

注意

见 所需依赖 to make sure that all dependencies are installed for this port. The cross-compiler is needed. arm-none-eabi-gcc should also be in the $PATH or specified manually via CROSS_COMPILE, either by setting the environment variable or in the make command line arguments.

You can also specify which board to use: 

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

见 ports/stm32/boards for the available boards. e.g. “PYBV11” or “NUCLEO_WB55”.

构建文档编制

MicroPython documentation is created using Sphinx . If you have already installed Python, then install Sphinx 使用 pip . It is recommended that you use a virtual environment: 

$ python3 -m venv env
$ source env/bin/activate
$ pip install sphinx

导航到 docs 目录： 

$ cd docs

构建文档： 

$ make html

打开 docs/build/html/index.html in your browser to view the docs locally. Refer to the documentation on importing your documentation to use Read the Docs.

运行测试

To run all tests in the test suite on the Unix port use: 

$ cd ports/unix
$ make test

To run a selection of tests on a board/device connected over USB use: 

$ cd tests
$ ./run-tests.py --target minimal --device /dev/ttyACM0

另请参阅 写编写测试 .

文件夹结构

There are a couple of directories to take note of in terms of where certain implementation details are. The following is a break down of the top-level folders in the source code.

py

包含编译器、运行时及核心库实现。

mpy-cross

Has the MicroPython cross-compiler which pre-compiles the Python scripts to bytecode.

ports

用于支持 port 的所有 MicroPython 版本的代码。

lib

Low-level C libraries used by any port which are mostly 3rd-party libraries.

drivers

Has drivers for specific hardware and intended to work across multiple ports.

extmod

包含更多非核心模块的 C 实现。

docs

Has the standard documentation found at https://docs.micropython.org/ .

tests

测试套件的实现。

tools

Contains helper tools including the upip 和 pyboard.py 模块。

examples

Example code for building MicroPython as a library as well as native modules.