快速开始¶
本文档介绍如何逐步设置版本控制、获取并编译源代码、编译文档、运行测试，以及包含 MicroPython 代码库的目录结构的描述。
使用 git 进行源码控制¶
MicroPython 源码托管在 GitHub 并使用 Git 进行源码控制。工作流程主要是从主仓库拉取或推送源码。先安装与你操作系统相应版本的 Git 再继续接下来的步骤。
备注
如需了解安装说明，请参考 Git 安装说明。了解 Git 基本命令的基本知识，请参考 Git 常用命令手册 或任何其他在线资源。
备注
源码中已包含一个 .git-blame-ignore-revs 文件，该文件会使得 git blame 输出中忽略格式化代码的提交。请参考 git blame 官方文档 来了解如何使用该文件。
获取源码¶
建议你维护一个 MicroPython 代码仓库的 fork ，以便在开发中使用。获取源码包括以下步骤：
从 https://github.com/micropython/micropython 仓库 fork 到你的账户下。
你将会有一个托管在 <https://github.com/<your-user-name>/micropython> 的 fork 。
使用以下命令 clone 你的 fork ：
$ 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 ，以便可以与 MicroPython 主项目的协作。你可以维护自己的映射，但是建议将 origin 映射到你的 fork ，并将 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 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.
>>>
所有支持的端都有不同的依赖库，参考它们的 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 编译交叉编译器，如果你不是这样做的话，需要在下一步之前先 cd .. 返回上级目录。
编译 Unix 端的 MicroPython¶
Unix 端是一个运行在 Linux、macOS 和其他 Unix-like 操作系统上的版本。它非常有用，因为它可以跳过将你的代码部署到目标设备上来测试的过程。在很多方面，它工作起来和 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.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 端的 MicroPython¶
Windows 端包含一个 Visual Studio 项目文件 micropython.vcxproj ，你可以使用 Visual Studio 打开或 msbuild 来编译。另外，也可以使用 mingw 编译、或 Windows 上的 Cygwin 、抑或在基于 WSL 的 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>
参见 ports/stm32/boards 来了解可用的板子。例如，”PYBV11” 或 “NUCLEO_WB55” 。
编译文档¶
MicroPython 文档是使用 Sphinx 创建的。如果你已经安装了 Python ，那么就使用 pip 安装 Sphinx。推荐在虚拟环境中使用：
$ python3 -m venv env
$ source env/bin/activate
$ pip install sphinx
转到 docs 目录：
$ cd docs
编译文档：
$ make html
在浏览器中打开 docs/build/html/index.html 可以本地浏览文档。 Sphinx 所使用 Read the Docs 的使用参见 importing your documentation 。
运行测试¶
在 Unix 适配端上运行所有测试用例：
$ 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
帮助工具，包括
upip和pyboard.py等模块。
examples
使用 MicroPython 库和原生模块的示例代码。