Merge pull request 'lopez/esp32' (#1) from lopez/esp32 into main

Reviewed-on: #1

esp32/Makefile

@@ -0,0 +1,62 @@
+# ========================================================== #
+# Spider Runtime - ESP32 Build System                        #
+# Toolchain: Espressif ESP-IDF (xtensa-esp-elf-g++)          #
+# ========================================================== #
+
+CC          := xtensa-esp-elf-g++
+TARGET      := spider_esp32.elf
+SRCDIR      := ../../src
+BUILDDIR    := bin
+TARGETDIR   := out
+SRCEXT      := cpp
+OBJEXT      := o
+
+ESP_FLAGS   := -DESP32 -DSPIDER_DISTRO_MICRO -DSPIDER_OS_NONE -mlongcalls -ffunction-sections -fdata-sections -fno-exceptions -fno-rtti
+
+# -O0: no optimizations, faster compilation during development
+CFLAGS      := -Wall -std=c++20 -O0 -DSPIDER_COMPILING $(ESP_FLAGS)
+LFLAGS      := -Wl,--gc-sections -mlongcalls
+INC         := -I../../src/
+
+# Exclude desktop-only modules
+EXCLUDE     := $(SRCDIR)/spider/runtime/util/Terminal.cpp \
+               $(SRCDIR)/spider/runtime/debug/LiveDebug.cpp \
+               $(SRCDIR)/spider/SpiderRuntime.cpp
+
+# ESP32 specific entry point (local to this build folder)
+EXTRA       := ./main_esp32.cpp
+
+SOURCES     := $(filter-out $(EXCLUDE), $(shell find $(SRCDIR) -type f -name "*.$(SRCEXT)" 2>/dev/null)) $(EXTRA)
+OBJECTS     := $(patsubst ./%,$(BUILDDIR)/%,$(patsubst $(SRCDIR)/%,$(BUILDDIR)/%,$(SOURCES:.$(SRCEXT)=.$(OBJEXT))))
+
+all: directories $(TARGET)
+	@echo "Build complete: $(TARGETDIR)/$(TARGET)"
+
+remake: cleaner all
+
+directories:
+	@mkdir -p $(TARGETDIR)
+	@mkdir -p $(BUILDDIR)
+
+clean:
+	@$(RM) -rf $(BUILDDIR)
+
+cleaner: clean
+	@$(RM) -rf $(TARGETDIR)
+
+$(TARGET): $(OBJECTS)
+	@echo "Linking $(TARGET)..."
+	$(CC) $(LFLAGS) -o $(TARGETDIR)/$(TARGET) $^
+	@echo "Done!"
+
+$(BUILDDIR)/%.$(OBJEXT): $(SRCDIR)/%.$(SRCEXT)
+	@mkdir -p $(dir $@)
+	@echo "Compiling $<..."
+	$(CC) $(CFLAGS) $(INC) -c -o $@ $<
+
+$(BUILDDIR)/%.$(OBJEXT): ./%.$(SRCEXT)
+	@mkdir -p $(dir $@)
+	@echo "Compiling $<..."
+	$(CC) $(CFLAGS) $(INC) -c -o $@ $<
+
+.PHONY: all remake clean cleaner

esp32/README.md

@@ -0,0 +1,83 @@
+# ESP32 Build Tools for Spider Runtime
+
+Build system for compiling the Spider Runtime for the ESP32
+microcontroller using the Espressif Xtensa toolchain.
+
+---
+
+## Requirements
+
+- [ESP-IDF v5.x](https://dl.espressif.com/dl/esp-idf/) installed
+- MSYS2 or any Unix-like shell
+- `spider-runtime` repository cloned at the same level as this repo
+
+Expected folder structure:
+```
+Internship/
+    spider-runtime/
+    spider-micro-buildtools/
+        esp32/   ← you are here
+```
+
+Add the Xtensa toolchain to your PATH before building:
+```bash
+export PATH=$PATH:/c/Espressif/tools/xtensa-esp-elf/<version>/xtensa-esp-elf/bin
+```
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `Makefile` | Build recipe for ESP32 using `xtensa-esp-elf-g++` |
+| `gen_makefile.py` | Regenerates the Makefile (run if Makefile gets corrupted) |
+| `main_esp32.cpp` | ESP32 entry point, replaces the desktop `main()` |
+
+---
+
+## Build
+```bash
+make
+```
+
+Output: `out/spider_esp32.elf`
+
+To clean and rebuild from scratch:
+```bash
+make cleaner
+make
+```
+
+---
+
+## Flash to ESP32
+
+**Step 1 — Convert to flashable binary:**
+```bash
+xtensa-esp-elf-objcopy -O binary out/spider_esp32.elf out/spider_esp32.bin
+```
+
+**Step 2 — Connect your ESP32 via USB and find the COM port**
+
+On Windows, check Device Manager under "Ports (COM & LPT)".
+
+**Step 3 — Flash:**
+```bash
+esptool.py --chip esp32 --port COM3 --baud 115200 write_flash 0x1000 out/spider_esp32.bin
+```
+
+Replace `COM3` with your actual port.
+
+---
+
+## Compiler Flags
+
+| 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 |
+| `-fno-exceptions -fno-rtti` | Disable unavailable C++ features |
+| `-O0` | No optimizations, faster development builds |

esp32/gen_makefile.py

@@ -0,0 +1,70 @@
+tab = '\t'
+dollar = '$'
+
+content = f"""# ========================================================== #
+# Spider Runtime - ESP32 Build System                        #
+# Toolchain: Espressif ESP-IDF (xtensa-esp-elf-g++)          #
+# ========================================================== #
+
+CC          := xtensa-esp-elf-g++
+TARGET      := spider_esp32.elf
+SRCDIR      := ../../src
+BUILDDIR    := bin
+TARGETDIR   := out
+SRCEXT      := cpp
+OBJEXT      := o
+
+ESP_FLAGS   := -DESP32 -DSPIDER_DISTRO_MICRO -DSPIDER_OS_NONE -mlongcalls -ffunction-sections -fdata-sections -fno-exceptions -fno-rtti
+
+# -O0: no optimizations, faster compilation during development
+CFLAGS      := -Wall -std=c++20 -O0 -DSPIDER_COMPILING {dollar}(ESP_FLAGS)
+LFLAGS      := -Wl,--gc-sections -mlongcalls
+INC         := -I../../src/
+
+# Exclude desktop-only modules
+EXCLUDE     := {dollar}(SRCDIR)/spider/runtime/util/Terminal.cpp \\
+               {dollar}(SRCDIR)/spider/runtime/debug/LiveDebug.cpp \\
+               {dollar}(SRCDIR)/spider/SpiderRuntime.cpp
+
+# ESP32 specific entry point (local to this build folder)
+EXTRA       := ./main_esp32.cpp
+
+SOURCES     := {dollar}(filter-out {dollar}(EXCLUDE), {dollar}(shell find {dollar}(SRCDIR) -type f -name "*.{dollar}(SRCEXT)" 2>/dev/null)) {dollar}(EXTRA)
+OBJECTS     := {dollar}(patsubst ./%,{dollar}(BUILDDIR)/%,{dollar}(patsubst {dollar}(SRCDIR)/%,{dollar}(BUILDDIR)/%,{dollar}(SOURCES:.{dollar}(SRCEXT)=.{dollar}(OBJEXT))))
+
+all: directories {dollar}(TARGET)
+{tab}@echo "Build complete: {dollar}(TARGETDIR)/{dollar}(TARGET)"
+
+remake: cleaner all
+
+directories:
+{tab}@mkdir -p {dollar}(TARGETDIR)
+{tab}@mkdir -p {dollar}(BUILDDIR)
+
+clean:
+{tab}@{dollar}(RM) -rf {dollar}(BUILDDIR)
+
+cleaner: clean
+{tab}@{dollar}(RM) -rf {dollar}(TARGETDIR)
+
+{dollar}(TARGET): {dollar}(OBJECTS)
+{tab}@echo "Linking {dollar}(TARGET)..."
+{tab}{dollar}(CC) {dollar}(LFLAGS) -o {dollar}(TARGETDIR)/{dollar}(TARGET) {dollar}^
+{tab}@echo "Done!"
+
+{dollar}(BUILDDIR)/%.{dollar}(OBJEXT): {dollar}(SRCDIR)/%.{dollar}(SRCEXT)
+{tab}@mkdir -p {dollar}(dir {dollar}@)
+{tab}@echo "Compiling {dollar}<..."
+{tab}{dollar}(CC) {dollar}(CFLAGS) {dollar}(INC) -c -o {dollar}@ {dollar}<
+
+{dollar}(BUILDDIR)/%.{dollar}(OBJEXT): ./%.{dollar}(SRCEXT)
+{tab}@mkdir -p {dollar}(dir {dollar}@)
+{tab}@echo "Compiling {dollar}<..."
+{tab}{dollar}(CC) {dollar}(CFLAGS) {dollar}(INC) -c -o {dollar}@ {dollar}<
+
+.PHONY: all remake clean cleaner
+"""
+
+with open('Makefile', 'w', newline='\n') as f:
+    f.write(content)
+print("Makefile generated successfully!")

esp32/main_esp32.cpp

@@ -0,0 +1,8 @@
+// ESP32 entry point for Spider Runtime
+// This replaces SpiderRuntime.cpp for microcontroller builds
+#include <spider/SpiderRuntime.hpp>
+
+int main() {
+    // TODO: initialize Spider runtime for ESP32
+    return 0;
+}