当前位置：首页 > news >正文

MicroPython核心（1）：源码获取、编译构建

news 2026/3/28 16:15:25

本文介绍了MicroPython在主要平台进行构建的基本方法，包括如何进行版本控制、获取和构建移植的源代码、构建文档、运行测试，以及MicroPython代码库的目录结构。

使用git进行源码管理

MicroPython托管在GitHub上，并使用Git进行源码管理。在进行下面的步骤之前，需要在本机先安装好Git。

注意：

有关安装说明的参考资料，请参阅Git安装说明，建议先熟悉Git的基本概念和操作再开始下面的工作。
.git-blame-ignore-revs文件，可避免git blame的输出被只用于格式化代码而无功能改动的提交所干扰。如何使用请参见 git blame文档文档。

获取代码

建议维护一个MicroPython代码库的分支以备开发之用。获取源代码的过程如下：

fork仓库https://github.com/micropython/micropython
获得一个<https://github.com//micropython>分支
使用以下命令克隆分支仓库：

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

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

配置远程upstream：

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

为方便共享代码变更，在分支版本库中配置 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)

现在已经有一份源代码副本了。默认情况下，它指向的是主分支。为了做好进一步开发的准备，建议在开发分支上工作。

$ git checkout -b dev-branch

这里可以给它起任何名字，每当切换到不同的分支时，都必须编译MicroPython。

编译构建代码

编译MicroPython时，需要编译相应的移植，通常是针对特定的开发板。先安装所需的依赖项，然后构建 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

Python是必须的，虽然支持Python 2，但建议使用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，以便对将包含在 port 固件中的 Python 代码进行预编译：

$ cd mpy-cross
$ make

**注意：**mpy-cross 必须针对主机架构而非目标架构构建。

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

LINK mpy-crosstext          data    bss     dec     hex filename279328          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，但其他 Linux 也可以使用，只需稍作修改即可：

$ 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

如果MicroPython能被正确构建，应该可以看到下面的信息：

LINK micropythontext         data     bss     dec     hex filename412033         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 在 Windows 和 Cygwin 或 Linux 中构建。

STM32移植构建

与 Unix 移植版一样，需要安装一些所需的依赖项，然后进行编译：

$ cd ports/stm32
$ make submodules
$ make

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

**注意：**请参阅 “所需的依赖项”，以确保为该移植安装了所有依赖项。arm-none-eabi-gcc也应位于 $PATH 中，或通过设置环境变量或在 make 命令行参数中手动通过 CROSS_COMPILE 指定。

还可以指定开发板：

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

关于可用的可用板，可以参考ports/stm32/boards，例如 “PYBV11"或"NUCLEO_WB55”。

文档构建

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，查看本地文档。请参阅有关导入文档的文档，以使用 “阅读文档”。

运行测试

在Linux移植上运行测试套件中的所有测试：

$ cd ports/unix
$ make test

在通过USB连接的开发板或设备上运行一系列测试：

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

目录结构

在某些实施细节方面，有几个目录值得注意。以下是源代码顶级文件夹的细分。

目录	说明
py	包含编译器、运行时和核心库的实现
mpy-cross	MicroPython交叉编译器，可将Python脚本预编译为字节码
ports	支持移植的所有 MicroPython 版本的代码
lib	任何移植使用的低级 C 语言库，其中大部分是第三方库
drivers	具有针对特定硬件的驱动程序，旨在支持多种移植
extmod	包含更多非核心模块的 C 语言实现
docs	网站上的标准文档https://docs.micropython.org/
tests	测试套件的实现
tools	包含构建和 CI 流程使用的脚本，以及pyboard.py和mpremote等工具
examples	把MicroPython作为库和本地模块构建的示例代码