146 lines
4.8 KiB
ReStructuredText
146 lines
4.8 KiB
ReStructuredText
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
|
|
--------------------
|
|
|
|
.. function:: 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``.
|
|
|
|
.. function:: freeze_as_str(path)
|
|
|
|
Freeze the given *path* and all ``.py`` scripts within it as a string, which
|
|
will be compiled upon import.
|
|
|
|
.. function:: 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.
|
|
|
|
.. function:: 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
|
|
------------------------------
|
|
|
|
.. function:: 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:
|
|
|
|
.. code-block:: python3
|
|
|
|
include("path.py", extra_features=True)
|
|
|
|
then in path.py:
|
|
|
|
.. code-block:: python3
|
|
|
|
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:
|
|
|
|
.. code-block:: python3
|
|
|
|
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:
|
|
|
|
.. code-block:: python3
|
|
|
|
freeze("/path/to/tests", ("test1.py", "test2.py"), opt=3)
|
|
|
|
To freeze a module which can be imported as ``import mymodule``, use:
|
|
|
|
.. code-block:: python3
|
|
|
|
freeze(
|
|
"../relative/path",
|
|
(
|
|
"mymodule/__init__.py",
|
|
"mymodule/core.py",
|
|
"mymodule/extra.py",
|
|
),
|
|
)
|
|
|
|
To include a manifest from the MicroPython repository, use:
|
|
|
|
.. code-block:: python3
|
|
|
|
include("$(MPY_DIR)/extmod/uasyncio/manifest.py")
|