入门

本指南分步介绍了如何设置版本控制、获取并构建某个移植版本的源代码、构建文档、运行测试，并对 MicroPython 代码库的目录结构进行了说明。

使用 git 进行源代码控制

MicroPython 托管在 GitHub 上，并使用 Git 进行源代码控制。其工作流程是从主仓库拉取代码以及向主仓库推送代码。请为你的操作系统安装相应版本的 Git，以便完成后续步骤。

备注

有关安装说明的参考，请查阅 Git 安装说明。你可以通过这本 Git 手册 或互联网上的其他资料学习基本的 git 命令。

备注

代码库中包含一个 .git-blame-ignore-revs 文件，它可以避免 git blame 的输出被那些仅用于格式化代码、没有功能性更改的提交所干扰。有关如何使用该文件，请参阅 git blame 文档。

获取代码

建议你为开发目的维护一个 MicroPython 仓库的派生（fork）。获取源代码的过程包括以下步骤：

  1. 派生（fork）仓库 https://github.com/micropython/micropython

  2. 现在你将在 <https://github.com/<your-user-name>/micropython> 处拥有一个派生（fork）。

  3. 使用以下命令克隆派生后的仓库：

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

然后，配置远程仓库 以便能够在 MicroPython 项目上进行协作。

配置远程 upstream：

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

通常会在派生（fork）的仓库上配置 upstream 和 origin，以协助共享代码更改。你可以维护自己的映射，但建议将 origin 映射到你的派生仓库，将 upstream 映射到 MicroPython 主仓库。

完成上述配置后，你的设置应与此类似：

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

现在你应该拥有了一份源代码副本。默认情况下，你指向的是 master 分支。为后续开发做准备，建议在开发分支上进行工作。

$ git checkout -b dev-branch

你可以为它取任意名称。每当切换到不同的分支时，都必须重新编译 MicroPython。

编译并构建代码

在编译 MicroPython 时，你需要编译某个特定的 port，通常针对某个特定的 board。首先安装所需的依赖项。然后在成功编译和构建之前先构建 MicroPython 交叉编译器。这一点特别适用于使用 Linux 进行编译时。Windows 的相关说明将在后面的章节中提供。

所需依赖项

为 Linux 安装所需的依赖项：

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

对于 stm32 移植版本，需要 ARM 交叉编译器：

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

有关最新详情，请参阅 ARM GCC 工具链。

还需要 Python 3。请检查你的系统上是否有可用的 Python：

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

所有受支持的移植版本都有不同的依赖要求，请参阅它们各自的 readme 文件。

构建 MicroPython 交叉编译器

几乎所有移植版本都需要先构建 mpy-cross，以便对将被包含在移植固件中的 Python 代码进行预编译：

$ cd mpy-cross
$ make

备注

请注意，mpy-cross 必须针对主机架构而非目标架构进行构建。

如果构建成功，你应该会看到类似如下的消息：

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

备注

使用 make -C mpy-cross 可以在一条语句中构建交叉编译器，而无需进入 mpy-cross 目录；否则，你需要在后续步骤中执行 cd ..。

构建 MicroPython 的 Unix 移植版本

Unix 移植版本是可在 Linux、macOS 和其他类 Unix 操作系统上运行的 MicroPython 版本。它对于开发 MicroPython 极为有用，因为它无需将代码部署到设备上即可进行测试。在许多方面，它的工作方式与 CPython 的 python 二进制文件非常相似。

要构建 Unix 移植版本，请确保按照所需依赖项一节中的详细说明安装了所有与 Linux 相关的依赖项。请参阅 所需依赖项 以确保已安装该移植版本所需的所有依赖项。此外，请确保你拥有可正常工作的 gcc 和 GNU make 环境。下面的示例使用了 Ubuntu 20.04，但其他 Unix 系统稍作修改后也应能正常工作：

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

然后进行构建：

$ cd ports/unix
$ make submodules
$ make

如果 MicroPython 构建正确，你应该会看到以下内容：

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 移植版本

