From 4a3e6e8f21593f2adba1464fc348af4a4c66825f Mon Sep 17 00:00:00 2001 From: Tomasz Andrzejak Date: Mon, 2 Dec 2024 20:33:03 +0100 Subject: [PATCH 1/7] Add justfile as a project workflow interface --- justfile | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 justfile diff --git a/justfile b/justfile new file mode 100644 index 00000000..4277a7e5 --- /dev/null +++ b/justfile @@ -0,0 +1,83 @@ +ncpus := num_cpus() +justdir := justfile_directory() +flavour := 'debug' +builddir := justdir / 'cmake-build-' + flavour +force := 'false' + +alias b := build +alias t := integration-test +alias w := wpt-test +alias c := componentize +alias fmt := format + +# List all recipes +default: + @echo 'Default flavour {{ flavour }}' + @echo 'Default build directory {{ builddir }}' + @just --list + +# Build specified target or all otherwise +build target="" flags="": + #!/usr/bin/env bash + set -euo pipefail + echo 'Setting build directory to {{ builddir }}, build type {{ flavour }}' + + # Only run configure step if build directory doesn't exist yet + if ! {{ path_exists(builddir) }} || {{ force }} = 'true'; then + cmake -S . -B {{ builddir }} {{ flags }} -DCMAKE_BUILD_TYPE={{ capitalize(flavour) }} + 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 + +# Remove build directory +clean-all: + rm -rf {{ 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 +integration-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 From 6eef5f4d244e14da2d6f20ebf142dc5fa8c521f6 Mon Sep 17 00:00:00 2001 From: Tomasz Andrzejak Date: Wed, 4 Dec 2024 16:40:21 +0100 Subject: [PATCH 2/7] Require confirmation before running clean-all --- justfile | 1 + 1 file changed, 1 insertion(+) diff --git a/justfile b/justfile index 4277a7e5..7f6de29e 100644 --- a/justfile +++ b/justfile @@ -37,6 +37,7 @@ clean: cmake --build {{ builddir }} --target clean # Remove build directory +[confirm] clean-all: rm -rf {{ builddir }} From 9ae1ec7fe92b64d28d1321a74eed2f79414903f7 Mon Sep 17 00:00:00 2001 From: Tomasz Andrzejak Date: Wed, 4 Dec 2024 16:46:48 +0100 Subject: [PATCH 3/7] Print directory to remove --- justfile | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/justfile b/justfile index 7f6de29e..e8763e66 100644 --- a/justfile +++ b/justfile @@ -36,11 +36,15 @@ build target="" flags="": clean: cmake --build {{ builddir }} --target clean -# Remove build directory -[confirm] -clean-all: +[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 }} From acc6b229b56adb7ef7abf01e88984b9e36d6eade Mon Sep 17 00:00:00 2001 From: Tomasz Andrzejak Date: Thu, 5 Dec 2024 16:05:17 +0100 Subject: [PATCH 4/7] Replace force variable with reconfigure --- justfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/justfile b/justfile index e8763e66..16accf62 100644 --- a/justfile +++ b/justfile @@ -2,7 +2,7 @@ ncpus := num_cpus() justdir := justfile_directory() flavour := 'debug' builddir := justdir / 'cmake-build-' + flavour -force := 'false' +reconfigure := 'false' alias b := build alias t := integration-test @@ -23,7 +23,7 @@ build target="" flags="": echo 'Setting build directory to {{ builddir }}, build type {{ flavour }}' # Only run configure step if build directory doesn't exist yet - if ! {{ path_exists(builddir) }} || {{ force }} = 'true'; then + if ! {{ path_exists(builddir) }} || {{ reconfigure }} = 'true'; then cmake -S . -B {{ builddir }} {{ flags }} -DCMAKE_BUILD_TYPE={{ capitalize(flavour) }} else echo 'build directory already exists, skipping cmake configure' From f2df6ad61f59416eef7e735f84672b110442934c Mon Sep 17 00:00:00 2001 From: Tomasz Andrzejak Date: Thu, 5 Dec 2024 16:52:16 +0100 Subject: [PATCH 5/7] Add justfile section in Readme --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/README.md b/README.md index 6a059cc2..b376ac15 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,61 @@ cd cmake-build-release ./componentize.sh ../tests/smoke.js ``` +6. Run 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: + +``` shell +cargo install 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 +``` + +The default build directory (`cmake-build-debug`) and build flavor (`debug`) can be overridden via command-line arguments. For example, the following command configures CMake to use `mybuilddir` as the build directory and sets the build type to `release`: + +``` shell +just builddir=mybuilddir flavour=release build +``` + +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 + +``` + +To view a complete list of available recipes, run: + +``` shell +just --list + +``` + ### Web Platform Tests To run the [Web Platform Tests](https://web-platform-tests.org/) suite, the WPT runner requires `Node.js` to be installed, and during build configuration the option `ENABLE_WPT:BOOL=ON` must be set. From cbe5ca5f071504275cf7b3e0e422e85bfe964b8c Mon Sep 17 00:00:00 2001 From: Tomasz Andrzejak Date: Thu, 5 Dec 2024 21:56:14 +0100 Subject: [PATCH 6/7] Move the justfile readme section --- README.md | 104 ++++++++++++++++++++++++++++++++---------------------- justfile | 16 ++++----- 2 files changed, 69 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index b376ac15..7f3feb91 100644 --- a/README.md +++ b/README.md @@ -124,52 +124,62 @@ cd cmake-build-release ./componentize.sh ../tests/smoke.js ``` -6. Run project-specific commands using `just` +### Web Platform Tests -The justfile provides a streamlined interface for executing common project-specific tasks. To install just, you can use the command: +To run the [Web Platform Tests](https://web-platform-tests.org/) suite, the WPT runner requires `Node.js` to be installed, and during build configuration the option `ENABLE_WPT:BOOL=ON` must be set. -``` shell -cargo install just +```bash +cmake -S . -B cmake-build-debug -DENABLE_WPT:BOOL=ON -DCMAKE_BUILD_TYPE=Debug +cmake --build cmake-build-debug --parallel 8 --target wpt-runtime +cd cmake-build-debug +ctest -R wpt --verbose # Note: some of the tests run fairly slowly in debug builds, so be patient ``` -Alternatively, refer to the official [installation instructions](https://github.com/casey/just?tab=readme-ov-file#installation) for your specific system. +The Web Platform Tests checkout can also be customized by setting the `WPT_ROOT=[path to your WPT checkout]` environment variable to the cmake command. -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. +WPT tests can be filtered with the `WPT_FILTER=string` variable, for example: -``` shell -just build +```bash +WPT_FILTER=fetch ctest -R wpt -v ``` -To build and run integration tests run: +Custom flags can also be passed to the test runner via `WPT_FLAGS="..."`, for example to update expectations use: -``` shell -just test +```bash +WPT_FLAGS="--update-expectations" ctest -R wpt -v ``` -To build and run Web Platform Tests run: +### Configuring available builtins -``` shell -just wpt-test # run all tests -just wpt-test console/console-log-symbol.any.js # run specific test +StarlingMonkey supports enabling/disabling bundled builtins using CMake options. You can get a full list of bundled builtins by running the following shell command: + +```shell +cmake -P [PATH_TO_STARLING_MONKEY]/cmake/builtins.cmake ``` -The default build directory (`cmake-build-debug`) and build flavor (`debug`) can be overridden via command-line arguments. For example, the following command configures CMake to use `mybuilddir` as the build directory and sets the build type to `release`: +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 builddir=mybuilddir flavour=release build +just build ``` -You can also start a Web Platform Tests (WPT) server with: +To build and run integration tests run: ``` shell -just wpt-server +just test ``` -After starting the server, individual tests can be run by sending a request with the test name to the server instance. For example: +To build and run Web Platform Tests run: ``` shell -curl http://127.0.0.1:7676/console/console-log-symbol.any.js - +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: @@ -179,41 +189,49 @@ just --list ``` -### Web Platform Tests - -To run the [Web Platform Tests](https://web-platform-tests.org/) suite, the WPT runner requires `Node.js` to be installed, and during build configuration the option `ENABLE_WPT:BOOL=ON` must be set. +> [!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 +> ``` +> This will ensure that the build directory is correctly configured for the new target. + +#### 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: -```bash -cmake -S . -B cmake-build-debug -DENABLE_WPT:BOOL=ON -DCMAKE_BUILD_TYPE=Debug -cmake --build cmake-build-debug --parallel 8 --target wpt-runtime -cd cmake-build-debug -ctest -R wpt --verbose # Note: some of the tests run fairly slowly in debug builds, so be patient +``` shell +just mode=release build ``` -The Web Platform Tests checkout can also be customized by setting the `WPT_ROOT=[path to your WPT checkout]` environment variable to the cmake command. +This command will set the build mode to release, and the build directory will automatically change to `cmake-build-release`. -WPT tests can be filtered with the `WPT_FILTER=string` variable, for example: +If you want to override the default build directory, you can use the `builddir` parameter. -```bash -WPT_FILTER=fetch ctest -R wpt -v +``` shell +just builddir=mybuilddir mode=release build ``` -Custom flags can also be passed to the test runner via `WPT_FLAGS="..."`, for example to update expectations use: +This command configures CMake to use `mybuilddir` as the build directory and sets the build mode to `release`. -```bash -WPT_FLAGS="--update-expectations" ctest -R wpt -v +#### Starting the WPT Server +You can also start a Web Platform Tests (WPT) server with: + +``` shell +just wpt-server ``` -### Configuring available builtins +After starting the server, individual tests can be run by sending a request with the test name to the server instance. For example: -StarlingMonkey supports enabling/disabling bundled builtins using CMake options. You can get a full list of bundled builtins by running the following shell command: +``` shell +curl http://127.0.0.1:7676/console/console-log-symbol.any.js -```shell -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. - ### 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 index 16accf62..984c746b 100644 --- a/justfile +++ b/justfile @@ -1,30 +1,30 @@ ncpus := num_cpus() justdir := justfile_directory() -flavour := 'debug' -builddir := justdir / 'cmake-build-' + flavour +mode := 'debug' +builddir := justdir / 'cmake-build-' + mode reconfigure := 'false' alias b := build -alias t := integration-test +alias t := test alias w := wpt-test alias c := componentize alias fmt := format # List all recipes default: - @echo 'Default flavour {{ flavour }}' + @echo 'Default mode {{ mode }}' @echo 'Default build directory {{ builddir }}' @just --list # Build specified target or all otherwise -build target="" flags="": +build target="all" flags="": #!/usr/bin/env bash set -euo pipefail - echo 'Setting build directory to {{ builddir }}, build type {{ flavour }}' + 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(flavour) }} + cmake -S . -B {{ builddir }} {{ flags }} -DCMAKE_BUILD_TYPE={{ capitalize(mode) }} else echo 'build directory already exists, skipping cmake configure' fi @@ -54,7 +54,7 @@ format *ARGS: {{ justdir }}/scripts/clang-format.sh {{ ARGS }} # Run integration test -integration-test: (build "integration-test-server") +test: (build "integration-test-server") ctest --test-dir {{ builddir }} -j {{ ncpus }} --output-on-failure # Build web platform test suite From 3d568ba12c376f491089a77c6393bcbffa84356b Mon Sep 17 00:00:00 2001 From: Tomasz Andrzejak Date: Thu, 5 Dec 2024 21:58:22 +0100 Subject: [PATCH 7/7] Make note more concise --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 7f3feb91..3b8e4de7 100644 --- a/README.md +++ b/README.md @@ -194,12 +194,11 @@ just --list > - 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: +> 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 > ``` -> This will ensure that the build directory is correctly configured for the new target. #### 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: