Skip to content

Files

Latest commit

36fe9bb · Sep 26, 2024

History

History
This branch is 1029 commits behind micropython/micropython:master.

unix

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Jan 30, 2024
Jul 20, 2024
Sep 23, 2024
Sep 10, 2024
Sep 26, 2024
Sep 19, 2024
Aug 26, 2024
Sep 1, 2020
Sep 26, 2024
Feb 15, 2024
Sep 6, 2017
Aug 14, 2024
Sep 23, 2024
Jul 4, 2024
Jul 20, 2024
Jul 4, 2024
Mar 7, 2024
Jul 15, 2024
Mar 7, 2024
Jul 17, 2024
Sep 8, 2020
Apr 21, 2023
Mar 7, 2024
Jul 17, 2024
Sep 26, 2024
Sep 6, 2024
Jan 5, 2024
Nov 13, 2020
Sep 8, 2020
Mar 7, 2024
May 23, 2022
Feb 27, 2020
Mar 7, 2024

README.md

MicroPython Unix port

The "unix" port runs in standard Unix-like environments including Linux, BSD, macOS, and Windows Subsystem for Linux.

The x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well as ARM and MIPS. Extending the unix port to another architecture requires writing some assembly code for the exception handling and garbage collection. Alternatively, a fallback implementation based on setjmp/longjmp can be used.

Building

Dependencies

To build the unix port locally then you will need:

  • git command line executable, unless you downloaded a source .tar.xz file from https://micropython.org/download/
  • gcc (or clang for macOS) toolchain
  • GNU Make
  • Python 3.x

To build the default "standard" variant and configuration, then you will also need:

  • pkg-config tool
  • libffi library and headers

On Debian/Ubuntu/Mint and related Linux distros, you can install all these dependencies with a command like:

# apt install build-essential git python3 pkg-config libffi-dev

(See below for steps to build either a standalone or minimal MicroPython executable that doesn't require system libffi or pkg-config.)

Default build steps

To set up the environment for building (not needed every time), starting from the top-level MicroPython directory:

$ cd ports/unix
$ make -C ../../mpy-cross
$ make submodules

The mpy-cross step builds the MicroPython cross-compiler. The make submodules step can be skipped if you didn't clone the MicroPython source from git.

Next, to build the actual executable (still in the ports/unix directory):

$ make

Then to give it a try:

$ ./build-standard/micropython
>>> list(5 * x + y for x in range(10) for y in [4, 2, 1])

Use CTRL-D (i.e. EOF) to exit the shell.

Learn about command-line options (in particular, how to increase heap size which may be needed for larger applications):

$ ./build-standard/micropython -h

To run the complete testsuite, use:

$ make test

The Unix port comes with a built-in package manager called mip, e.g.:

$ ./build-standard/micropython -m mip install hmac

or

$ ./build-standard/micropython
>>> import mip
>>> mip.install("hmac")

Browse available modules at micropython-lib. See Package management for more information about mip.

Minimal Variant

The "standard" variant of MicroPython is the default. It enables most features, including external modules interfaced using libffi. To instead build the "minimal" variant, which disables almost all optional features and modules:

$ cd ports/unix
$ make submodules
$ make VARIANT=minimal

The executable will be built at build-minimal/micropython.

Additional variants can be found in the variants sub-directory of the port, although these are mostly of interest to MicroPython maintainers.

Standalone build

By default, the "standard" variant uses pkg-config to link to the system's shared libffi library.

It is possible to instead build a standalone MicroPython where libffi is built from source and linked statically into the micropython executable. This is mostly useful for embedded or cross-compiled applications.

Building standalone requires autoconf and libtool to also be installed.

To build standalone:

$ export MICROPY_STANDALONE=1
$ make submodules                # fetches libffi submodule
$ make deplibs                   # build just the external libraries
$ make                           # build MicroPython itself

make deplibs causes all supported external libraries (currently only libffi) to be built inside the build directory, so it needs to run again only after make clean.

If you intend to build MicroPython with additional options (like cross-compiling), the same set of options should be passed to both make deplibs and make.

Other dependencies

To actually enable/disable use of dependencies, edit the ports/unix/mpconfigport.mk file, which has inline descriptions of the options. For example, to build the SSL module, MICROPY_PY_SSL should be set to 1.

Debug Symbols

By default, builds are stripped of symbols and debug information to save size.

To build a debuggable version of the Unix port, there are two options:

  1. Run make [other arguments] DEBUG=1. Note setting DEBUG also reduces the optimisation level and enables assertions, so it's not a good option for builds that also want the best performance.
  2. Run make [other arguments] STRIP=. Note that the value of STRIP is empty. This will skip the build step that strips symbols and debug information, but changes nothing else in the build configuration.

Optimisation Level

The default compiler optimisation level is -Os, or -Og if DEBUG=1 is set.

Setting the variable COPT will explicitly set the optimisation level. For example make [other arguments] COPT=-O0 DEBUG=1 will build a binary with no optimisations, assertions enabled, and debug symbols.