diff --git a/README.md b/README.md index 9eb4a854..a316bf6b 100644 --- a/README.md +++ b/README.md @@ -41,61 +41,46 @@ 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: +```bash +just setup emulator ; just run emulator tutorials/wat/main/fac.wat ``` -just setup ; 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] -> **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 ; just monitor 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 @@ -165,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: @@ -185,6 +169,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 @@ -192,11 +182,39 @@ cmake .. -D BUILD_EMULATOR=ON make ``` -## WebAssembly Specification tests +### 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: -```shell -cd tests/latch -npm run spectest +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`. + +## Run test suites + +```bash +just build emulator +just test all ``` ## Technical support and feedback @@ -205,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 d4e211b5..b6c002c2 100644 --- a/justfile +++ b/justfile @@ -1,7 +1,5 @@ set unstable - -default: - just --list +set default-list := true ## Run @@ -12,6 +10,7 @@ run platform program: just stage {{program}} just build {{platform}} just flash {{platform}} upload.wasm + just monitor {{platform}} ## Stage @@ -34,6 +33,17 @@ wat program: clean: rm -rf build-emu build-doctest build +[group('clean')] +[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 has(flags, flag) := if flags =~ ('(^| )' + flag + '($| )') { "true" } else { "false" } @@ -59,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')] @@ -73,13 +83,13 @@ 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: 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,57 +97,92 @@ cli program *flags: ./build-emu/wdcli {{program}} {{flags}} +## Monitor + +[group('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 +[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: + brew install nanopb [group('setup')] [doc('Setup: emulator')] -_setup-emulator: +_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] 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 -## Private recipes -# make build folder -_mkdir-emu: - mkdir -p build-emu +## QoL / Maintenance + +[group('maintenance')] +[doc('Run routine Git maintenance')] +maintain: + git maintenance run + +[group('maintenance')] +[doc('Aggressively prune Git objects and stale remote refs')] +[confirm("GC git and delete stale files?")] +prune: _prune + +_prune: + git maintenance run --task=gc + git remote prune origin + + +## Private recipes # make build folder _mkdir-doctest: