128 lines
3.3 KiB
Markdown
128 lines
3.3 KiB
Markdown
# 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. |