Compiling Spider for ESP32

This entry documents the process of cross-compiling the Spider Runtime for the ESP32 microcontroller using the Espressif toolchain.

Prerequisites

ESP-IDF installed (v5.x) from https://dl.espressif.com/dl/esp-idf/
MSYS2 or any Unix-like shell
Spider Runtime source code

Add the Xtensa toolchain to your PATH:

export PATH=$PATH:/c/Espressif/tools/xtensa-esp-elf/<version>/xtensa-esp-elf/bin

How it works

Spider source code goes through two compilation stages before running on hardware:

script.spider
    ↓  Spider Compiler
bytecode.spd
    ↓  loaded by
Spider Runtime (C++)
    ↓  compiled by
xtensa-esp-elf-g++
    ↓
spider_esp32.elf  →  flashed to ESP32

The Spider Runtime is written in C++20. The Xtensa cross-compiler translates it into machine code the ESP32 processor can execute directly.

Step 1 — Configure the build flags

The Runtime uses compile-time platform detection. The following flags must be passed to the compiler:

Flag	Purpose
`-DESP32`	Activates ESP32 detection in `distro_mcu.hpp`
`-DSPIDER_DISTRO_MICRO`	Enables microcontroller mode
`-DSPIDER_OS_NONE`	Declares bare-metal, no OS
`-mlongcalls`	Required for Xtensa memory layout
`-ffunction-sections -fdata-sections`	Enable dead code elimination
`-Wl,--gc-sections`	Strip unused sections from binary
`-fno-exceptions -fno-rtti`	Disable C++ features unavailable on bare-metal

Step 2 — Set up the Makefile

Navigate to build/esp32/ and run the build generator:

cd build/esp32
python3 gen_makefile.py

This generates a Makefile that:

Uses xtensa-esp-elf-g++ as the compiler
Excludes desktop-only modules (Terminal.cpp, LiveDebug.cpp)
Uses a minimal ESP32 entry point (main_esp32.cpp) instead of the desktop main()
Compiles all Runtime .cpp files under src/spider/

Step 3 — Compile the Runtime

make

Expected output:

Compiling ../../src/spider/runtime/cpu/CPU.cpp...
Compiling ../../src/spider/runtime/instr/InstrMap.cpp...
...
Linking spider_esp32.elf...
Done!
Build complete: out/spider_esp32.elf

Verify the output is a valid Xtensa binary:

xtensa-esp-elf-objdump -f out/spider_esp32.elf
# Expected: file format elf32-xtensa-be, architecture: xtensa

xtensa-esp-elf-size out/spider_esp32.elf
# Expected: text ~450KB, fits within ESP32's 4MB flash

Step 4 — Convert to flashable binary

ESP-IDF's esptool.py requires a raw .bin file:

xtensa-esp-elf-objcopy -O binary out/spider_esp32.elf out/spider_esp32.bin

Step 5 — Flash to ESP32

Connect the ESP32 via USB. Identify the COM port in Device Manager, then flash:

esptool.py --chip esp32 --port COM3 --baud 115200 write_flash 0x1000 out/spider_esp32.bin

Replace COM3 with your actual port.

Notes

-O0 is used during development for faster compilation. Switch to -Os for production builds to minimize binary size.
main_esp32.cpp is the ESP32 entry point. It will initialize the Spider Runtime once the runtime API is complete.
The Spider bytecode (.spd) is loaded separately into the ESP32's flash memory and read by the Runtime at boot.

3.3 KiB Raw Permalink Blame History