From 9729749facf3de276a2eda07a63699462f190aa9 Mon Sep 17 00:00:00 2001 From: Tom Lauwaerts Date: Thu, 9 Jul 2026 18:11:23 +0200 Subject: [PATCH 1/6] Fix just commands in README --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9eb4a854..2e717d3e 100644 --- a/README.md +++ b/README.md @@ -41,8 +41,8 @@ This project is released under the Mozilla Public License 2.0, and is being deve If you use just, the most common project commands are collected in the justfile. To run the virtual machine locally (emulator) for the first time, use: -``` -just setup ; just run emulator tutorials/wat/main/fac.wat +```bash +just setup emulator ; just run emulator tutorials/wat/main/fac.wat ``` ## Build and Development Instructions @@ -185,6 +185,12 @@ The CLI is also used to run the various unit and specification tests for WARDuin To install the CLI perform the following steps starting from the project root folder: +```bash +just build emulator ; echo ; ./build-emu/wdcli --help +``` + +Alternative, when you do not have just, use: + ```bash mkdir build-emu cd build-emu From 8e7f549be26e81078ed105e61c61a55ebe387e65 Mon Sep 17 00:00:00 2001 From: Tom Lauwaerts Date: Thu, 9 Jul 2026 18:24:48 +0200 Subject: [PATCH 2/6] QoL improvements for first time users --- README.md | 69 ++++++++++++++++++++++++++++++------------------------- justfile | 2 +- 2 files changed, 39 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 2e717d3e..85fd0a8a 100644 --- a/README.md +++ b/README.md @@ -48,54 +48,33 @@ just setup emulator ; just run emulator tutorials/wat/main/fac.wat ## Build and Development Instructions > [!NOTE] -> **Supported platforms:** Linux (Ubuntu), macOS, ESP-IDF, Arduino +> **Supported platforms:** Linux (Ubuntu), macOS, Zephyr, ESP-IDF, Arduino The project uses CMake. Quick install looks like this: ```bash git clone --recursive git@github.com:TOPLLab/WARDuino.git cd WARDuino -mkdir build-emu -cd build-emu -cmake .. -D BUILD_EMULATOR=ON -make +just build emulator ``` This will build the command-line tool (`emulator`), which has been tested on both linux and macOS. -The WARDuino VM can be compiled with both the Arduino and ESP-IDF toolchains, and has been extensively tested on different ESP8266 and ESP32 microcontrollers. - -### Build for ESP-IDF - -> [!WARNING] -> Primitive support for IDF is under construction. - -Before you can compile and flash with ESP-IDF, you must install and enable [the toolchain](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html). -You also need to disable the watchdog timer: +```bash +./build-emu/wdcli --help +``` -1. Go to the root folder of the WARDuino repo -2. run `idf.py menuconfig` -3. Under **Component config → ESP System Settings** disable the following options: - - Interrupt watchdog - - Initialize Task Watchdog Timer on startup -4. Save and quit the menu +The WARDuino VM can be compiled with both the Arduino and ESP-IDF toolchains, and has been extensively tested on different ESP8266 and ESP32 microcontrollers. -Make sure the ESP-IDF tools are enabled, otherwise these steps will not work. +### Build for Zephyr -To install the WARDuino with the ESP-IDF toolchain perform the following steps starting from the project root folder: +First, install the [Zephyr SDK](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#getting-started-guide), then run: ```bash -mkdir build -cd build -cmake .. -D BUILD_ESP=ON -make flash +just build zephyr tutorials/wat/main/blink.wat ; just flash zephyr ``` -Or simply run `idf.py flash`. - -### Build for Zephyr - -First, install the [Zephyr SDK](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#getting-started-guide), then follow these steps: +Alternative, when you do not have just, you can follow the following steps: 1. Activate your Zephyr environment: ```bash @@ -198,6 +177,34 @@ cmake .. -D BUILD_EMULATOR=ON make ``` +### Build for ESP-IDF + +> [!WARNING] +> Primitive support for IDF is under construction. + +Before you can compile and flash with ESP-IDF, you must install and enable [the toolchain](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html). +You also need to disable the watchdog timer: + +1. Go to the root folder of the WARDuino repo +2. run `idf.py menuconfig` +3. Under **Component config → ESP System Settings** disable the following options: + - Interrupt watchdog + - Initialize Task Watchdog Timer on startup +4. Save and quit the menu + +Make sure the ESP-IDF tools are enabled, otherwise these steps will not work. + +To install the WARDuino with the ESP-IDF toolchain perform the following steps starting from the project root folder: + +```bash +mkdir build +cd build +cmake .. -D BUILD_ESP=ON +make flash +``` + +Or simply run `idf.py flash`. + ## WebAssembly Specification tests ```shell diff --git a/justfile b/justfile index d4e211b5..9a44b58d 100644 --- a/justfile +++ b/justfile @@ -73,7 +73,7 @@ zephyr *flags='-b esp32_devkitc_wroom/esp32/procpu': [group('exec')] [doc('Flash/execute platform')] -flash platform program *flags: +flash platform program="upload.wasm" *flags: just _flash_{{platform}} {{program}} {{flags}} _flash_zephyr program *flags: From 260dd008cf6e2525815cea19a01ea856acdb13db Mon Sep 17 00:00:00 2001 From: Tom Lauwaerts Date: Thu, 9 Jul 2026 18:27:37 +0200 Subject: [PATCH 3/6] Fix test command in README --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 85fd0a8a..ad208d65 100644 --- a/README.md +++ b/README.md @@ -205,11 +205,11 @@ make flash Or simply run `idf.py flash`. -## WebAssembly Specification tests +## Run test suites ```shell -cd tests/latch -npm run spectest +just build emulator +just test all ``` ## Technical support and feedback From 06f734f027058a94a4a5c9565e0ac6caf5e3da61 Mon Sep 17 00:00:00 2001 From: Tom Lauwaerts Date: Mon, 13 Jul 2026 08:53:36 +0200 Subject: [PATCH 4/6] Extend justfile --- README.md | 13 +++++++++---- justfile | 30 +++++++++++++++++++++++------- 2 files changed, 32 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index ad208d65..a316bf6b 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,12 @@ To run the virtual machine locally (emulator) for the first time, use: just setup emulator ; just run emulator tutorials/wat/main/fac.wat ``` +You can use the debugger by running: + +```bash +just monitor emulator 8119 +``` + ## Build and Development Instructions > [!NOTE] @@ -71,7 +77,7 @@ The WARDuino VM can be compiled with both the Arduino and ESP-IDF toolchains, an First, install the [Zephyr SDK](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#getting-started-guide), then run: ```bash -just build zephyr tutorials/wat/main/blink.wat ; just flash zephyr +just build zephyr tutorials/wat/main/blink.wat ; just flash zephyr ; just monitor zephyr ``` Alternative, when you do not have just, you can follow the following steps: @@ -144,7 +150,6 @@ arduino-cli lib install --git-url https://github.com/me-no-dev/AsyncTCP.git If you haven't done so already, clone (or symlink) this repository to `~/Arduino/libraries` to make WARDuino available to Arduino. - After this initial installation steps you can start using WARDuino with the Arduino toolchain. You can upload the example file as follows, starting from the project root: @@ -207,7 +212,7 @@ Or simply run `idf.py flash`. ## Run test suites -```shell +```bash just build emulator just test all ``` @@ -218,7 +223,7 @@ For a feature request or bug report, create a [GitHub issue](https://github.com/ ## Acknowledgments -WARDuino by Robbert Gurdeep Singh, Tom Lauwaerts, Carlos Rojas Castillo, Maarten Steevens and Christophe Scholliers is licensed under a [MPL-2.0 License](./LICENSE). +WARDuino by Tom Lauwaerts, Maarten Steevens, Carlos Rojas Castillo, and Christophe Scholliers is licensed under a [MPL-2.0 License](./LICENSE). An early version of this work was derived from [kanaka/wac](https://github.com/kanaka/wac) by Joel Martin. If you need to cite WARDuino in your research, use: diff --git a/justfile b/justfile index 9a44b58d..eb8f22cf 100644 --- a/justfile +++ b/justfile @@ -12,6 +12,7 @@ run platform program: just stage {{program}} just build {{platform}} just flash {{platform}} upload.wasm + just monitor {{platform}} ## Stage @@ -79,7 +80,7 @@ flash platform program="upload.wasm" *flags: _flash_zephyr program *flags: just _zephyr "west flash {{flags}}" -_flash_emulator program *flags: (cli program flags) +_flash_emulator program *flags='--socket 8119': (cli program flags) [group('exec')] [doc('Run command-line interface')] @@ -87,48 +88,63 @@ cli program *flags: ./build-emu/wdcli {{program}} {{flags}} +## Monitor + +monitor platform port='8119': + just _monitor_{{platform}} {{port}} + +[no-exit-message] +_monitor_emulator port='8119': + telnet localhost {{port}} + + +_monitor_zephyr port: + west espressif monitor + + ## Setup [group('setup')] [doc('Setup toolchains & platforms')] setup platform: _setup-emulator +[confirm('You are about to install nanopb using Homebrew. Proceed? [y/n]')] +_nanopb: + brew install nanopb + [group('setup')] [doc('Setup: emulator')] -_setup-emulator: +_setup-emulator: _nanopb git submodule update --init --recursive [group('lint')] [doc('Lint src folder')] +[no-exit-message] lint: clang-format -i src/**/* ## Tests [group('test')] -[doc('Run tests')] +[doc('Run tests at level (unit, integration, spec, all)')] test level='all': just {{level}} [group('test')] -[doc('Run unit tests')] unit: _mkdir-doctest _build-doctest ctest --test-dir ./build-doctest --output-on-failure [group('test')] -[doc('Run spec tests')] [working-directory: 'tests/latch/'] spec: WABT="../../lib/wabt/build/" npm run tests:spec [group('test')] -[doc('Run integration tests')] [working-directory: 'tests/latch/'] integration: WABT="../../lib/wabt/build/" npm run tests:integration [group('test')] -[doc('Run integration tests')] [working-directory: 'tests/latch/'] all: WABT="../../lib/wabt/build/" npm run tests:all From 8663761bdafb8235b4fff0c4505e3e57e1150015 Mon Sep 17 00:00:00 2001 From: Tom Lauwaerts Date: Tue, 11 Aug 2026 07:20:08 +0200 Subject: [PATCH 5/6] Add git hygiene to justfile --- justfile | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/justfile b/justfile index eb8f22cf..2950b7fc 100644 --- a/justfile +++ b/justfile @@ -35,6 +35,12 @@ wat program: clean: rm -rf build-emu build-doctest build +[group('clean')] +[doc('Reset repo (warn: aggresive)')] +[confirm("Hard reset repository?")] +reset: clean prune + + ## Build has(flags, flag) := if flags =~ ('(^| )' + flag + '($| )') { "true" } else { "false" } @@ -149,6 +155,20 @@ integration: all: WABT="../../lib/wabt/build/" npm run tests:all +## QoL / Maintenance + +[group('maintenance')] +maintain: + git maintenance run + +[group('maintenance')] +[doc('Aggressive GC for git (use wisely)')] +[confirm("GC git and delete stale files?")] +prune: + git maintenance run --task=gc + git remote prune origin + + ## Private recipes # make build folder From 4d2ecba65f2e5abf12610fe9d5ff8a6834302cf3 Mon Sep 17 00:00:00 2001 From: Tom Lauwaerts Date: Tue, 11 Aug 2026 08:51:54 +0200 Subject: [PATCH 6/6] Improve justfile --- justfile | 43 ++++++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/justfile b/justfile index 2950b7fc..b6c002c2 100644 --- a/justfile +++ b/justfile @@ -1,7 +1,5 @@ set unstable - -default: - just --list +set default-list := true ## Run @@ -36,9 +34,14 @@ clean: rm -rf build-emu build-doctest build [group('clean')] -[doc('Reset repo (warn: aggresive)')] -[confirm("Hard reset repository?")] -reset: clean prune +[doc('Clean tests folders')] +clean-tests: + rm -rf tests/latch/node-modules + +[group('clean')] +[doc("Hard reset repository")] +[confirm("Clean all generated files and Git data?")] +reset: clean clean-tests _prune ## Build @@ -66,9 +69,9 @@ build platform *flags: [group('build')] [working-directory: 'build-emu'] [doc('Platform: emulator')] -emulator *flags: _mkdir-emu - cmake .. -D BUILD_EMULATOR=ON {{cmake(flags)}} -G Ninja - ninja +emulator *flags: + cmake -S . -B build-emu -D BUILD_EMULATOR=ON {{cmake(flags)}} -G Ninja + cmake --build build-emu [group('build')] [doc('Platform: zephyr')] @@ -96,6 +99,7 @@ cli program *flags: ## Monitor +[group('monitor')] monitor platform port='8119': just _monitor_{{platform}} {{port}} @@ -111,8 +115,9 @@ _monitor_zephyr port: ## Setup [group('setup')] -[doc('Setup toolchains & platforms')] -setup platform: _setup-emulator +[doc('Setup toolchains & platforms (target: emulator, tests)')] +setup target: + just _setup-{{target}} [confirm('You are about to install nanopb using Homebrew. Proceed? [y/n]')] _nanopb: @@ -123,6 +128,10 @@ _nanopb: _setup-emulator: _nanopb git submodule update --init --recursive +[working-directory: 'tests/latch/'] +_setup-tests: + npm i + [group('lint')] [doc('Lint src folder')] [no-exit-message] @@ -155,26 +164,26 @@ integration: all: WABT="../../lib/wabt/build/" npm run tests:all + ## QoL / Maintenance [group('maintenance')] +[doc('Run routine Git maintenance')] maintain: git maintenance run [group('maintenance')] -[doc('Aggressive GC for git (use wisely)')] +[doc('Aggressively prune Git objects and stale remote refs')] [confirm("GC git and delete stale files?")] -prune: +prune: _prune + +_prune: git maintenance run --task=gc git remote prune origin ## Private recipes -# make build folder -_mkdir-emu: - mkdir -p build-emu - # make build folder _mkdir-doctest: mkdir -p build-doctest