MicroPython的Manifest文件介绍

摘要

MicroPython除了能够从文件系统加载Python代码外，还可以把Python代码“冻结”到固件加载，这样做有几个好处：

• 代码已被预编译为字节码，无需在加载时编译Python源代码。
• 字节码可以直接从ROM（即闪存）中执行，而无需复制到内存。同样，任何常量对象（字符串、元组等）也从ROM中加载，这可以大大增加应用程序的可用内存。
• 在没有文件系统的设备上，这也是加载Python代码的唯一方法。

在开发过程中，一般不建议冻结，因为每次更新都需要重新刷新整个固件，这会大大降低开发周期，不过，有选择性地冻结一些很少变化的依赖项（如第三方库）还是很有用的。

“manifest”本身也是Python文件，列出了要冻结到固件的其他Python文件，会在构建的时候解释执行。通常情况下，可以将manifest文件作为电路板定义的一部分来编写，当然也可以编写一个独立的manifest文件，将其与现有的电路板定义一起使用。

manifest文件可以定义对microropython-lib库和文件系统中的Python文件的依赖关系，也可以定义对其它manifest文件的依赖关系。

编写 manifest 文件

manifest文件是一个包含一系列函数调用的Python文件。请参阅下面定义的可用函数。

manifest文件中使用的任何路径都可以包含以下变量。这些变量都解析为绝对路径。

• $(MPY_DIR) - MicroPython 仓库的路径。
• $(MPY_LIB_DIR) - microropython-lib子模块的路径。最好使用require()。
• $(PORT_DIR) - 当前端口的路径（例如 ports/stm32）
• $(BOARD_DIR) - 当前板子的路径（例如 ports/stm32/boards/PYBV11）

自定义manifest文件不应放在MicroPython主资源库中，而是应该把它们与项目的其余部分一起进行版本控制。

通常情况下，用于编译固件的manifest需要包含端口manifest，其中可能包括电路板运行所需的冻结模块。如果只想在现有电路板上添加其他模块，则应包含电路板manifest（这反过来又会包含端口manifest）。

使用自定义manifest构建

可以在 make 命令行中指定manifest：

$ make BOARD=MYBOARD FROZEN_MANIFEST=/path/to/my/project/manifest.py

这适用于所有的端口， 包括基于CMake的端口(如 esp32、 rp2)，Makefile包装器会将其传递给CMake联编。

为板子定义添加manifest

对于自定义的电路板定义，可以让它自动包含自定义的manifest。在基于 make 的 port（大多数 port）中，在 mpconfigboard.mk 中设置 FROZEN_MANIFEST 变量。

FROZEN_MANIFEST ?= $(BOARD_DIR)/manifest.py

在基于 CMake 的 port（如 esp32、rp2）上，请使用 mpconfigboard.cmake

set(MICROPY_FROZEN_MANIFEST ${MICROPY_BOARD_DIR}/manifest.py)

高级函数

注意：可以在各种函数中设置opt关键字参数，它控制着交叉编译器使用的优化级别。请参见micropython.opt_level()。

package(package_path, files=None, base_path=‘.’, opt=None)

相当于将 "package_path "目录复制到设备上（冻结代码除外）。

最简单的例子是冻结当前目录中的软件包 “foo”：

package("foo")

将递归包含 foo 中的所有 .py 文件，并冻结为 foo/**/*.py：

如果软件包与manifest文件不在同一目录下，则使用 base_path：

package("foo", base_path="path/to/libraries")

上面的路径也可以使用变量，如：base_path中的$(PORT_DIR)。

要限制使用软件包中的某些文件，可以使用files（注意：路径应相对于软件包）：package("foo", files=["bar/baz.py"])。

module(module_path, base_path=‘.’, opt=None)

把单个 Python 文件作为模块。

如果文件在当前目录下，则可以:

module("foo.py")

或者，使用 base_path 指定文件位置：

module("foo.py", base_path="src/drivers")

可以使用上述变量，如base_path中的$(PORT_DIR)。

require(name, unix_ffi=False)

从 micropython-lib 请求软件包名称（及其依赖包）。

要使用 unix-ffi 目录中的模块，可选择指定 unix_ffi=True。

include(manifest_path)

包含其他manifest。

通常，用于编译固件的manifest需要包括端口manifest，其中可能包括电路板运行所需的冻结模块。

manifest参数可以是字符串（文件名）或字符串迭代。

相对路径是根据当前manifest文件解析的。

如果路径指向一个目录，则隐式包含该目录中的 manifest.py 文件。

可以在 manifest_path 中使用变量，如 $(PORT_DIR)。

metadata(description=None, version=None, license=None, author=None)

定义此manifest文件的元数据。这对 microropython-lib 软件包的manifest非常有用。

低级函数

为完整起见，我们对这些函数进行了记录，但除了 freeze_as_str 外，所有功能都可以通过高级函数访问。

freeze(path, script=None, opt=0)

指定的冻结路径，并自动判断其类型。.py 脚本将先编译为 .mpy 文件，然后冻结，而 .mpy 文件将直接冻结。

path 必须是一个目录，也就是开始搜索文件的基本目录。导入生成的冻结模块时，模块名称将从 path 后开始，也就是说，模块名称中不包括 path。

如果 path 是相对路径，则解析为当前的 manifest.py。

如果 script 为 “None”，路径中的所有文件都将被冻结。

如果 script 是可迭代的，则freeze()会在可迭代的所有条目上调用（使用相同的path和oppt）。

如果 script 是字符串，那么它将指定要冻结的文件或目录，并且可以包括文件或最后一个目录之前的额外目录，文件或目录将在 path 中搜索。如果 script 是一个目录，那么该目录中的所有文件都将被冻结。

opt 是编译 .py 到 .mpy 时传递给 mpy-cross 的优化级别。这些级别在 microropython.opt_level() 中描述。

freeze_as_str(path)

以字符串形式冻结给定path和其中的所有 .py 脚本，并在导入时进行编译。

freeze_as_mpy(path, script=None, opt=0)

首先将 .py 脚本编译成 .mpy 文件，然后冻结输入的 .mpy 文件。有关参数的详细信息，请参阅 freeze()。

freeze_mpy(path, script=None, opt=0)

冻结.mpy文件。参数可以参考freeze()。

举例

要冻结当前目录下的单个文件，并可以import mydriver：

module("mydriver.py")

冻结当前目录下 "mydriver "子目录中的文件目录，并可以import mydriver ：

package("mydriver")

冻结 microropython-lib 中的 "hmac "库：

require("hmac")

一个完整的PYBD_SF2电路板自定义 manifest.py 文件示例：

# 包含电路板缺省的manifest.
include("$(BOARD_DIR)/manifest.py")
# 添加一个自定义驱动
module("mydriver.py")
# 从micropython-lib添加aiorepl
require("aiorepl")

然后就可以用：

$ cd ports/stm32
$ make BOARD=PYBD_SF2 FROZEN_MANIFEST=~/src/myproject/manifest.py

请注意，大多数板卡都没有自己的 manifest.py，而是直接使用 port 的 manifest.py，在这种情况下manifest应该用include("$(PORT_DIR)/boards/manifest.py")替代。