Add blog entry 4 - Compiling Spider for ESP32

2026-03-25 16:54:46 -06:00
parent f681e7ef53
commit 55c35942c1
1 changed files with 128 additions and 0 deletions
--- a/blog-post-4.md
+++ b/blog-post-4.md
@@ -0,0 +1,128 @@
+# 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:
+```bash
+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:
+```bash
+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
+```bash
+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:
+```bash
+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:
+```bash
+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:
+```bash
+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.