Justfile

.github/workflows/test.yml

@@ -80,7 +80,7 @@ jobs:
         working-directory: tests/latch/
 
       - name: Run Latch
-        run: npm run spectest
+        run: npm run tests:spec
         working-directory: tests/latch/
 
   # Stage 3: end-to-end testing of primitives and debugger
@@ -135,7 +135,7 @@ jobs:
         working-directory: tests/latch/
 
       - name: Run Latch
-        run: npm run primtest
+        run: npm run tests:prim
         working-directory: tests/latch/
 
   debugtests:
@@ -188,6 +188,6 @@ jobs:
         working-directory: tests/latch/
 
       - name: Run Latch
-        run: npm run debugtest
+        run: npm run tests:debug
         working-directory: tests/latch/
 

README.md

@@ -36,6 +36,15 @@ This project is released under the Mozilla Public License 2.0, and is being deve
 > [!WARNING]
 > WARDuino is not 1.0, since this is an active research project. Expect possible bugs or performance issues.
 
+## Quick start
+
+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
+```
+
 ## Build and Development Instructions
 
 > [!NOTE]

justfile

@@ -0,0 +1,157 @@
+set unstable
+
+default:
+    just --list
+
+
+## Run
+
+[group('run')]
+[doc('Run program on any platform (rebuilds)')]
+run platform program:
+    just stage {{program}}
+    just build {{platform}}
+    just flash {{platform}} upload.wasm
+
+
+## Stage
+
+[group('stage')]
+[doc('Stage program as .wasm')]
+stage program: (wat program)
+
+
+[group('stage')]
+[doc('Compile target .wat file to .wasm')]
+wat program:
+  wat2wasm --no-canonicalize-leb128s --disable-bulk-memory --debug-names -v -o upload.wasm {{program}}
+
+
+## Clean
+
+[group('clean')]
+[doc('Clean build folders')]
+clean:
+    rm -rf build-emu build-doctest build
+
+## Build
+
+has(flags, flag) := if flags =~ ('(^| )' + flag + '($| )') { "true" } else { "false" }
+
+extract(flags) := trim(
+  (if has(flags, "debug") == "true" { "-DDEBUG" } else { "" }) + " " +
+  (if has(flags, "trace") == "true" { "-DTRACE" } else { "" })
+)
+
+cmake(flags) := (
+    if extract(flags) == "" {
+      ""
+    } else {
+      '-DCMAKE_CXX_FLAGS="' + extract(flags) + '"'
+    }
+)
+
+[group('build')]
+[doc('Build runtime for any platform (flags: debug, trace)')]
+build platform *flags:
+    just {{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
+
+[group('build')]
+[doc('Platform: zephyr')]
+zephyr *flags='-b esp32_devkitc_wroom/esp32/procpu': 
+    just _zephyr "west build {{flags}}"
+
+
+## Flash
+
+[group('exec')]
+[doc('Flash/execute platform')]
+flash platform program *flags:
+    just _flash_{{platform}} {{program}} {{flags}}
+
+_flash_zephyr program *flags:
+    just _zephyr "west flash {{flags}}"
+
+_flash_emulator program *flags: (cli program flags)
+
+[group('exec')]
+[doc('Run command-line interface')]
+cli program *flags:
+    ./build-emu/wdcli {{program}} {{flags}}
+
+
+## Setup
+
+[group('setup')]
+[doc('Setup toolchains & platforms')]
+setup platform: _setup-emulator
+
+[group('setup')]
+[doc('Setup: emulator')]
+_setup-emulator:
+    git submodule update --init --recursive
+
+[group('lint')]
+[doc('Lint src folder')]
+lint:
+    clang-format -i src/**/*
+
+## Tests
+
+[group('test')]
+[doc('Run tests')]
+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
+
+# make build folder
+_mkdir-doctest:
+    mkdir -p build-doctest
+
+_build-doctest:
+    cmake -B ./build-doctest -D BUILD_UNITTEST=ON -G Ninja
+    cmake --build ./build-doctest 2>/dev/null
+
+# activate zephyr environment and run a command in it
+[working-directory: 'platforms/Zephyr']
+[script("bash")]
+_zephyr +cmd:
+    set -euo pipefail
+    source ~/zephyrproject/.venv/bin/activate
+    source ~/zephyrproject/zephyr/zephyr-env.sh
+    {{cmd}}

tests/latch/package.json

@@ -2,10 +2,12 @@
   "name": "warduino-testsuite",
   "version": "1.0.0",
   "scripts": {
-    "debugtest": "npx ts-node ./src/debugger.test.ts",
-    "primtest": "npx ts-node ./src/primitives.test.ts",
-    "spectest": "npx ts-node ./src/spec.test.ts",
-    "comptest": "npx ts-node ./src/comp.test.ts"
+    "tests:debug": "npx ts-node ./src/debugger.test.ts",
+    "tests:prim": "npx ts-node ./src/primitives.test.ts",
+    "tests:spec": "npx ts-node ./src/spec.test.ts",
+    "tests:comp": "npx ts-node ./src/comp.test.ts",
+    "tests:integration": "npm run tests:debug ; npm run tests:prim",
+    "tests:all": "npm run tests:spec ; npm run tests:integration"
   },
   "devDependencies": {
     "latch": "file:./latch-0.6.0.tgz",