MicroPython 清单文件

当为设备编译固件时，以下组件将被包含在编译过程中:

  • 核心 MicroPython 虚拟机和运行时

  • 固件中指定的微处理器/设备接口的特定适配的系统代码和驱动程序

  • 标准内置模块，如 sys

  • 扩展内置模块，如 json 和 machine

  • C/C++ 编写的额外模块

  • Python 编写的额外模块

所有在固件中包含的模块都可以通过 Python 代码中的 import 语句来使用。在编译过程中编写的 Python 额外模块（上述最后一项）称为 冻结模块，并在 manifest.py 文件中指定。修改此清单文件要求重新编译固件。

你也可以在设备运行时向文件系统中添加额外的模块。在文件系统添加和删除模块不需要重新编译固件，因此它是一个更简单的方式。使用清单文件是优势是，冻结模块更高效：它们在导入时更快，而且占用的内存更少。

MicroPython 清单文件是 Python 文件，可以包含任意的 Python 代码。其中还有一组命令（预定义的函数）用于指定要包含的 Python 源文件。这些命令在下面描述。

冻结源代码

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

冻结的入参通过 path 指定后，自动确定其类型。一个 .py 脚本将会被编译为 .mpy 再冻结，而一个 .mpy 文件则可直接冻结。

path 必须是一个目录，代表要搜索文件的基础目录。导入指定的冻结模块时，模块的名称将从 path 后开始，即 path 不会包含在模块名称中。

如果 path 是相对路径，则会被解析到当前的 manifest.py 的相对路径。如果需要访问特定的路径，请使用 $(MPY_DIR)、$(MPY_LIB_DIR)、$(PORT_DIR)、$(BOARD_DIR)。

如果 script 是 None，则 path 下的所有文件都会被冻结。

如果 script 是一个可遍历的集合，则会调用 freeze() 函数对可遍历集合中的所有项进行冻结（传递相同的 path 和 opt 参数）。

如果 script 是一个字符串，则代表指定要冻结的文件或目录，并可以在文件或最后一个目录之前包含额外的目录。 path 下的文件或目录都会被搜索。如果 script 是一个目录，则该目录下的所有文件都会被冻结。

传递给 mpy-cross 的 opt 参数用于指定编译 .py 到 .mpy 的优化级别。

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 文件。

包含其它的 manifest 文件

include(manifest, **kwargs)

包含另一个 manifest 文件。

manifest 参数可以是一个字符串（文件名）或者一个可遍历的字符串集合。

相对路径会被解析为当前 manifest 文件的相对路径。

可选的 kwargs 参数可以提供给通过 options 配置被包含的脚本。

例如：

include("path.py", extra_features=True)

然后在 path.py 中：

options.defaults(standard_features=True)
# freeze minimal modules.
if options.standard_features:
    # freeze standard modules.
if options.extra_features:
    # freeze extra modules.

示例

要冻结一个可以通过 import mydriver 进行导入的单个文件，请使用：

freeze(".", "mydriver.py")

要冻结一个可以通过 import test1 和 import test2 进行导入的文件集合，并且这些文件会被编译为优化级别为 3 的文件，请使用：

freeze("/path/to/tests", ("test1.py", "test2.py"), opt=3)

要冻结一个可以通过 import mymodule 进行导入的模块，请使用：

freeze(
    "../relative/path",
    (
        "mymodule/__init__.py",
        "mymodule/core.py",
        "mymodule/extra.py",
    ),
)

要包含来自 MicroPython 代码仓中的 manifest 文件，请使用：

include("$(MPY_DIR)/extmod/uasyncio/manifest.py")