diff --git a/README.md b/README.md index 6a059cc2..3b8e4de7 100644 --- a/README.md +++ b/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. diff --git a/justfile b/justfile new file mode 100644 index 00000000..984c746b --- /dev/null +++ b/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