入门

本指南涵盖了设置版本控制、获取和构建端口源代码副本、构建文档、运行测试以及 MicroPython 代码库目录结构描述的分步过程。

使用 git 进行源代码控制

MicroPython 托管在 GitHub 上，并使用 Git 进行源代码控制。工作流是这样的，代码从主存储库中拉取和推送。为您的操作系统安装相应版本的 Git 以完成其余步骤。.

笔记

有关安装说明的参考，请参阅Git 安装说明。在本 Git 手册 或互联网上的任何其他资源中了解基本的 git 命令。

笔记

包含一个 .git-blame-ignore-revs 文件，可避免 git blame 的输出被仅用于格式化代码但没有功能更改的提交弄乱。有关如何使用它的信息，请参阅 git blame 文档。

获取代码

建议您出于开发目的维护 MicroPython 存储库的一个分支。获取源代码的过程包括以下内容：

  1. Fork 仓库 https://github.com/micropython/micropython

  2. 您现在将在 https://github.com//micropython> 上有一个分支。

  3. 使用以下命令克隆分叉存储库：

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

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

配置远程上游：

$ 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 arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib

有关 最新详细信息，请参阅ARM GCC 工具链 。

还需要 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.
>>>

所有支持的端口都有不同的依赖要求，请参阅各自的 自述文件。

构建 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 和的工作环境。Ubuntu 20.04 已用于下面的示例，但其他 unix 应该只需稍加修改即可工作： GNU make

$ 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 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 submodules
$ make BOARD=<board>

有关 可用的板，请参阅端口/stm32/板 。例如“PYBV11”或“NUCLEO_WB55”。

构建文档

MicroPython 文档是使用 Sphinx. 如果您已经安装了 Python，请Sphinx 使用 pip. 建议您使用虚拟环境：

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

导航到 docs目录：

$ cd docs

构建文档：

$ make html

docs/build/html/index.html在浏览器中打开以在本地查看文档。请参阅有关导入文档的文档以使用阅读文档。

运行测试

要在 Unix 端口上运行测试套件中的所有测试，请使用：

$ cd ports/unix
$ make test

要在通过 USB 连接的电路板/设备上运行一系列测试，请使用：

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

另请参阅编写测试。

文件夹结构

关于某些实现细节的位置，有几个目录需要注意。以下是源代码中顶级文件夹的细分。

py

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

mpy-cross

具有 MicroPython 交叉编译器，可将 Python 脚本预编译为字节码。

端口

支持端口的所有 MicroPython 版本的代码。

库

任何端口使用的低级 C 库，主要是 3rd 方库。

drivers

具有特定硬件的驱动程序，旨在跨多个端口工作。

扩展模块

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

文档

在https://docs.micropython.org/找到标准文档。

测试

测试套件的实现。

工具

包含帮助工具，包括upip 和 pyboard.py 模块。

例子

将 MicroPython 构建为库和本机模块的示例代码。