Skip to content

OS Development on MacOS

Most users can just use a pre-built binary from the releases page and install it manually or using the web installer.

But if for some reason that one doesn't work, or you really want to modify things under the hood, you're in the right place here!

Get the prerequisites

Clone the repositories:

git clone --recurse-submodules https://github.com/MicroPythonOS/MicroPythonOS.git

That will take a while, because it recursively clones MicroPython, LVGL, ESP-IDF and all their dependencies.

While that's going on, make sure you have everything installed to compile code:

xcode-select --install
brew install pkg-config libffi ninja make SDL2

Compile the code

  1. Make sure you're in the main repository:

    cd MicroPythonOS/

  2. Start the Compilation

    Usage:

    ./scripts/build_mpos.sh <target system> <build type (prod or dev)> [optional target device]

    Target systems: esp32, unix (= Linux) and macOS

    Build types:

    • A prod build includes the complete filesystem that's "frozen" into the build, so it's fast and all ready to go but the files in /lib and /builtin will be read-only.
    • A dev build comes without a filesystem, so it's perfect for power users that want to work on MicroPythonOS internals. There's a simple script that will copy all the necessary files over later, and these will be writeable.

    Note: for unix and macOS systems, only dev has been tested. The prod builds might have issues but should be made to work soon.

    Target devices: waveshare-esp32-s3-touch-lcd-2 or fri3d-2024

    Examples:

    ./scripts/build_mpos.sh esp32 prod fri3d-2024
./scripts/build_mpos.sh esp32 dev waveshare-esp32-s3-touch-lcd-2
./scripts/build_mpos.sh esp32 unix dev
./scripts/build_mpos.sh esp32 macOS dev

    The resulting build file will be in lvgl_micropython/build/, for example:

    • lvgl_micropython/build/lvgl_micropy_unix
    • lvgl_micropython/build/lvgl_micropy_macOS
    • lvgl_micropython/build/lvgl_micropy_ESP32_GENERIC_S3-SPIRAM_OCT-16.bin

Running on Linux or MacOS

  1. Make sure you have the software

    Either you built your own on MacOS or Linux or you can download a pre-built executable binary (e.g., MicroPythonOS_amd64_Linux, MicroPythonOS_amd64_MacOS) from the releases page.

    Give it executable permissions:

    chmod +x /path/to/MicroPythonOS_executable_binary

  2. Make sure you have the local_filesystem/ folder

    You probably already have a local clone that contains the internal_filesystem.

    If not, then clone it now:

    git clone --recurse-submodules https://github.com/MicroPythonOS/MicroPythonOS.git
cd MicroPythonOS/

  3. Start it from the local_filesystem/ folder:

    cd internal_filesystem/ # make sure you're in the right place to find the filesystem
/path/to/MicroPythonOS_executable_binary -X heapsize=32M -v -i -c "$(cat boot_unix.py main.py)"

    There's also a convenient ./scripts/run_desktop.sh script that will attempt to start the latest build that you compiled yourself.

Modifying files

You'll notice that, whenever you change a file on your local system, the changes are immediately visible whenever you reload the file.

This results in a very quick coding cycle.

Give this a try by editing internal_filesystem/builtin/apps/com.micropythonos.about/assets/about.py and then restarting the "About" app. Powerful stuff!