Make starling.wasm a usable component, and document it as such (#161)

This changes the current `starling.wasm` build target to instead be called `starling-raw.wasm` to reflect that it's not yet a usable thing. Additionally, the current `runtime-eval` target is renamed to `starling` and produces a new `starling.wasm` file, which this time is a component that can be used to run dynamically loaded code. I also updated the documentation accordingly. And finally, I fixed a bug in `CMakeLists.txt` introduced in #151 that broke the `runtime-eval` build target. That's the entire reason I fell down this rabbit hole 😬 Signed-off-by: Till Schneidereit <[email protected]>
bytecodealliance · Oct 18, 2024 · 114208c · 114208c
1 parent 72ee41c
commit 114208c
Show file tree

Hide file tree

Showing 7 changed files with 52 additions and 26 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -48,7 +48,7 @@ if (ENABLE_WPT)
     include("tests/wpt-harness/wpt.cmake")
 endif()
 
-add_executable(starling.wasm
+add_executable(starling-raw.wasm
         runtime/js.cpp
         runtime/allocator.cpp
         runtime/encode.cpp
@@ -65,31 +65,31 @@ option(USE_WASM_OPT "use wasm-opt to optimize the StarlingMonkey binary" ON)
 if (USE_WASM_OPT)
     if (CMAKE_BUILD_TYPE STREQUAL "Release")
         add_custom_command(
-                TARGET starling.wasm
+                TARGET starling-raw.wasm
                 POST_BUILD
-                COMMAND ${WASM_OPT} --strip-debug -O3 -o starling.wasm starling.wasm
+                COMMAND ${WASM_OPT} --strip-debug -O3 -o starling-raw.wasm starling-raw.wasm
                 WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         )
     elseif (CMAKE_BUILD_TYPE STREQUAL "RelWithDebInfo")
         add_custom_command(
-                TARGET starling.wasm
+                TARGET starling-raw.wasm
                 POST_BUILD
-                COMMAND ${WASM_OPT} -O3 -g -o starling.wasm starling.wasm
+                COMMAND ${WASM_OPT} -O3 -g -o starling-raw.wasm starling-raw.wasm
                 WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         )
     endif()
 else()
     if (CMAKE_BUILD_TYPE STREQUAL "Release")
         add_custom_command(
-            TARGET starling.wasm
+            TARGET starling-raw.wasm
             POST_BUILD
-            COMMAND ${WASM_OPT} --strip-debug -O0 -o starling.wasm starling.wasm
+            COMMAND ${WASM_OPT} --strip-debug -O0 -o starling-raw.wasm starling-raw.wasm
             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         )
     endif()
 endif()
 
-target_link_libraries(starling.wasm PRIVATE host_api extension_api builtins spidermonkey rust-url)
+target_link_libraries(starling-raw.wasm PRIVATE host_api extension_api builtins spidermonkey rust-url)
 
 # build a compilation cache of ICs
 if(WEVAL)
@@ -100,8 +100,8 @@ if(WEVAL)
         ALL
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         COMMAND rm -f starling-ics.wevalcache
-        COMMAND echo ./null.js | ${WEVAL_BIN} weval --dir . --show-stats --cache starling-ics.wevalcache -w -i starling.wasm -o /dev/null
-        DEPENDS starling.wasm
+        COMMAND echo ./null.js | ${WEVAL_BIN} weval --dir . --show-stats --cache starling-ics.wevalcache -w -i starling-raw.wasm -o /dev/null
+        DEPENDS starling-raw.wasm
         VERBATIM
     )
     set(WEVAL_CACHE_FILE "starling-ics.wevalcache")
@@ -110,7 +110,7 @@ else()
     set(AOT 0)
 endif()
 
-set(RUNTIME_FILE "starling.wasm")
+set(RUNTIME_FILE "starling-raw.wasm")
 set(ADAPTER_FILE "preview1-adapter.wasm")
 configure_file("componentize.sh" "${CMAKE_CURRENT_BINARY_DIR}/componentize.sh" @ONLY)
 configure_file(${ADAPTER} "${CMAKE_CURRENT_BINARY_DIR}/${ADAPTER_FILE}" COPYONLY)
@@ -123,19 +123,19 @@ function(componentize OUTPUT)
     cmake_parse_arguments(ARG "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
     list(TRANSFORM ARG_SOURCES PREPEND ${CMAKE_CURRENT_SOURCE_DIR}/)
     list(JOIN ARG_SOURCES " " SOURCES)
-    get_target_property(RUNTIME_DIR starling.wasm BINARY_DIR)
+    get_target_property(RUNTIME_DIR starling-raw.wasm BINARY_DIR)
 
     add_custom_command(
             OUTPUT ${OUTPUT}.wasm
             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-            COMMAND ${CMAKE_COMMAND} ${RUNTIME_DIR}/componentize.sh ${SOURCES} -o ${OUTPUT}.wasm
-            DEPENDS ${ARG_SOURCES} ${RUNTIME_DIR}/componentize.sh starling.wasm
+            COMMAND ${RUNTIME_DIR}/componentize.sh ${SOURCES} -o ${OUTPUT}.wasm
+            DEPENDS ${ARG_SOURCES} ${RUNTIME_DIR}/componentize.sh starling-raw.wasm
             VERBATIM
     )
     add_custom_target(${OUTPUT} DEPENDS ${OUTPUT}.wasm)
 endfunction()
 
 componentize(smoke-test SOURCES tests/cases/smoke/smoke.js)
-componentize(runtime-eval)
+componentize(starling)
 
 include("tests/tests.cmake")
diff --git a/README.md b/README.md
@@ -58,13 +58,39 @@ cmake -S . -B cmake-build-debug -DCMAKE_BUILD_TYPE=Debug
 
 3. Build the runtime
 
-The following command will build the `starling.wasm` runtime module in the `cmake-build-release` directory:
+Building the runtime is done in two phases: first, cmake is used to build a raw version as a WebAssembly core module. Then, that module is turned into a [WebAssembly Component](https://component-model.bytecodealliance.org/) using the `componentize.sh` script.
+
+The following command will build the `starling-raw.wasm` runtime module in the `cmake-build-release` directory:
 ```bash
 # Use cmake-build-debug for the debug build
 # Change the value for `--parallel` to match the number of CPU cores in your system
 cmake --build cmake-build-release --parallel 8
 ```
 
+Then, the `starling-raw.wasm` module can be turned into a component with the following command:
+
+```bash
+cd cmake-build-release
+./componentize.sh -o starling.wasm
+```
+
+The resulting runtime can be used to load and evaluate JS code dynamically:
+
+```bash
+wasmtime -S http starling.wasm -e "console.log('hello world')"
+# or, to load a file:
+wasmtime -S http --dir . starling.wasm index.js
+```
+
+Alternatively, a JS file can be provided during componentization:
+
+```bash
+cd cmake-build-release
+./componentize.sh index.js -o starling.wasm
+```
+
+This way, the JS file will be loaded during componentization, and the top-level code will be executed, and can e.g. register a handler for the `fetch` event to serve HTTP requests.
+
 4. Testing the build 
 
 After completing the build (a debug build in this case), the integration test runner can be built:
@@ -145,7 +171,7 @@ include("${PATH_TO_STARLING_MONKEY}/cmake/add_as_subproject.cmake")
 
 With that line added (and `${PATH_TO_STARLING_MONKEY}` replaced with the actual path to StarlingMonkey), the importing project will have all the build targets of StarlingMonkey available to it.
 
-Note that building the `starling.wasm` target itself will result in the linked `starling.wasm` file being created in the `starling.wasm` sub-directory of the importing project's build directory.
+Note that building the `starling-raw.wasm` target itself will result in the linked `starling-raw.wasm` file being created in the `starling-raw.wasm` sub-directory of the importing project's build directory.
 
 To make use of importing StarlingMonkey in this way, you'll probably want to add additional builtins, or provide your own implementation of the host interface.
 

diff --git a/cmake/add_as_subproject.cmake b/cmake/add_as_subproject.cmake
@@ -3,7 +3,7 @@
 
 cmake_minimum_required(VERSION 3.27 FATAL_ERROR)
 
-add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/.." ${CMAKE_BINARY_DIR}/starling.wasm)
+add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/.." ${CMAKE_BINARY_DIR}/starling-raw.wasm)
 
 set(PATH_BACKUP CMAKE_MODULE_PATH)
 set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}")

diff --git a/componentize.sh b/componentize.sh
@@ -93,15 +93,15 @@ if [[ -n "$IN_FILE" ]]; then
            --cache-ro "$(dirname "$0")/starling-ics.wevalcache" \
            $WEVAL_VERBOSE \
            -o "$OUT_FILE" \
-           -i "$(dirname "$0")/starling.wasm"
+           -i "$(dirname "$0")/starling-raw.wasm"
   else
       echo "$STARLING_ARGS" | WASMTIME_BACKTRACE_DETAILS=1 $wizer --allow-wasi --wasm-bulk-memory true \
            --inherit-stdio true --inherit-env true $preopen_dir -o "$OUT_FILE" \
-           -- "$(dirname "$0")/starling.wasm"
+           -- "$(dirname "$0")/starling-raw.wasm"
   fi
 else
   echo "Creating runtime-eval component $OUT_FILE"
-  cp "$(dirname "$0")/starling.wasm" "$OUT_FILE"
+  cp "$(dirname "$0")/starling-raw.wasm" "$OUT_FILE"
 fi
 
 $wasm_tools component new -v --adapt "wasi_snapshot_preview1=$(dirname "$0")/preview1-adapter.wasm" --output "$OUT_FILE" "$OUT_FILE"
diff --git a/include/config-parser.h b/include/config-parser.h
@@ -37,7 +37,7 @@ class ConfigParser {
    * program name, so all the examples for the other `apply_args` overload apply here, too.
    */
   ConfigParser *apply_args(std::string_view args_string) {
-    std::vector<std::string_view> args = { "starling.wasm" };
+    std::vector<std::string_view> args = { "starling-raw.wasm" };
     char last = '\0';
     bool in_quotes = false;
     size_t slice_start = 0;

diff --git a/tests/tests.cmake b/tests/tests.cmake
@@ -6,7 +6,7 @@ include("wasmtime")
 include("weval")
 
 function(test_e2e TEST_NAME)
-    get_target_property(RUNTIME_DIR starling.wasm BINARY_DIR)
+    get_target_property(RUNTIME_DIR starling-raw.wasm BINARY_DIR)
     add_test(e2e-${TEST_NAME} ${BASH_PROGRAM} ${CMAKE_SOURCE_DIR}/tests/test.sh ${RUNTIME_DIR} ${CMAKE_SOURCE_DIR}/tests/e2e/${TEST_NAME})
     set_property(TEST e2e-${TEST_NAME} PROPERTY ENVIRONMENT "WASMTIME=${WASMTIME};WIZER=${WIZER_DIR}/wizer;WASM_TOOLS=${WASM_TOOLS_DIR}/wasm-tools")
     set_tests_properties(e2e-${TEST_NAME} PROPERTIES TIMEOUT 120)
@@ -15,13 +15,13 @@ endfunction()
 add_custom_target(integration-test-server DEPENDS test-server.wasm)
 
 function(test_integration TEST_NAME)
-    get_target_property(RUNTIME_DIR starling.wasm BINARY_DIR)
+    get_target_property(RUNTIME_DIR starling-raw.wasm BINARY_DIR)
 
     add_custom_command(
         OUTPUT test-server.wasm
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         COMMAND ${CMAKE_COMMAND} -E env "WASM_TOOLS=${WASM_TOOLS_DIR}/wasm-tools" env "WIZER=${WIZER_DIR}/wizer" env "PREOPEN_DIR=${CMAKE_SOURCE_DIR}/tests" ${RUNTIME_DIR}/componentize.sh ${CMAKE_SOURCE_DIR}/tests/integration/test-server.js test-server.wasm
-        DEPENDS ${ARG_SOURCES} ${RUNTIME_DIR}/componentize.sh starling.wasm
+        DEPENDS ${ARG_SOURCES} ${RUNTIME_DIR}/componentize.sh starling-raw.wasm
         VERBATIM
     )
 

diff --git a/tests/wpt-harness/wpt.cmake b/tests/wpt-harness/wpt.cmake
@@ -29,7 +29,7 @@ add_custom_command(
         OUTPUT wpt-runtime.wasm
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         COMMAND ${CMAKE_COMMAND} -E env PATH=${WASM_TOOLS_DIR}:${WIZER_DIR}:$ENV{PATH} env "COMPONENTIZE_FLAGS=${COMPONENTIZE_FLAGS}" WPT_ROOT=${WPT_ROOT} ${CMAKE_CURRENT_SOURCE_DIR}/tests/wpt-harness/build-wpt-runtime.sh
-        DEPENDS starling.wasm componentize.sh tests/wpt-harness/build-wpt-runtime.sh tests/wpt-harness/pre-harness.js tests/wpt-harness/post-harness.js
+        DEPENDS starling-raw.wasm componentize.sh tests/wpt-harness/build-wpt-runtime.sh tests/wpt-harness/pre-harness.js tests/wpt-harness/post-harness.js
         VERBATIM
 )