Skip to content

Commit 6170ebc

Browse files
mathieucarboumathieucarbou
committed
Update website
1 parent e49293a commit 6170ebc

2 files changed

Lines changed: 173 additions & 0 deletions

File tree

‎docs/hosted-build.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Hosted Build (Arduino Emulator)
2+
3+
ESPAsyncWebServer can be compiled and run as a **native executable** on Linux, Windows, and macOS using the [Arduino-Emulator](https://github.com/pschatzmann/Arduino-Emulator) and [PosixAsyncTCP](https://github.com/MitchBradley/PosixAsyncTCP) libraries.
4+
5+
This allows you to:
6+
7+
- Build and run the server locally without any embedded hardware
8+
- Iterate quickly on server logic without flashing a device
9+
- Integrate the server into CI pipelines for compile-time and basic runtime testing
10+
11+
The compiled binary is a real HTTP/WebSocket server that listens on a local port and can be tested with any HTTP client.
12+
13+
---
14+
15+
## Requirements
16+
17+
| Tool | Notes |
18+
|------|-------|
19+
| CMake ≥ 3.11 | Build system |
20+
| Ninja (recommended) or Make | Generator |
21+
| C++17 compiler | GCC, Clang, or MSVC |
22+
| Git | Cloning dependencies |
23+
24+
The following external repositories must be cloned before building:
25+
26+
| Repository | Purpose | Clone path |
27+
|-----------|---------|------------|
28+
| [pschatzmann/Arduino-Emulator](https://github.com/pschatzmann/Arduino-Emulator) | Arduino core emulation (millis, delay, String, Serial, …) | `.ci/arduino-emulator` |
29+
| [MitchBradley/PosixAsyncTCP](https://github.com/MitchBradley/PosixAsyncTCP) | POSIX socket-based AsyncTCP replacement | `.ci/asynctcp` |
30+
| [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) | FS/LittleFS headers | `.ci/arduino-esp32` |
31+
32+
---
33+
34+
## Cloning dependencies
35+
36+
```bash
37+
git clone --depth 1 --recurse-submodules \
38+
https://github.com/pschatzmann/Arduino-Emulator.git \
39+
.ci/arduino-emulator
40+
41+
git clone --depth 1 \
42+
https://github.com/MitchBradley/PosixAsyncTCP \
43+
.ci/asynctcp
44+
45+
git clone --depth 1 \
46+
https://github.com/espressif/arduino-esp32.git \
47+
.ci/arduino-esp32
48+
```
49+
50+
---
51+
52+
## Building
53+
54+
The CMake project is located at [`examples/arduino_emulator/`](https://github.com/ESP32Async/ESPAsyncWebServer/tree/master/examples/arduino_emulator).
55+
56+
```bash
57+
# Configure
58+
cmake -S examples/arduino_emulator \
59+
-B .ci/arduino-emulator-build/out \
60+
-G Ninja
61+
62+
# Build the host executable
63+
cmake --build .ci/arduino-emulator-build/out \
64+
--target espasyncwebserver_host \
65+
--parallel
66+
```
67+
68+
This produces the `espasyncwebserver_host` executable in the build output directory.
69+
70+
---
71+
72+
## Running
73+
74+
```bash
75+
chmod +x .ci/arduino-emulator-build/out/espasyncwebserver_host
76+
.ci/arduino-emulator-build/out/espasyncwebserver_host
77+
```
78+
79+
The server starts on port **8080** by default. You can test it with:
80+
81+
```bash
82+
curl http://localhost:8080/
83+
```
84+
85+
Expected output:
86+
87+
```
88+
ESPAsyncWebServer host app is running on port 8080
89+
```
90+
91+
---
92+
93+
## Example application
94+
95+
The entry point is [`examples/arduino_emulator/main.cpp`](https://github.com/ESP32Async/ESPAsyncWebServer/tree/master/examples/arduino_emulator/main.cpp):
96+
97+
```cpp
98+
#include <Arduino.h>
99+
#include <AsyncTCP.h>
100+
#include <ESPAsyncWebServer.h>
101+
102+
static AsyncWebServer server(8080);
103+
104+
void setup() {
105+
server.on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
106+
request->send(200, "text/plain",
107+
"ESPAsyncWebServer host app is running on port 8080\n");
108+
});
109+
110+
server.onNotFound([](AsyncWebServerRequest *request) {
111+
request->send(404, "text/plain", "Not found\n");
112+
});
113+
114+
PosixAsyncTCPManager::getInstance().begin();
115+
server.begin();
116+
}
117+
118+
void loop() {
119+
delay(1000);
120+
}
121+
```
122+
123+
The standard `setup()` / `loop()` structure is identical to embedded Arduino code. Arduino-Emulator calls these functions and provides the Arduino API.
124+
125+
---
126+
127+
## CMake project structure
128+
129+
[`examples/arduino_emulator/CMakeLists.txt`](https://github.com/ESP32Async/ESPAsyncWebServer/tree/master/examples/arduino_emulator/CMakeLists.txt) defines three targets:
130+
131+
| CMake target | Description |
132+
|-------------|-------------|
133+
| `arduino_emulator` | Arduino core (provided by Arduino-Emulator via `add_subdirectory`) |
134+
| `espasyncwebserver` | All `src/*.cpp` files compiled as a static library |
135+
| `test` | AsyncTCP, FS, and base64 support compiled as a static library |
136+
| `espasyncwebserver_host` | Final executable linking everything together |
137+
138+
The `HOST` preprocessor definition is set on all targets so that platform-specific code (e.g. lwIP headers) is conditionally excluded at compile time.
139+
140+
---
141+
142+
## Preprocessor define
143+
144+
When building for the host, the `HOST` macro is defined:
145+
146+
```cmake
147+
target_compile_definitions(espasyncwebserver PUBLIC HOST ARDUINO=10813)
148+
```
149+
150+
You can use it in your own code to guard any embedded-only sections:
151+
152+
```cpp
153+
#ifndef HOST
154+
// ESP32/ESP8266-only code
155+
WiFi.begin(ssid, password);
156+
#endif
157+
```
158+
159+
---
160+
161+
## CI integration
162+
163+
The [Build (Arduino Emulator)](https://github.com/ESP32Async/ESPAsyncWebServer/actions/workflows/build-arduino-emulator.yml) GitHub Actions workflow runs this build automatically on every push and pull request targeting `main` or `release/*` branches.
164+
165+
The workflow runs on **Ubuntu** (`ubuntu-latest`) and performs the following steps:
166+
167+
1. Install `cmake`, `ninja-build`, `build-essential`, and `git`
168+
2. Clone Arduino-Emulator, PosixAsyncTCP, and arduino-esp32
169+
3. Configure and build the `espasyncwebserver_host` target
170+
4. Mark the resulting binary as executable
171+
172+
See [`.github/workflows/build-arduino-emulator.yml`](https://github.com/ESP32Async/ESPAsyncWebServer/blob/master/github/workflows/build-arduino-emulator.yml) for the full workflow definition.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,5 +53,6 @@ nav:
5353
- Event Source (SSE): eventsource.md
5454
- Serving Static Files: static-files.md
5555
- Filters & Rewrites: filters.md
56+
- Hosted Build (Arduino Emulator): hosted-build.md
5657
- Help & Issues: help_and_issues.md
5758
- Code of Conduct: code_of_conduct.md

0 commit comments

Comments
 (0)