Add justfile as a project workflow interface (#180)

README.md

@@ -159,6 +159,78 @@ cmake -P [PATH_TO_STARLING_MONKEY]/cmake/builtins.cmake
 
 Note that it's required to include builtins defining all exports defined by the used host API. Using the default WASI 0.2.0 host API, that means including the `fetch_event` builtin.
 
+### Running project-specific commands using `just`
+
+The justfile provides a streamlined interface for executing common project-specific tasks. To install just, you can use the command `cargo install just` or `cargo binstall just`. Alternatively, refer to the official [installation instructions](https://github.com/casey/just?tab=readme-ov-file#installation) for your specific system.
+
+Once installed, navigate to the project directory and run `just` commands as needed. For instance, the following commands will configure a default `cmake-build-debug` directory and build the project.
+
+``` shell
+just build
+```
+
+To build and run integration tests run:
+
+``` shell
+just test
+```
+
+To build and run Web Platform Tests run:
+
+``` shell
+just wpt-test # run all tests
+just wpt-test console/console-log-symbol.any.js # run specific test
+```
+
+To view a complete list of available recipes, run:
+
+``` shell
+just --list
+
+```
+
+> [!NOTE]
+> By default, the CMake configuration step is skipped if the build directory already exists. However, this can sometimes cause issues if the existing build directory was configured for a different target. For instance:
+> - Running `just build` creates a build directory for the default target,
+> - Running `just wpt-build` afterward may fail because the WPT target hasn’t been configured in the existing build directory.
+>
+> To resolve this, you can force cmake to reconfigure the build directory by adding the `reconfigure=true` parameter. For example:
+>
+> ``` shell
+> just reconfigure=true wpt-build
+> ```
+
+#### Customizing build
+The default build mode is debug, which automatically configures the build directory to `cmake-build-debug`. You can switch to a different build mode, such as release, by specifying the mode parameter. For example:
+
+``` shell
+just mode=release build
+```
+
+This command will set the build mode to release, and the build directory will automatically change to `cmake-build-release`.
+
+If you want to override the default build directory, you can use the `builddir` parameter. 
+
+``` shell
+just builddir=mybuilddir mode=release build
+```
+
+This command configures CMake to use `mybuilddir` as the build directory and sets the build mode to `release`.
+
+#### Starting the WPT Server
+You can also start a Web Platform Tests (WPT) server with:
+
+``` shell
+just wpt-server
+```
+
+After starting the server, individual tests can be run by sending a request with the test name to the server instance. For example:
+
+``` shell
+curl http://127.0.0.1:7676/console/console-log-symbol.any.js
+
+```
+
 ### Using StarlingMonkey as a CMake sub-project
 
 StarlingMonkey can be used as a subproject in a larger CMake project.

justfile

@@ -0,0 +1,88 @@
+ncpus := num_cpus()
+justdir := justfile_directory()
+mode := 'debug'
+builddir := justdir / 'cmake-build-' + mode
+reconfigure := 'false'
+
+alias b := build
+alias t := test
+alias w := wpt-test
+alias c := componentize
+alias fmt := format
+
+# List all recipes
+default:
+    @echo 'Default mode {{ mode }}'
+    @echo 'Default build directory {{ builddir }}'
+    @just --list
+
+# Build specified target or all otherwise
+build target="all" flags="":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    echo 'Setting build directory to {{ builddir }}, build type {{ mode }}'
+
+    # Only run configure step if build directory doesn't exist yet
+    if ! {{ path_exists(builddir) }} || {{ reconfigure }} = 'true'; then
+        cmake -S . -B {{ builddir }} {{ flags }} -DCMAKE_BUILD_TYPE={{ capitalize(mode) }}
+    else
+        echo 'build directory already exists, skipping cmake configure'
+    fi
+
+    # Build target
+    cmake --build {{ builddir }} --parallel {{ ncpus }} {{ if target == "" { target } else { "--target " + target } }}
+
+# Run clean target
+clean:
+    cmake --build {{ builddir }} --target clean
+
+[private]
+[confirm('proceed?')]
+do_clean:
+    rm -rf {{ builddir }}
+
+# Remove build directory
+clean-all: && do_clean
+    @echo "This will remove {{builddir}}"
+
+# Componentize js script
+componentize script="" outfile="starling.wasm": build
+    {{ builddir }}/componentize.sh {{ script }} -o {{ outfile }}
+
+# Format code using clang-format. Use --fix to fix files inplace
+format *ARGS:
+    {{ justdir }}/scripts/clang-format.sh {{ ARGS }}
+
+# Run integration test
+test: (build "integration-test-server")
+    ctest --test-dir {{ builddir }} -j {{ ncpus }} --output-on-failure
+
+# Build web platform test suite
+[group('wpt')]
+wpt-build: (build "wpt-runtime" "-DENABLE_WPT:BOOL=ON")
+
+# Run web platform test suite
+[group('wpt')]
+wpt-test filter="": wpt-build
+    WPT_FILTER={{ filter }} ctest --test-dir {{ builddir }} -R wpt --verbose
+
+# Update web platform test expectations
+[group('wpt')]
+wpt-update: wpt-build
+    WPT_FLAGS="--update-expectations" ctest --test-dir {{ builddir }} -R wpt --verbose
+
+# Run wpt server
+[group('wpt')]
+wpt-server: wpt-build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    cd {{ builddir }}
+    wpt_root=$(grep '^CPM_PACKAGE_wpt-suite_SOURCE_DIR:INTERNAL=' CMakeCache.txt | cut -d'=' -f2-)
+
+    echo "Using wpt-suite at ${wpt_root}"
+    WASMTIME_BACKTRACE_DETAILS= node {{ justdir }}/tests/wpt-harness/run-wpt.mjs --wpt-root=${wpt_root} -vv --interactive
+
+# Prepare WPT hosts
+[group('wpt')]
+wpt-setup:
+    cat deps/wpt-hosts | sudo tee -a /etc/hosts