Windows 移植版本包含一个 Visual Studio 项目文件 micropython.vcxproj，你可以用它来构建 micropython.exe。它可以在 Visual Studio 中打开，也可以使用 msbuild 从命令行构建。或者，也可以使用 mingw 进行构建，无论是在带有 Cygwin 的 Windows 上还是在 Linux 上。有关更多信息，请参阅 windows 移植版本文档。

构建 STM32 移植版本

与 Unix 移植版本一样，你需要按照 所需依赖项 一节中的详细说明安装一些所需的依赖项，然后进行构建：

$ cd ports/stm32
$ make submodules
$ make

有关刷写固件的更多详情，请参阅 stm32 文档。

备注

请参阅 所需依赖项 以确保已安装该移植版本所需的所有依赖项。需要交叉编译器。arm-none-eabi-gcc 也应位于 $PATH 中，或通过 CROSS_COMPILE 手动指定，方式可以是设置环境变量或在 make 命令行参数中指定。

你还可以指定要使用的开发板：

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

可用的开发板请参阅 ports/stm32/boards。例如 "OPENMV4" 或 "OPENMV4P"。

构建文档

MicroPython 文档使用 Sphinx 创建。如果你已经安装了 Python，那么使用 pip 安装 Sphinx。建议你使用虚拟环境：

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

进入 docs 目录：

$ cd docs

构建文档：

$ make html

在浏览器中打开 docs/build/html/index.html 即可在本地查看文档。要使用 Read the Docs，请参阅有关 导入文档 的文档。

运行测试

要在 Unix 移植版本上运行测试套件中的所有测试，请使用：

$ cd ports/unix
$ make test

要在通过 USB 连接的开发板/设备上运行选定的测试，请使用：

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

另请参阅 编写测试。

面向开发者的其他 make 目标

在所有基于 make 的移植版本中，都有一个用于打印特定目标文件大小的目标。当更改局限于单个文件时，这在测试各种变体以寻找更小的替代方案时非常有用。

例如，在进行 unix 标准构建时，要打印 py/ 目录中 objstr.o 的大小：

$ make build-standard/py/objstr.sz

类似地，还有一个用于保存文件预处理版本的目标：

$ make build-standard/py/objstr.pp

在 ports/unix 中，还有一些与运行测试相关的其他目标：

$ 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

在本地使用 ci.sh

MicroPython 使用 GitHub Actions 进行持续集成。为了减少对任何特定 CI 系统的依赖，基于 Unix 的构建的实际构建步骤都放在 tools/ci.sh 文件中。它也可以作为脚本在开发者的桌面环境中使用，但有以下注意事项：

  • 对于大多数步骤，假定使用的是与 CI 期间所用系统类似的 Ubuntu/Debian 系统。

  • 某些特定步骤假定使用特定的 Ubuntu 版本。

  • 设置步骤可能会调用系统包管理器来安装软件包、从互联网下载并安装软件等。

要获取包含命令列表的用法消息，请运行：

$ tools/ci.sh --help

例如，你可以使用以下命令构建并测试 unix 最小移植版本：

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

如果你使用 bash shell，可以添加一个带有 Tab 补全功能的 ci 命令：

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

对于 zsh shell，请将 --bash-completion 替换为 --zsh-completion。对于 fish shell，请将 --bash-completion 替换为 --fish-completion。

然后，输入：

$ ci unix_cov<tab>

这会将 ci 步骤名称补全为 unix_coverage_。再次按下 Tab 键将显示匹配步骤的列表：

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

文件夹结构

就某些实现细节所在的位置而言，有几个目录值得注意。以下是源代码中顶层文件夹的详细说明。

py

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

mpy-cross

包含 MicroPython 交叉编译器，它将 Python 脚本预编译为字节码。

ports

适用于所有受支持移植版本的各个 MicroPython 版本的代码。

lib

供任何移植版本使用的底层 C 库，其中大多数是第三方库。

drivers

包含针对特定硬件的驱动程序，旨在跨多个移植版本工作。

extmod

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

docs

包含 https://docs.micropython.org/ 上的标准文档。

tests

测试套件的实现。

tools

包含构建和 CI 流程所用的脚本，以及诸如 mpremote 之类的用户工具。

examples

用于将 MicroPython 构建为库以及构建原生模块的示例代码。