# 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.