MicroPython的Manifest文件介绍

2024-01-08 04:31:32

摘要

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()会在可迭代的所有条目上调用(使用相同的pathoppt)。

如果 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")替代。

文章来源:https://blog.csdn.net/superatom01/article/details/135447047
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。