MicroPython manifest files

When building firmware for a device the following components are included in the compilation process:

  • the core MicroPython virtual machine and runtime

  • port-specific system code and drivers to interface with the microcontroller/device that the firmware is targeting

  • standard built-in modules, like sys

  • extended built-in modules, like json and machine

  • extra modules written in C/C++

  • extra modules written in Python

All the modules included in the firmware are available via import from Python code. The extra modules written in Python that are included in a build (the last point above) are called frozen modules, and are specified by a manifest.py file. Changing this manifest requires rebuilding the firmware.

It’s also possible to add additional modules to the filesystem of the device once it is up and running. Adding and removing modules to/from the filesystem does not require rebuilding the firmware so is a simpler process than rebuilding firmware. The benefit of using a manifest is that frozen modules are more efficient: they are faster to import and take up less RAM once imported.

MicroPython manifest files are Python files and can contain arbitrary Python code. There are also a set of commands (predefined functions) which are used to specify the Python source files to include. These commands are described below.

Freezing source code

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

Freeze the input specified by path, automatically determining its type. A .py script will be compiled to a .mpy first then frozen, and a .mpy file will be frozen directly.

path must be a directory, which is the base directory to begin searching for files. When importing the resulting frozen modules, the name of the module will start after path, i.e. path is excluded from the module name.

If path is relative, it is resolved to the current manifest.py. Use $(MPY_DIR), $(MPY_LIB_DIR), $(PORT_DIR), $(BOARD_DIR) if you need to access specific paths.

If script is None, all files in path will be frozen.

If script is an iterable then freeze() is called on all items of the iterable (with the same path and opt passed through).

If script is a string then it specifies the file or directory to freeze, and can include extra directories before the file or last directory. The file or directory will be searched for in path. If script is a directory then all files in that directory will be frozen.

opt is the optimisation level to pass to mpy-cross when compiling .py to .mpy.

freeze_as_str(path)

Freeze the given path and all .py scripts within it as a string, which will be compiled upon import.

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

Freeze the input by first compiling the .py scripts to .mpy files, then freezing the resulting .mpy files. See freeze() for further details on the arguments.

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

Freeze the input, which must be .mpy files that are frozen directly. See freeze() for further details on the arguments.

Including other manifest files

include(manifest, **kwargs)

Include another manifest.

The manifest argument can be a string (filename) or an iterable of strings.

Relative paths are resolved with respect to the current manifest file.

Optional kwargs can be provided which will be available to the included script via the options variable.

For example:

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

then in path.py:

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

Examples

To freeze a single file which is available as import mydriver, use:

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

To freeze a set of files which are available as import test1 and import test2, and which are compiled with optimisation level 3, use:

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

To freeze a module which can be imported as import mymodule, use:

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

To include a manifest from the MicroPython repository, use:

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