You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 26, 2026. It is now read-only.
Copy file name to clipboardExpand all lines: docs/embedded-proplet.md
+129Lines changed: 129 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -71,3 +71,132 @@ For debugging and diagnostics, the configuration enables logging with a default
71
71
- WASM Handler : Interfaces with WAMR to load, execute, and manage WASM modules on the embedded device, enforcing isolation and resource constraints.
72
72
- Configuration and Build System: Defines system parameters, dependencies, and build instructions to streamline deployment on Zephyr OS.
73
73
- Data Serialization: Handles encoding and decoding of structured data in JSON format for efficient message parsing within the Propeller network.
74
+
75
+
## Setup
76
+
77
+
When running:
78
+
79
+
```bash
80
+
west build -b esp32s3_devkitc/esp32s3/procpu -p auto .
81
+
```
82
+
83
+
CMake might stop with:
84
+
85
+
```bash
86
+
Could NOT find Threads (missing: Threads_FOUND)
87
+
...
88
+
FATAL ERROR: command exited with status 1: ...
89
+
```
90
+
91
+
This is triggered by WAMR’s top-level `CMakeLists.txt` in `wasm-micro-runtime/`, specifically the lines:
92
+
93
+
```cmake
94
+
set (THREADS_PREFER_PTHREAD_FLAG ON)
95
+
find_package(Threads REQUIRED)
96
+
```
97
+
98
+
because `WAMR` tries to detect and link `pthread` on the `host` system (Linux, Windows, macOS).
99
+
100
+
- However, on `Zephyr`, especially for an `ESP32-S3` target, we do not use the host’s pthread library at all. There’s no concept of a local Linux “Threads” library in a cross-compile for an Xtensa SoC.
101
+
- So CMake’s `find_package(Threads REQUIRED)` fails with “Could NOT find Threads” because there’s no suitable host pthread dev package to fulfill that requirement in the cross-compilation environment.
102
+
103
+
Installing host pthread dev files sometimes helps in a purely local scenario, but it can still fail or is semantically incorrect for embedded cross-builds.
104
+
105
+
The Solution is to bypass `find_package(Threads REQUIRED)` on Zephyr. So, in your WAMR repo file `wasm-micro-runtime/CMakeLists.txt`, locate where it calls:
106
+
107
+
```cmake
108
+
find_package(Threads REQUIRED)
109
+
```
110
+
111
+
and wrap that call in a conditional so it does not run on Zephyr:
112
+
113
+
```cmake
114
+
if (NOT WAMR_BUILD_PLATFORM STREQUAL "zephyr")
115
+
set (THREADS_PREFER_PTHREAD_FLAG ON)
116
+
find_package(Threads REQUIRED)
117
+
endif()
118
+
```
119
+
120
+
then clean and rebuild:
121
+
122
+
```bash
123
+
rm -rf build
124
+
west build -b esp32s3_devkitc/esp32s3/procpu -p auto .
125
+
```
126
+
127
+
### Dynamic Linking
128
+
129
+
Zephyr does not support dynamic linking on most embedded targets (including ESP32-S3). When WAMR’s CMakeLists tries:
130
+
131
+
```cmake
132
+
add_library(iwasm_shared SHARED ...)
133
+
```
134
+
135
+
you see the warning:
136
+
137
+
```cmake
138
+
ADD_LIBRARY called with SHARED option but the target platform does not support
139
+
dynamic linking. Building a STATIC library instead. This may lead to problems.
140
+
```
141
+
142
+
This is harmless on Zephyr—it just forces the shared library to become a static library—but it can be confusing. To fix it, you should skip building a shared library entirely when you are on Zephyr.
143
+
144
+
In your `modules/wamr/wasm-micro-runtime/CMakeLists.txt`, right after you set `WAMR_BUILD_PLATFORM="zephyr"`, force shared libs off:
145
+
146
+
```cmake
147
+
if (WAMR_BUILD_PLATFORM STREQUAL "zephyr")
148
+
set(WAMR_BUILD_SHARED 0 CACHE BOOL "Disable shared library on Zephyr" FORCE)
149
+
endif ()
150
+
```
151
+
152
+
If that’s in place, the `if (WAMR_BUILD_SHARED)` block that calls:
That way, the shared library part is skipped on Zephyr.
172
+
173
+
Either approach ensures the warning disappears, and you end up only with a static WAMR build (`iwasm_static`) on Zephyr, which is what you actually need.
174
+
175
+
### Configuration Files
176
+
177
+
Configuration options are split between `prj.conf` and `esp32s3-devkitc.conf`, which Zephyr's build system merges based on the board and build target. Follow best practices to avoid conflicting settings.
178
+
179
+
### **Purpose of Each File**
180
+
181
+
1.**`prj.conf`:**
182
+
183
+
- Application-specific settings.
184
+
- Defines project-specific features, libraries, and behaviors.
185
+
186
+
2.**`esp32s3-devkitc.conf`:**
187
+
188
+
- Board-specific settings.
189
+
- Configures hardware-specific options for the ESP32-S3.
190
+
191
+
3.**`esp32s3-devkitc.overlay`:**
192
+
- Extends or modifies the board's Devicetree source.
193
+
194
+
### **Configuration Hierarchy**
195
+
196
+
Zephyr processes files in this order:
197
+
198
+
1.**Default Kconfig files**: Zephyr subsystems and modules.
If a setting appears in both `prj.conf` and `esp32s3-devkitc.conf`, the value in `prj.conf` takes precedence. Avoid duplicate definitions to prevent conflicts.
0 commit comments