From d52ef0402a672b5a131fb34f667e71845a66105e Mon Sep 17 00:00:00 2001
From: Chris Fallin <chris@cfallin.org>
Date: Fri, 26 Jul 2024 14:36:36 -0700
Subject: [PATCH] SpiderMonkey CMake package: use alternate artifacts if
 specified.

When developing StarlingMonkey using an existing SpiderMonkey build with
no SM changes, it is very convenient to download and use pre-built
artifacts for SM from the CI on `spidermonkey-wasi-embedding`, and we do
not want to lose this convenience or approachability.

However, when modifying SpiderMonkey itself, it is nearly impossible to
do development with the current setup: the debug loop requires merging
changes to `gecko-dev` with one PR, updating the hash in
`spidermonkey-wasi-embedding` with another PR, getting both merged
and waiting for the build in CI before StarlingMonkey can use the
new engine.

Rather than require a local hack for such cases, this modifies the
SpiderMonkey CMake module to recognize a `SPIDERMONKEY_BINARIES`
environment variable, and use artifacts there instead. This allows the
developer to point this to a local clone of
`spidermonkey-wasi-embedding` with a modified `gecko-dev`, rebuilt with
`rebuild.sh` as needed. The `README` is updated with details on how to
use this.
---
 README.md                | 52 ++++++++++++++++++++++++++++++++++++++++
 cmake/spidermonkey.cmake | 21 ++++++++++++----
 2 files changed, 68 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 5929d292..a6f509df 100644
--- a/README.md
+++ b/README.md
@@ -160,3 +160,55 @@ name of one of the directories. Currently, only an implementation in terms of [w
 (host-apis/wasi-0.2.0) is provided, and used by default.
 
 To provide a custom host API implementation, you can set `HOST_API` to the (absolute) path of a directory containing that implementation.
+
+## Developing Changes to SpiderMonkey
+
+StarlingMonkey uses SpiderMonkey as its underlying JS engine, and by default,
+downloads build artifacts from [a wrapper
+repository](https://github.com/bytecodealliance/spidermonkey-wasi-embedding)
+around [our local SpiderMonkey
+tree](https://github.com/bytecodealliance/gecko-dev). That wrapper repository
+contains a SpiderMonkey commit-hash in a file, and its CI jobs build the
+artifacts that StarlingMonkey downloads during its build.
+
+This flow is optimized for ease of development of StarlingMonkey, and avoiding
+the need to build SpiderMonkey locally, which requires some additional tools
+and is resource-intensive. However, sometimes it is necessary or desirable to
+make modifications to SpiderMonkey directly, whether to make fixes or optimize
+performance.
+
+In order to do so, first clone the above two repositories, with `gecko-dev`
+(SpiderMonkey itself) as a subdirectory to `spidermonkey-wasi-embedding`:
+
+```shell
+git clone https://github.com/bytecodealliance/spidermonkey-wasi-embedding
+cd spidermonkey-wasi-embedding/
+git clone https://github.com/bytecodealliance/gecko-dev
+```
+
+and switch to the commit that we are currently using:
+
+```shell
+git checkout `cat ../gecko-revision`
+# now edit the source
+```
+
+Then make changes as necessary, eventually rebuilding from the
+`spidermonkey-wasi-embedding` root:
+
+```shell
+cd ../ # back to spidermonkey-wasi-embedding
+./rebuild.sh release
+```
+
+This will produce a `release/` directory with artifacts of the same form
+normally downloaded by StarlingMonkey. So, finally, from within StarlingMonkey,
+set an environment variable `SPIDERMONKEY_BINARIES`:
+
+```shell
+export SPIDERMONKEY_BINARIES=/path/to/spidermonkey-wasi-embedding/release
+cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
+cmake --build cmake-build-release --parallel 8
+```
+
+and use/test as above.
diff --git a/cmake/spidermonkey.cmake b/cmake/spidermonkey.cmake
index 475a358a..5a5dee84 100644
--- a/cmake/spidermonkey.cmake
+++ b/cmake/spidermonkey.cmake
@@ -6,12 +6,23 @@ else()
     set(SM_BUILD_TYPE release)
 endif()
 
-CPMAddPackage(NAME spidermonkey-${SM_BUILD_TYPE}
-        URL https://github.com/bytecodealliance/spidermonkey-wasi-embedding/releases/download/rev_${SM_REV}/spidermonkey-wasm-static-lib_${SM_BUILD_TYPE}.tar.gz
-        DOWNLOAD_ONLY YES
-)
+# If the developer has specified an alternate local set of SpiderMonkey
+# artifacts, use them. This allows for local/in-tree development without
+# requiring a roundtrip through GitHub CI.
+#
+# This can be set, for example, to the output directly (`release/` or `debug/`)
+# under a local clone of the `spidermonkey-wasi-embedding` repo.
+if (DEFINED ENV{SPIDERMONKEY_BINARIES})
+    set(SM_SOURCE_DIR $ENV{SPIDERMONKEY_BINARIES})
+else()
+    CPMAddPackage(NAME spidermonkey-${SM_BUILD_TYPE}
+            URL https://github.com/bytecodealliance/spidermonkey-wasi-embedding/releases/download/rev_${SM_REV}/spidermonkey-wasm-static-lib_${SM_BUILD_TYPE}.tar.gz
+            DOWNLOAD_ONLY YES
+    )
+
+    set(SM_SOURCE_DIR ${CPM_PACKAGE_spidermonkey-${SM_BUILD_TYPE}_SOURCE_DIR} CACHE STRING "Path to spidermonkey ${SM_BUILD_TYPE} build" FORCE)
+endif()
 
-set(SM_SOURCE_DIR ${CPM_PACKAGE_spidermonkey-${SM_BUILD_TYPE}_SOURCE_DIR} CACHE STRING "Path to spidermonkey ${SM_BUILD_TYPE} build" FORCE)
 set(SM_INCLUDE_DIR ${SM_SOURCE_DIR}/include)
 
 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/null.cpp "")